I’m new to Clojure and have been using Compojure to write a basic web application. I’m hitting a wall with Compojure’s defroutes syntax, though, and I think I need to understand both the “how” and the “why” behind it all.
It seems like a Ring-style application begins with an HTTP request map, then just passes the request through a series of middleware functions until it gets transformed into a response map, which gets sent back to the browser. This style seems too “low level” for developers, thus the need for a tool like Compojure. I can see this need for more abstractions in other software ecosystems as well, most notably with Python’s WSGI.
The problem is that I don’t understand Compojure’s approach. Let’s take the following defroutes S-expression:
(defroutes main-routes
(GET "/" [] (workbench))
(POST "/save" {form-params :form-params} (str form-params))
(GET "/test" [& more] (str "<pre>" more "</pre>"))
(GET ["/:filename" :filename #".*"] [filename]
(response/file-response filename {:root "./static"}))
(ANY "*" [] "<h1>Page not found.</h1>"))
I know that the key to understanding all of this lies within some macro voodoo, but I don’t totally understand macros (yet). I’ve stared at the defroutes source for a long time, but just don’t get it! What’s going on here? Understanding the “big idea” will probably help me answer these specific questions:
- How do I access the Ring environment from within a routed function (e.g. the
workbenchfunction)? For example, say I wanted to access the HTTP_ACCEPT headers or some other part of the request/middleware? - What’s the deal with the destructuring (
{form-params :form-params})? What keywords are available for me when destructuring?
I really like Clojure but I am so stumped!
Compojure explained (to some degree)
NB. I am working with Compojure 0.4.1 (here‘s the 0.4.1 release commit on GitHub).
Why?
At the very top of
compojure/core.clj, there’s this helpful summary of Compojure’s purpose:On a superficial level, that’s all there is to the “why” question. To go a bit deeper, let’s have a look at how a Ring-style app functions:
A request arrives and is transformed into a Clojure map in accordance with the Ring spec.
This map is funnelled into a so-called “handler function”, which is expected to produce a response (which is also a Clojure map).
The response map is transformed into an actual HTTP response and sent back to the client.
Step 2. in the above is the most interesting, as it is the handler’s responsibility to examine the URI used in the request, examine any cookies etc. and ultimately arrive at an appropriate response. Clearly it is necessary that all this work be factored into a collection of well-defined pieces; these are normally a “base” handler function and a collection of middleware functions wrapping it. Compojure’s purpose is to simplify the generation of the base handler function.
How?
Compojure is built around the notion of “routes”. These are actually implemented at a deeper level by the Clout library (a spinoff of the Compojure project — many things were moved to separate libraries at the 0.3.x -> 0.4.x transition). A route is defined by (1) an HTTP method (GET, PUT, HEAD…), (2) a URI pattern (specified with syntax which will apparently be familiar to Webby Rubyists), (3) a destructuring form used in binding parts of the request map to names available in the body, (4) a body of expressions which needs to produce a valid Ring response (in non-trivial cases this is usually just a call to a separate function).
This might be a good point to have a look at a simple example:
Let’s test this at the REPL (the request map below is the minimal valid Ring request map):
If
:request-methodwere:headinstead, the response would benil. We’ll return to the question of whatnilmeans here in a minute (but notice that it is not a valid Ring respose!).As is apparent from this example,
example-routeis just a function, and a very simple one at that; it looks at the request, determines whether it’s interested in handling it (by examining:request-methodand:uri) and, if so, returns a basic response map.What is also apparent is that the body of the route does not really need to evaluate to a proper response map; Compojure provides sane default handling for strings (as seen above) and a number of other object types; see the
compojure.response/rendermultimethod for details (the code is entirely self-documenting here).Let’s try using
defroutesnow:The responses to the example request displayed above and to its variant with
:request-method :headare like expected.The inner workings of
example-routesare such that each route is tried in turn; as soon as one of them returns a non-nilresponse, that response becomes the return value of the wholeexample-routeshandler. As an added convenience,defroutes-defined handlers are wrapped inwrap-paramsandwrap-cookiesimplicitly.Here’s an example of a more complex route:
Note the destructuring form in place of the previously used empty vector. The basic idea here is that the body of the route might be interested in some information about the request; since this always arrives in the form of a map, an associative destructuring form can be supplied to extract information from the request and bind it to local variables which will be in scope in the route’s body.
A test of the above:
The brilliant follow-up idea to the above is that more complex routes may
assocextra information onto the request at the matching stage:This responds with a
:bodyof"foo"to the request from the previous example.Two things are new about this latest example: the
"/:fst/*"and the non-empty binding vector[fst]. The first is the aforementioned Rails-and-Sinatra-like syntax for URI patterns. It’s a bit more sophisticated than what is apparent from the example above in that regex constraints on URI segments are supported (e.g.["/:fst/*" :fst #"[0-9]+"]can be supplied to make the route accept only all-digit values of:fstin the above). The second is a simplified way of matching on the:paramsentry in the request map, which is itself a map; it’s useful for extracting URI segments from the request, query string parameters and form parameters. An example to illustrate the latter point:This would be a good time to have a look at the example from the question text:
Let’s analyse each route in turn:
(GET "/" [] (workbench))— when dealing with aGETrequest with:uri "/", call the functionworkbenchand render whatever it returns into a response map. (Recall that the return value might be a map, but also a string etc.)(POST "/save" {form-params :form-params} (str form-params))—:form-paramsis an entry in the request map provided by thewrap-paramsmiddleware (recall that it is implicitly included bydefroutes). The response will be the standard{:status 200 :headers {"Content-Type" "text/html"} :body ...}with(str form-params)substituted for.... (A slightly unusualPOSThandler, this…)(GET "/test" [& more] (str "<pre> more "</pre>"))— this would e.g. echo back the string representation of the map{"foo" "1"}if the user agent asked for"/test?foo=1".(GET ["/:filename" :filename #".*"] [filename] ...)— the:filename #".*"part does nothing at all (since#".*"always matches). It calls the Ring utility functionring.util.response/file-responseto produce its response; the{:root "./static"}part tells it where to look for the file.(ANY "*" [] ...)— a catch-all route. It is good Compojure practice always to include such a route at the end of adefroutesform to ensure that the handler being defined always returns a valid Ring response map (recall that a route matching failure results innil).Why this way?
One purpose of the Ring middleware is to add information to the request map; thus cookie-handling middleware adds a
:cookieskey to the request,wrap-paramsadds:query-paramsand/or:form-paramsif a query string / form data is present and so on. (Strictly speaking, all the information the middleware functions are adding must be already present in the request map, since that is what they get passed; their job is to transform it to be it more convenient to work with in the handlers they wrap.) Ultimately the “enriched” request is passed to the base handler, which examines the request map with all the nicely preprocessed information added by the middleware and produces a response. (Middleware can do more complex things than that — like wrapping several “inner” handlers and choosing between them, deciding whether to call the wrapped handler(s) at all etc. That is, however, outside the scope of this answer.)The base handler, in turn, is usually (in non-trivial cases) a function which tends to need just a handful of items of information about the request. (E.g.
ring.util.response/file-responsedoesn’t care about most of the request; it only needs a filename.) Hence the need for a simple way of extracting just the relevant parts of a Ring request. Compojure aims to provide a special-purpose pattern matching engine, as it were, which does just that.