strojure.undertow.handler — com.github.strojure/undertow 1.4.0-125

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.

on-response-commit clj

(on-response-commit listener)

(on-response-commit handler listener)

(on-response-commit handler {:keys [listener]})

Returns a new handler which adds listener callback that will be invoked just before response is commit. 1-arity function returns handler wrapper.

The listener is one of:

• a function (fn [exchange] ...);
• a configuration map with :listener key;
• an instance of io.undertow.server.ResponseCommitListener.

Example:

(defn- set-content-type-options
[^HttpServerExchange exchange]
(let [headers (.getResponseHeaders exchange)]
  (when (.contains headers Headers/CONTENT_TYPE)
    (.put headers Headers/X_CONTENT_TYPE_OPTIONS "nosniff"))))

(on-response-commit next-handler set-content-type-options)

{:type handler/on-response-commit :listener set-content-type-options}

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"})

security clj

(security next-handler
          {:keys [csp hsts referrer-policy content-type-options]
           {:keys [policy report-only random-nonce-fn report-handler]} :csp})

Returns a new handler which applies collection of web-security related handlers to the next-handler.

Arguments:

• next-handler – a handler to wrap.

• configuration map with keys:

  • :csp – CSP handler config, see handler.csp/csp-handler.

  • :hsts – the Strict-Transport-Security response header.

    • Is not set by default, instead I'd recommend to set this header on webapp container/proxy level like nginx.
    • The true value is rendered as "max-age=31536000".
    • The string value is rendered as is.

  • :referrer-policy – the [Referrer-Policy] response header.

    • Is not set by default, instead I'd recommend to set this header on webapp container/proxy level like nginx.
    • The true value is rendered as "strict-origin-when-cross-origin".
    • The string value is rendered as is.
    • The keyword is rendered as keyword name.

  • :content-type-options – boolean flag if [X-Content-Type-Options]: nosniff response header should be added.

    • Default: true.
    • Response header is only added when Content-Type is set.

Example:

{:type `handler/security :csp {:policy {"default-scr" :none}}}

NOTE: Not implemented obsolete headers:

• X-Frame-Options is obsoleted by CSP’s frame-ancestors directive.
• X-XSS-Protection is non-standard and not supported in modern browsers.

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 handler.session/in-memory-session-manager).

   • session-config The instance of SessionConfig or session config configuration map. If not specified then SessionCookieConfig is used with HttpOnly and SameSite=Lax (see handler.session/session-cookie-config).

set-response-header clj

(set-response-header next-handler headers)

Returns a new handler which sets fixed response headers.

The headers is a map of string header names and values where value is one of:

• a string value to be set as is;
• a function (fn [^HttpServerExchange exchange] header-value) which returns header value for exchange;
• an instance of ExchangeAttribute to read header value from exchange.

Example:

(set-response-header handler {"X-Content-Type-Options" "nosniff"})

The headers can be a map {:header {...}} for declarative description:

{:type `set-response-header :header {"Content-Type" "text/html"
                                     "X-Content-Type-Options" "nosniff"}}

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.