API for aleph.http

by Zachary Tellman

Usage:
(ns your-namespace
  (:require aleph.http))

Overview



Public Variables and Functions



http-client

function
Usage: (http-client options)
Returns a function which represents a persistent connection to the server specified by
:url.  The function will take an HTTP request per the Ring spec and optionally a timeout,
and returns a result-channel that will emit the HTTP response.  Redirects will not be
followed.

The connection can be closed using lamina.connections/close-connection.

Requests will only be sent to the server once the response to the previous request has
been received.  To make concurrent requests, open multiple clients.


http-request

function
Usage: (http-request request)
       (http-request request timeout)
Takes an HTTP request structured per the Ring spec, and returns a result-channel
that will emit an HTTP response.  If a timeout is specified and elapses before a
response is received, the result will emit an error.


pipelined-http-client

function
Usage: (pipelined-http-client options)
Returns a function which represents a persistent connection to the server specified by
:url.  The function will take an HTTP request per the Ring spec and optionally a timeout,
and returns a result-channel that will emit the HTTP response.  Redirects will not be
followed.

The connection can be closed using lamina.connections/close-connection.

Requests will be sent to the server as soon as they are made, under the assumption that
responses will be sent in the same order.  This is not always a safe assumption (see
http://en.wikipedia.org/wiki/HTTP_pipelining ), use only where you're sure the underlying
assumptions holds.


request-body->input-stream

function
Usage: (request-body->input-stream request)
Returns a result-channel which will emit the request with an InputStream or nil as the
body.

The result-channel will be immediately realized if the request is not chunked, but if
the request is chunked then synchronously waiting on the result inside the handler will
cause issues.  You may synchronously wait on the result in a different thread, but the
recommended approach is to structure your handler like:

(defn handler [ch request]
  (run-pipeline (request-body->input-stream request)
    (fn [request]
      ... middleware and routing goes here ...)))

or to use the (async ...) macro.


request-client-info

function
Usage: (request-client-info request)
Returns information about the client, based on the 'User-Agent' header in the request.


function
Usage: (request-cookie request)
Returns a hash of the values within the request's cookie.


request-params

function
Usage: (request-params request)
       (request-params request options)
Returns a result-channel representing the merged query and body parameters in the request.

The result-channel will be immediately realized if the request is not chunked, but if the
request is chunked then synchronously waiting on the result inside the handler will cause
issues.  You may synchrously wait on the result in a different thread, but the recommended
approach is do something like:

(run-pipeline (request-params request)
  (fn [params]
    ... handle request here ...))

or to wrap your code in the (async ...) macro.


start-http-server

function
Usage: (start-http-server handler options)
Starts an HTTP server on the specified :port.  To support WebSockets, set :websocket to
true.

'handler' should be a function that takes two parameters, a channel and a request hash.
The request is a hash that conforms to the Ring standard, with :websocket set to true
if it is a WebSocket handshake.  If the request is chunked, the :body will also be a
channel.

If the request is a standard HTTP request, the channel will accept a single message, which
is the response.  For a chunked response, the response :body should be a channel.  If the
request is a WebSocket handshake, the channel represents a full duplex socket, which
communicates via complete (i.e. non-streaming) strings.


sync-http-request

function
Usage: (sync-http-request request)
       (sync-http-request request timeout)
A synchronous version of http-request.  Halts the thread until the response has returned,
and throws an exception if the timeout elapsed or another error occurred.


wrap-aleph-handler

function
Usage: (wrap-aleph-handler f)
Allows for an asynchronous handler to be used within a largely synchronous application.
Assuming the top-level handler has been wrapped in wrap-ring-handler, this function can be
used to wrap handler functions for asynchronous routes.


wrap-ring-handler

function
Usage: (wrap-ring-handler f)
Wraps a synchronous Ring handler, such that it can be used in start-http-server.  If certain
routes within the application are asynchronous, wrap those handler functions in
wrap-aleph-handler.

aleph.http.server.requests




transform-netty-request

function
Usage: (transform-netty-request req netty-channel options)
Transforms a Netty request into a Ring request.

aleph.http.server.responses




transform-aleph-response

function
Usage: (transform-aleph-response response options)
Turns a Ring response into something Netty can understand.

aleph.http.websocket.protocol




mask-buffers

function
Usage: (mask-buffers mask bufs)
Does an in-place masking of a sequence of ByteBuffers.
Logo & site design by Tom Hickey.
Clojure auto-documentation system by Tom Faulhaber.