strojure.undertow.handler — com.github.strojure/undertow 1.0.72-rc2

Undertow HttpHandler functionality and library of standard handlers.

arity1-wrapper clj

(arity1-wrapper f)

Converts 1-arity function (fn [handler]) to function (fn [obj]) returning handler wrapper (fn [handler] ...).

arity2-wrapper clj

(arity2-wrapper f)

Converts 2-arity function (fn [handler obj]) to function (fn [obj]) returning handler wrapper (fn [handler] ...).

chain clj

(chain xs)

(chain handler xs)

Chains sequence of handler wrappers with handlerin direct order. Used for declarative description of handler chains. The 1-arity function chains preceding wrappers with the last handler in sequence.

The expression

(handler/chain my-handler [handler/request-dump
                           handler/simple-error-page])
;=> #object[io.undertow.server.handlers.RequestDumpingHandler 0x7b3122a5 "dump-request()"]

is same as

(-> my-handler
    simple-error-page
    request-dump)

define-type clj

(define-type sym {:keys [as-handler as-wrapper alias]})

Adds multimethods for declarative description of HTTP handlers.

1. sym A constant to distinguish specific handler, usually symbol of handler function var.
2. Options:
   • :as-handler The function (fn [obj] handler) to coerce obj to handler.
   • :as-wrapper The function (fn [obj] (fn [handler])) returning function to wrap another handler.
   • :alias The alias for the sym, usually keyword.

dispatch clj

(dispatch next-handler)

A HttpHandler that dispatches request to the XNIO worker thread pool if the current thread in the IO thread for the exchange.

graceful-shutdown clj

(graceful-shutdown next-handler)

Returns a new handler that can be used to wait for all requests to finish before shutting down the server gracefully.

path clj

(path config)

(path default-handler {:keys [prefix exact cache-size]})

Returns a new path handler, with optional default handler. A HttpHandler that dispatches to a given handler based of a prefix match of the path. This only matches a single level of a request, e.g. if you have a request that takes the form: /foo/bar.

Arguments:

• default-handler The handler that is invoked if there are no paths matched.

• config The configuration map with options:

  • :prefix The map of path prefixes and their handlers.

    • If the path does not start with a / then one will be prepended.
    • The match is done on a prefix bases, so registering /foo will also match /foo/bar. Though exact path matches are taken into account before prefix path matches. So if an exact path match exists its handler will be triggered.
    • If / is specified as the path then it will replace the default handler.

  • :exact The map of exact paths and their handlers.

    • If the request path is exactly equal to the given path, run the handler.
    • Exact paths are prioritized higher than prefix paths.

  • :cache-size The cache size, unlimited by default, integer.

Example:

(handler/path {:prefix {"static" (handler/resource {...})}
               :exact {"ws" (handler/websocket {...})}})

proxy-peer-address clj

(proxy-peer-address next-handler)

Returns a new handler that sets the peer address based on the X-Forwarded-For and X-Forwarded-Proto headers.

This should only be used behind a proxy that always sets this header, otherwise it is possible for an attacker to forge their peer address.

request-dump clj

(request-dump next-handler)

Returns a handler that dumps requests to the log for debugging purposes.

resource clj

(resource resource-manager)

(resource next-handler resource-manager)

Returns a new resource handler with optional next handler that is called if no resource is found.

Function arguments:

• next-handler The handler that is called if no resource is found.

• resource-manager The instance of ResourceManager or resource manager configuration map.

  Resource manager configuration options:

  • :resource-manager The type of configuration manager, keyword.
    • Used as :type in configuration passed to api.types/as-resource-manager.

  Configuration options of :classpath-files resource manager:

  • :prefix The prefix that is appended to resources that are to be loaded, string.
    • Default prefix is "public".
    • The :classpath-files resource manager ignores directories to avoid 403 Forbidden response.

Example:

(handler/resource {:resource-manager :classpath-files
                   :prefix "public/static"})

session clj

(session next-handler
         {:keys [session-manager session-config]
          :or {session-manager {} session-config {}}})

Returns a new handler that attaches the session to the request. This handler is also the place where session cookie configuration properties are configured. Note: this approach is not used by Servlet, which has its own session handlers.

1. next-handler The handler that is called after attaching session.

2. Handler configuration map with options:

   • session-manager The instance of SessionManager or session manager configuration map. If not specified then InMemorySessionManager is used with default settings (see [[in-memory-session-manager]]).

   • session-config The instance of SessionConfig or session config configuration map. If not specified then SessionCookieConfig is used with default settings (see [[session-cookie-config]]).

simple-error-page clj

(simple-error-page next-handler)

Returns a handler that generates an extremely simple no frills error page.

virtual-host clj

(virtual-host {:keys [host]})

(virtual-host default-handler config)

Returns a new virtual host handler, with optional default handler. A HttpHandler that implements virtual hosts based on the Host: http header.

Arguments:

• default-handler The handler that is invoked if there are no hostnames matched.

• config The configuration map with options:

  • :host The map of hostnames and their handlers.

Example:

(handler/virtual-host {:host {"static.localhost" (handler/resource {...})
                              "ws.localhost" (handler/websocket {...})})

websocket clj

(websocket {:keys [on-connect on-message on-close on-error] :as callback})

(websocket {{:keys [on-connect on-message on-close on-error]} :callback})

(websocket callback)

(websocket next-handler callback)

Returns a new web socket session handler with optional next handler to invoke if the web socket connection fails. A HttpHandler which will process the HttpServerExchange and do the actual handshake/upgrade to WebSocket.

Function arguments:

• next-handler The handler that is invoked if there are no web socket headers.

• callback The instance of the WebSocketConnectionCallback or callback configuration map.

  Callback configuration options provided “as is” or as :callback key:

  • :on-connect The function (fn [{:keys [callback exchange channel]}]).

    • Is called once the WebSocket connection is established, which means the handshake was successful.

  • :on-message The function (fn [{:keys [callback channel text data]}]).

    • Is called when listener receives a message.
    • The text message is provided in :text and binary message is provided in :data.

  • :on-close The function (fn [{:keys [callback channel code reason]}]).

    • Is called once the WebSocket connection is closed.
    • The :code is status code to close messages: http://tools.ietf.org/html/rfc6455#section-7.4

  • :on-error The function (fn [{:keys [callback channel error]}]).

    • Is called on WebSocket connection error.
    • Default implementation just closes WebSocket connection.

with-exchange clj

(with-exchange handle-exchange)

A simple HttpHandler which invokes function handle-exchange with server exchange as argument.