Serve web requests using Ring handlers, Servlets, or Undertow HttpHandlers
(run handler & options)
handler with the given
handler can be a Ring handler function, a Servlet, or an Undertow HttpHandler. Can be called multiple times - if given the same options, any prior handler with those options will be replaced. Returns the given options with any missing defaults filled in.
options can be a map or kwargs, with these valid keys [default]:
:hostThe interface bind address [“localhost”]
:portThe port listening for requests 
:pathMaps the handler to a prefix of the url path [“/”]
:virtual-hostVirtual host name[s] (a String or a List of Strings) [nil]
:dispatch?Invoke handlers in worker thread pool [true]
handler is a Servlet, the following options are also supported:
:servlet-nameThe servlet’s registered name [the
:filter-mapAn insertion-order-preserving mapping, e.g. array-map or LinkedHashMap, of names to Filter instances [nil]
Note the web server only binds to the loopback interface, by default. To expose your handler to the network, set
:host to an external IP address, or use “0.0.0.0” to bind it to all interfaces.
:virtual-host option enables name-based virtual hosting which, along with the
:path option, distinguishes the handlers on a single server. That is, multiple handlers can run on the same
as long as each has a unique combination of
Run calls may be threaded together:
(-> (run ello)
(->> (run owdy))
(->> (run ola)))
The above actually creates two web server instances, one listening for ello and owdy requests on port 8080, and another listening for ola requests on 8081.
For ring handlers, the actual writing of the response happens after your hander returns. If an exception occurs on the write (the most common case being an IOException because the client has gone away), the default behavior is to log the exception. If you would like to be able to handle that exception yourself, you can return a function in the ring response under
:write-error-handler. This function will be called with the exception, the request map, and the response map if an exception occurs when writing the response. Note that this handler can’t actually affect the response. If you would prefer a global handler, see
The underlying web server for Immutant is Undertow, which supports more advanced options than the above. These can be configured by passing an
Undertow$Builder via the
:configuration option, an instance of which is easily constructed from a map of valid keywords using the
immutant.web.undertow/options function. For convenience, all of its option keywords are valid for
run, too: if present, an
Undertow$Builder will be returned in the result.
If your handlers are compute-bound, you may be able to gain some performance by setting
:dispatch? to false. This causes the handlers to run on Undertow’s I/O threads, avoiding the context switch of dispatching them to the worker thread pool, at the risk of refusing client requests under load. Note that when
:dispatch? is false, returning a seq, File, or InputStream as a ring body will cause that request to be dispatched to a worker thread at write time to prevent blocking an I/O thread.
Inside WildFly, the
:dispatch? options are ignored, since all handlers are mounted as servlets contained within WildFly’s own Undertow instance. Further, all invocations of
run must be within the initialization function for your application, i.e. your
(run-dmc handler & options)
(server & options)
Returns the web server instance associated with a particular set of options, typically the map returned from a
run call. The web server provides
isRunning methods, allowing you to, for example, temporarily stop serving requests for all the handlers running on a particular server.
(let [srv (server (run hello
:auto-startfalse))] (.isRunning srv) ;=> false (.start srv) (.isRunning srv) ;=> true (.stop srv))
The return value is either a single server instance or a list of servers if passed the result from threaded run calls that would cause multiple servers to be created.
(stop & options)
Stops a running handler.
options can be passed as a map or kwargs, but is typically the map returned from a
run call. If that return value is not available, you can pass the same options map passed to
run for the handler you want to stop. If options isn’t provided, the handler at the root context path (“/”) of the default server will be stopped. If there are no handlers remaining on the server, the server itself is stopped. Returns true if a handler was actually removed.