strojure.undertow.server — com.github.strojure/undertow 1.4.0+123

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

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 {:as config
        :keys [port handler buffer-size io-threads worker-threads direct-buffers
               server-options socket-options worker-options handler-fn-adapter
               builder-fn-wrapper]})

(start builder)

(start server)

Starts Undertow server given instance, builder or configuration map. Returns closeable server instance.

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 created and chained explicitly:

(-> (my-handler :default-handler)
    ;; The handlers for app hostnames.
    (handler/virtual-host
      {:host {"app1.company.com" (my-handler :app1-handler)
              "app2.company.com" (my-handler :app2-handler)}})
    ;; Enable sessions for next handlers (above).
    (handler/session {})
    ;; Path specific handlers.
    (handler/path {:prefix {"static" (handler/resource {:resource-manager :classpath-files
                                                        :prefix "public/static"})}
                   :exact {"websocket" (handler/websocket websocket-callback)}})
    ;; The handler for webapi hostname.
    (handler/virtual-host {:host {"webapi.company.com" (my-handler :webapi-handler)}})
    ;; Supplemental useful handlers.
    (handler/simple-error-page)
    (handler/proxy-peer-address))

Or same handler can be written declarative:

[;; Supplemental useful handlers.
 {:type handler/proxy-peer-address}
 {:type handler/simple-error-page}
 ;; The handler for webapi hostname.
 {:type handler/virtual-host
  :host {"app1.company.com" (my-handler :app1-handler)
         "app2.company.com" (my-handler :app2-handler)}}
 ;; Path specific handlers.
 {:type handler/path
  :prefix {"static" {:type handler/resource :resource-manager :classpath-files
                     :prefix "public/static"}}
  :exact {"websocket" {:type handler/websocket :callback websocket-callback}}}
 ;; Enable sessions for next handlers.
 {:type handler/session}
 ;; The handlers for app hostnames.
 {:type handler/virtual-host
  :host {"webapi.company.com" (my-handler :webapi-handler)}}
 ;; Last resort handler
 (my-handler :default-handler)]

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.