strojure.undertow.server — com.github.strojure/undertow 1.0.31-beta.4

Undertow server functionality (start, stop, options etc.).

closeable clj

(closeable instance)

Returns java.io.Closable interface for running servers instance to use with with-open macro like:

(with-open [_ (closable (start {...}))]
  ;; Use running server here then close it.
  )

define-option clj

(define-option alias option)

(define-option alias option coerce-fn)

Defines keyword alias for Undertow option. The optional coerce-fn is used to coerce option value to correct Java type.

set-handler-fn-adapter clj

(set-handler-fn-adapter f)

Permanently assigns coercion of Clojure function to HttpHandler. Can be used by adapters like Ring handler adapter.

start clj

(start {:keys [port handler buffer-size io-threads worker-threads direct-buffers
               server-options socket-options worker-options handler-fn-adapter
               builder-fn-wrapper]})

Starts Undertow server given instance, builder or configuration map.

Server configuration map options:

• :port The map of ports and their listeners.

  • Can be just a port number for HTTP listener with default configuration.
  • The port listener is an instance of Undertow$ListenerBuilder or listener builder configuration map.
  • Port listener configuration options:
    • :host The host name string, default "localhost".
    • :https HTTPS configuration map with options:
      • :key-managers The instance of javax.net.ssl.KeyManager[].
      • :trust-managers The instance of javax.net.ssl.TrustManager[].
      • :ssl-context The instance of javax.net.ssl.SSLContext.
    • :handler The listener HttpHandler to be used on the port. See below how to declare handlers.
    • :socket-options The map of socket options for the listener.
      • :undertow/enable-http2. If HTTP2 protocol enabled, boolean.
      • Other option keywords can be found below in this namespace.
    • :use-proxy-protocol boolean.
  • The :https enables HTTPS protocol for the listener.
  • Declaration of AJP protocol is not supported.

• :handler The server HttpHandler to be used for all listeners without handler specified. See below how declare handlers.

• :buffer-size integer.

• :io-threads The number of IO threads to create.

• :worker-threads The number of worker threads, integer.

• :direct-buffers If direct buffers enabled, boolean.

• :server-options The map of server options.

• :socket-options The map of socket options.

• :worker-options The map of worker options.

• :handler-fn-adapter The function (fn [f] handler)

  • Defines coercion of clojure functions to HttpHandler during invocation of start, like i.e. ring handler.
  • By default, the coercion is not defined and functions cannot be used as handler.
  • The coercion can be assigned permanently using set-handler-fn-adapter.

• :builder-fn-wrapper

  • The function (fn [f] (fn [builder config] (f builder config))) which wraps standard builder configuration function f returning new function on builder and configuration.
  • Allows to customize builder configuration in any way by modifying builder, config and even ignoring function f.
  • Allows to make settings which are not available in declarative configuration like setWorker, setByteBufferPool etc.

Server configuration example:

{:port {;; HTTP port listener
        8080 {:host "localhost"
              :handler (comment "Listener handler declaration.")}
        ;; HTTPS port listener
        4040 {:https {:ssl-context '_}}}
 ;; Server handler for all listeners without handlers.
 :handler (comment "Server handler declaration.")
 :server-options {:undertow/enable-http2 true}}

Handler declaration

Handlers can be declared and chained using function invocations:

;; The chain of HTTP handler in reverse order.
(-> default-handler-fn
    ;; The handlers for app hostnames.
    (handler/virtual-host {:host {"app1" app1-handler-fn
                                  "app2" app2-handler-fn}})
    ;; Enable sessions for handlers above.
    (handler/session-attachment {})
    ;; The handler for specific path
    (handler/path {:prefix {"static" (handler/resource {:resource-manager :class-path
                                                        :prefix "public/static"})}
                   :exact {"websocket" (handler/websocket {:on-connect (fn [{:keys [channel] :as event}])
                                                           :on-message (fn [{:keys [channel text] :as event}])
                                                           :on-close (fn [event])
                                                           :on-error (fn [event])})}})
    ;; The handler for webapi hostname.
    (handler/virtual-host {:host {"webapi.localtest.me" webapi-handler-fn}})
    (handler/simple-error-page)
    (handler/proxy-peer-address)
    (handler/graceful-shutdown))

Or same handler written declarative:

[;; The chain of HTTP handlers in direct order.
 {:type handler/graceful-shutdown}
 {:type handler/proxy-peer-address}
 {:type handler/simple-error-page}
 ;; The handler for webapi hostname.
 {:type handler/virtual-host
  :host {"webapi.localtest.me" webapi-handler-fn}}
 ;; The handler for specific path
 {:type handler/path
  :prefix {"static" {:type handler/resource
                     :resource-manager :class-path
                     :prefix "public/static"}}
  :exact {"websocket" {:type handler/websocket
                       :on-connect (fn [{:keys [channel] :as event}])
                       :on-message (fn [{:keys [channel text] :as event}])
                       :on-close (fn [event])
                       :on-error (fn [event])}}}
 ;; Enable sessions for next handlers.
 {:type handler/session-attachment}
 ;; The handlers for app hostnames.
 {:type handler/virtual-host :host {"app1" app1-handler-fn
                                    "app2" app2-handler-fn}}
 default-handler-fn]

Keywords can be used instead of symbols as handler :type values:

{:type ::handler/proxy-peer-address}

There are some Undertow handlers available in the handler namespace. Others can be used via Java interop or adapted for declarative description using handler/define-type function.

stop clj

(stop instance)

Stops server instance, returns nil. The instance can be an instance of Undertow or map with {:type ::instance}.