Chapter 6. Immutant Web

Immutant allows applications to respond to web requests, typically via Ring handlers, but standard Java Servlets are supported, too. Each application can dynamically register any number of handlers, each with a unique context path. This allows you to have multiple Ring endpoints that share the same deployment lifecycle.

Immutant provides a session implementation that provides automatic data sharing across nodes in a cluster.

In this chapter, the term application refers to the full deployment itself, and endpoint refers to a particular web application based around a single Ring handler as its entry point. For most applications, the two will be the same thing.

The context path is a prefix on the path portion of a url that is used as a mechanism to route requests to the proper endpoint when more than one endpoint is being served by the same 'container'. If you are running only one endpoint in a container (which is the typical strategy when deploying a Clojure endpoint via Jetty), the context path is the root context - /.

A properly constructed endpoint needs no knowledge of the context path it is mounted under - the container is responsible for routing requests to the endpoint and providing the endpoint specific fragment of the url's path to it. This allows the endpoint to be moved between contexts (or mounted at multiple contexts at once) without any modification to the endpoint code itself.

In addition to segmenting applications by context path, you can also segment by virtual host. To specify the virtual host (or hosts) for an application, set the :virtual-host key in either in the deployment descriptor or the :immutant section of the application's project.clj (see Initialization for the details on setting configuration values). :virtual-host must be a string specifying a single host or a vector of strings specifying multiple hosts. Two applications with different virtual hosts can use the same context path without collision.

To register a Ring handler, you simply call immutant.web/start, which takes one or two arguments, plus some options:

• sub-context-path - the sub-context path within the application's context path where the handler should be attached. Optional - if omitted, "/" is assumed. Only one handler can be attached to any given sub-context path - providing an already attached sub-context will replace the previously registered handler.
• handler - the Ring handler to invoke when requests come in on the sub context path. If a symbol is passed, it'll be resolved to a var to facilitate auto-reloading.

The options are a subset of those provided by the popular ring-server:

These options can also be specified in the :ring map in project.clj, useful when porting existing Ring apps.

Auto-reloading is enabled by default in development mode, which is determined by the presence of the :dev profile among the active ones in your Leiningen project. The lein-immutant plugin activates :dev by default when you deploy your app, but you can override this using the with-profile higher-order task. You can also set the environment variable, LEIN_NO_DEV, to disable these defaults, regardless of whether :dev is active.

Let's take a look at start in use. For the following example, assume the application has a top-level context path of /my-app:

(ns my.ns
  (:require [immutant.web :as web]))

;; handle requests at the root sub-context (/).
;; this handler will receive any request that the app
;; receives at /my-app/* *except* for anything captured by another
;; sub-context.
(web/start my-root-handler)

;; handle requests at the /somewhere sub-context.
;; this handler will receive any request that the app
;; receives at /my-app/somewhere/*.
(web/start "/somewhere" my-other-handler)

;; If you want to see your changes immediately while in a REPL,
;; the symbol referring to your handler should resolve to a var.
;; You only need to explicitly set :auto-reload? when not in
;; development mode.
(web/start #'your-handler :auto-reload? true)

You can deregister a registered handler at any time. Immutant will deregister any remaining handlers for you when your application is undeployed.

You can deregister a Ring handler via the immutant.web/stop function, which takes zero or one arguments:

• sub-context-path - the sub-context path within the application's context path where the handler was attached. Optional - if omitted, "/" is assumed.

An example of using stop:

(ns my.ns
  (:require [immutant.web :as web]))

;; deregisters the handler attached to the root sub-context (/)
(web/stop)

;; deregisters the handler attached to the /somewhere sub-context
(web/stop "/somewhere")

Now that we've introduced registering ring handlers, we can give an example that makes it clear how the context and sub-context paths work, and how the path info gets set.

First, we'll set the context path for the entire application in our project.clj:

(defproject someapp "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.4.0"]]

  :immutant {:init someapp.core/start
             :context-path "/foo"})

Now we'll register two ring handlers with different sub-contexts, both of which will be available under the parent context we set in project.clj:

(ns someapp.core
  (:require [immutant.web :as web]))

(defn make-handler  [sub-context]
  (fn [{:keys [context path-info] :as request}]
    {:status 200
     :content-type "text/plain"
     :body (pr-str {:mounted-sub-context sub-context
                    :request-context context
                    :request-path-info path-info})}))

(defn start []
  ;; responds to /foo/
  (web/start "/" (make-handler "/"))
  ;; responds to /foo/bar/
  (web/start "/bar" (make-handler "/bar")))

When we deploy the app to Immutant, we can see how it sets the :context and :path-info keys in the request map:

$ curl http://localhost:8080/foo/baz
{:mounted-sub-context "/", :request-context "/foo", :request-path-info "/baz"}
$ curl http://localhost:8080/foo/baz/sheep
{:mounted-sub-context "/", :request-context "/foo", :request-path-info "/baz/sheep"}
$ curl http://localhost:8080/foo/bar/baz
{:mounted-sub-context "/bar", :request-context "/foo/bar", :request-path-info "/baz"}
$ curl http://localhost:8080/foo/bar/baz/sheep
{:mounted-sub-context "/bar", :request-context "/foo/bar", :request-path-info "/baz/sheep"}
$ curl http://localhost:8080/foo/bar
{:mounted-sub-context "/bar", :request-context "/foo/bar", :request-path-info "/"}
$ curl http://localhost:8080/foo/
{:mounted-sub-context "/", :request-context "/foo", :request-path-info "/"}

Immutant provides a session store that can be used with the Ring session middleware (and any other middleware that uses ring.middleware.session, like Sandbar). The Immutant session store uses the session provided by the underlying JBoss AS7 servlet container, which automatically replicates session data across a cluster. You create the store by calling immutant.web.session/servlet-store, and use it by passing it as the :store option to ring.middleware.session/wrap-session:

(ns my.ns
  (:require [ring.middleware.session :as ring-session]
            [immutant.web :as web]
            [immutant.web.session :as immutant-session]))

(web/start
 (ring-session/wrap-session
  #'my-handler
  {:store (immutant-session/servlet-store)}))

Note: since this store is managed by the servlet container, the session cookie (JSESSIONID by default) is itself managed at the servlet level. Any options other than :store passed to ring.middleware.session/wrap-session (:cookie-attrs, :cookie-name, or :root) won't affect the actual cookie used to store the session id client-side. To set the cookie name or attributes, see session options.

When a web server is embedded within an application, it's fine to make assumptions about relative paths because the current working directory for both the app and the web server is the same.

But this is not the case for Immutant, or any app server, because multiple applications may be deployed on it simultaneously. The app server is a single process, with a single current working directory, and an application should not assume that the server's current directory matches its root.

But certain libraries require actual filesystem paths to directories at runtime, so you need to be able to determine the path to the application root. You can do so via the immutant.util/app-relative function.

Web applications often need to serve static resources such as images, stylesheets, or javascript files. Ring applications use middleware to accomplish this.

In Immutant, the recommended approach is to store your resources beneath resources/public/, and then reference that path using ring.middleware.resource/wrap-resource:

(ring.middleware.resource/wrap-resource app "public")

This works because the resources/ directory is automatically added to the application's effective classpath at deployment.

NOTE: Prior to version 1.2, Ring middleware didn't support applications mounted at a context path other than the root. The 1.0.x versions of Immutant ship with Ring 1.1.8, and provide a drop-in replacement, immutant.web/wrap-resource, that is no longer available in later Immutant versions.

Though mounting a Ring handler at a particular [sub] context path will suffice for the majority of Clojure web apps, some may find it too limiting and require the full capabilities of the Java Servlet API. Of course, like any servlet container, you can always wrap your servlets up into a war file and deploy it to Immutant. But you don't have to. You can mount any servlet to a context path via the immutant.web/start-servlet function.

The servlet container used by JBossAS uses a bounded thread pool for handling HTTP connections. The default maximum bound for that pool is 512 * the number of cores. If you need to reduce or expand that limit, you can do so via a system property: org.immutant.web.http.maxThreads.

There are several ways to set that system property - you can pass it to lein immutant run:

lein immutant run -Dorg.immutant.web.http.maxThreads=9000

or to standalone.sh:

$IMMUTANT_HOME/jboss/bin/standalone.sh -Dorg.immutant.web.http.maxThreads=9000

or add it to standalone.xml:

<extensions>
...
</extensions>
<system-properties>
  <property name='org.immutant.web.http.maxThreads' value='123'/>
</system-properties>

Note that if you have changed the name of the HTTP connector from "http" for some reason, you will need to replace "http" in the system property with that new name.