http.async.client documentation

Asynchronous HTTP Client - Clojure

DELETE

(DELETE client url & {:as options})
Sends asynchronously HTTP DELETE request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

GET

(GET client url & {:as options})
Sends asynchronously HTTP GET request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

HEAD

(HEAD client url & {:as options})
Sends asynchronously HTTP HEAD request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

OPTIONS

(OPTIONS client url & {:as options})
Sends asynchronously HTTP OPTIONS request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

PATCH

(PATCH client url & {:as options})
Sends asynchronously HTTP PATCH request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

POST

(POST client url & {:as options})
Sends asynchronously HTTP POST request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

PUT

(PUT client url & {:as options})
Sends asynchronously HTTP PUT request to url.
Returns a map:
- :id      - unique ID of request
- :status  - promise that once status is received is delivered, contains lazy map of:
  - :code     - response code
  - :msg      - response message
  - :protocol - protocol with version
  - :major    - major version of protocol
  - :minor    - minor version of protocol
- :headers - promise that once headers are received is delivered, contains lazy map of:
  - :server - header names are keyworded, values stay not changed
- :body    - body of response, depends on request type, might be ByteArrayOutputStream
             or lazy sequence, use conveniece methods to extract it, like string
- :done    - promise that is delivered once receiving response has finished
- :error   - promise that is delivered if requesting resource failed, once delivered
             will contain Throwable.
Arguments:
- client   - client created via create-client
- url      - URL to request
- options  - keyworded arguments:
  :query   - map of query parameters, if value is vector than multiple values
             will be send as n=v1&n=v2
  :headers - map of headers
  :body    - body
  :cookies - cookies to send
  :proxy   - map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
  :auth    - map with authentication to be used
    :type     - either :basic or :digest
    :user     - user name to be used
    :password - password to be used
    :realm    - realm name to authenticate in
  :timeout - request timeout in ms

await

(await response)
Waits for response processing to be finished.
Returns same response.

body

(body resp)
Gets body.
If body have not yet been delivered and request hasn't failed waits for body.

cancel

(cancel resp)
Cancels response.

cancelled?

(cancelled? resp)
Checks if response has been cancelled.

close

(close client)
Closes client.

content-type

(content-type resp)
Gets content type from response.

cookies

(cookies resp)
Gets cookies from response.

create-client

(create-client & {:keys [compression-enabled connection-timeout follow-redirects remove-params-on-redirect idle-in-pool-timeout keep-alive max-conns-per-host max-conns-total max-redirects proxy auth request-timeout user-agent async-connect executor-service ssl-context]})
Creates new Async Http Client.
Arguments:
- :compression-enabled :: enable HTTP compression
- :connection-timeout :: connections timeout in ms
- :follow-redirects :: enable following HTTP redirects
- :remove-params-on-redirect :: query parameters removed when a redirect occurs
- :idle-in-pool-timeout :: idle connection in pool timeout in ms
- :keep-alive :: enable HTTP keep alive, enabled by default
- :max-conns-per-host :: max number of polled connections per host
- :max-conns-total :: max number of total connections held open by client
- :max-redirects :: max nuber of redirects to follow
- :proxy :: map with proxy configuration to be used
    :host     - proxy host
    :port     - proxy port
    :protocol - (optional) protocol to communicate with proxy,
                :http (default, if you provide no value) and :https are allowed
    :user     - (optional) user name to use for proxy authentication,
                has to be provided with :password
    :password - (optional) password to use for proxy authentication,
                has to be provided with :user
- :auth :: map with authentication to be used
    :type       - either :basic or :digest
    :user       - user name to be used
    :password   - password to be used
    :realm      - realm name to authenticate in
    :preemptive - assume authentication is required
- :request-timeout :: request timeout in ms
- :user-agent :: User-Agent branding string
- :async-connect :: Execute connect asynchronously
- :executor-service :: provide your own executor service for callbacks to be executed on
- :ssl-context :: provide your own SSL Context

create-ws-byte-listener

(create-ws-byte-listener soc f)
Creates WebSocket binary listner.

create-ws-close-listener

(create-ws-close-listener f)
Creates WebSocket close listener.

create-ws-text-listener

(create-ws-text-listener soc f)
Creates WebSocket text listener.

done?

(done? resp)
Checks if request is finished already (response receiving finished).

error

(error resp)
Returns Throwable if request processing failed.

failed?

(failed? resp)
Checks if request failed.

headers

(headers resp)
Gets headers.
If headers have not yet been delivered and request hasn't failed waits for headers.

location

(location resp)
Retrieves location of redirect.

open?

(open? client)
Checks if client is open.

raw-url

(raw-url resp)
Gets raw URL from response

redirect?

(redirect? resp)
Checks if response is redirect.

request-stream

(request-stream client method url body-part-callback & {:as options})
Consumes stream from given url.
method - HTTP method to be used (:get, :post, ...)
url - URL to set request to
body-part-callback - callback that takes status (ref {}) of request
                     and received body part as vector of bytes
options - are optional and can contain :headers, :param, and :query (see prepare-request).

send

(send ws & {text :text, byte :byte})
Send message via WebSocket.

status

(status resp)
Gets status if status was delivered.

stream-seq

(stream-seq client method url & {:as options})
Creates potentially infinite lazy sequence of Http Stream.

string

(string resp)(string headers body)
Converts response to string.
Or converts body taking encoding from response.

url

(url resp)
Gets URL from response

websocket

(websocket client url & {text-cb :text, byte-cb :byte, open-cb :open, close-cb :close, error-cb :error})
Opens WebSocket connection.

ws-lifecycle-listener

(ws-lifecycle-listener ws openf closef errorf)
Registers WebSocketListener to handle lifecycle of WebSocket.

Stores active socket in atom.