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 workbench function)? 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:
A concise syntax for generating Ring handlers.
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:
(def example-route (GET "/" [] "<html>...</html>"))
Let's test this at the REPL (the request map below is the minimal valid Ring request map):
user> (example-route {:server-port 80
:server-name "127.0.0.1"
:remote-addr "127.0.0.1"
:uri "/"
:scheme :http
:headers {}
:request-method :get})
{:status 200,
:headers {"Content-Type" "text/html"},
:body "<html>...</html>"}
If :request-method were :head instead, the response would be nil. We'll return to the question of what nil means here in a minute (but notice that it is not a valid Ring respose!).
As is apparent from this example, example-route is 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-method and :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/render multimethod for details (the code is entirely self-documenting here).
Let's try using defroutes now:
(defroutes example-routes
(GET "/" [] "get")
(HEAD "/" [] "head"))
The responses to the example request displayed above and to its variant with :request-method :head are like expected.
The inner workings of example-routes are such that each route is tried in turn; as soon as one of them returns a non-nil response, that response becomes the return value of the whole example-routes handler. As an added convenience, defroutes-defined handlers are wrapped in wrap-params and wrap-cookies implicitly.
Here's an example of a more complex route:
(def echo-typed-url-route
(GET "*" {:keys [scheme server-name server-port uri]}
(str (name scheme) "://" server-name ":" server-port uri)))
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:
user> (echo-typed-url-route {:server-port 80
:server-name "127.0.0.1"
:remote-addr "127.0.0.1"
:uri "/foo/bar"
:scheme :http
:headers {}
:request-method :get})
{:status 200,
:headers {"Content-Type" "text/html"},
:body "http://127.0.0.1:80/foo/bar"}
The brilliant follow-up idea to the above is that more complex routes may assoc extra information onto the request at the matching stage:
(def echo-first-path-component-route
(GET "/:fst/*" [fst] fst))
This responds with a :body of "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 :fst in the above). The second is a simplified way of matching on the :params entry 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:
(defroutes echo-params
(GET "/" [& more]
(str more)))
user> (echo-params
{:server-port 80
:server-name "127.0.0.1"
:remote-addr "127.0.0.1"
:uri "/"
:query-string "foo=1"
:scheme :http
:headers {}
:request-method :get})
{:status 200,
:headers {"Content-Type" "text/html"},
:body "{\"foo\" \"1\"}"}
This would be a good time to have a look at the example from the question text:
(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>"))
Let's analyse each route in turn:
(GET "/" [] (workbench)) -- when dealing with a GET request with :uri "/", call the function workbench and 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-params is an entry in the request map provided by the wrap-params middleware (recall that it is implicitly included by defroutes). The response will be the standard {:status 200 :headers {"Content-Type" "text/html"} :body ...} with (str form-params) substituted for .... (A slightly unusual POST handler, 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 function ring.util.response/file-response to 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 a defroutes form to ensure that the handler being defined always returns a valid Ring response map (recall that a route matching failure results in nil).
Why this way?
One purpose of the Ring middleware is to add information to the request map; thus cookie-handling middleware adds a :cookies key to the request, wrap-params adds :query-params and/or :form-params if 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-response doesn'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.
There is an excellent article at booleanknot.com from James Reeves (author of Compojure), and reading it made it "click" for me, so I have retranscribed some of it here (really that's all I did).
There is also a slidedeck here from the same author, that answers this exact question.
Compojure is based on Ring, which is an abstraction for http requests.
A concise syntax for generating Ring handlers.
So, what are those Ring handlers ? Extract from the doc :
;; Handlers are functions that define your web application.
;; They take one argument, a map representing a HTTP request,
;; and return a map representing the HTTP response.
;; Let's take a look at an example:
(defn what-is-my-ip [request]
{:status 200
:headers {"Content-Type" "text/plain"}
:body (:remote-addr request)})
Pretty simple, but also quite low-level.
The above handler can be defined more concisely using the ring/util library.
(use 'ring.util.response)
(defn handler [request]
(response "Hello World"))
Now we want to call different handlers depending on the request.
We could do some static routing like so :
(defn handler [request]
(or
(if (= (:uri request) "/a") (response "Alpha"))
(if (= (:uri request) "/b") (response "Beta"))))
And refactor it like this :
(defn a-route [request]
(if (= (:uri request) "/a") (response "Alpha")))
(defn b-route [request]
(if (= (:uri request) "/b") (response "Beta"))))
(defn handler [request]
(or (a-route request)
(b-route request)))
The interesting thing that James notes then is that this allows nesting routes, because "the result of combining two or more routes together is itself a route".
(defn ab-routes [request]
(or (a-route request)
(b-route request)))
(defn cd-routes [request]
(or (c-route request)
(d-route request)))
(defn handler [request]
(or (ab-routes request)
(cd-routes request)))
By now, we are beginning to see some code that looks like it could be factored, using a macro. Compojure provides a defroutes macro:
(defroutes ab-routes a-route b-route)
;; is identical to
(def ab-routes (routes a-route b-route))
Compojure provides other macros, like the GET macro:
(GET "/a" [] "Alpha")
;; will expand to
(fn [request#]
(if (and (= (:request-method request#) ~http-method)
(= (:uri request#) ~uri))
(let [~bindings request#]
~#body)))
That last function generated looks like our handler !
Please make sure to check out James post, as it goes into more detailed explanations.
For anybody who still struggled to find out what is going on with the routes, it might be that, like me, you don't understand the idea of destructuring.
Actually reading the docs for let helped clear up the whole "where do the magic values come from?" question.
I'm pasting the relevant sections below:
Clojure supports abstract structural
binding, often called destructuring,
in let binding lists, fn parameter
lists, and any macro that expands into
a let or fn. The basic idea is that a
binding-form can be a data structure
literal containing symbols that get
bound to the respective parts of the
init-expr. The binding is abstract in
that a vector literal can bind to
anything that is sequential, while a
map literal can bind to anything that
is associative.
Vector binding-exprs allow you to bind
names to parts of sequential things
(not just vectors), like vectors,
lists, seqs, strings, arrays, and
anything that supports nth. The basic
sequential form is a vector of
binding-forms, which will be bound to
successive elements from the
init-expr, looked up via nth. In
addition, and optionally, & followed
by a binding-forms will cause that
binding-form to be bound to the
remainder of the sequence, i.e. that
part not yet bound, looked up via
nthnext . Finally, also optional, :as
followed by a symbol will cause that
symbol to be bound to the entire
init-expr:
(let [[a b c & d :as e] [1 2 3 4 5 6 7]]
[a b c d e])
->[1 2 3 (4 5 6 7) [1 2 3 4 5 6 7]]
Vector binding-exprs allow you to bind
names to parts of sequential things
(not just vectors), like vectors,
lists, seqs, strings, arrays, and
anything that supports nth. The basic
sequential form is a vector of
binding-forms, which will be bound to
successive elements from the
init-expr, looked up via nth. In
addition, and optionally, & followed
by a binding-forms will cause that
binding-form to be bound to the
remainder of the sequence, i.e. that
part not yet bound, looked up via
nthnext . Finally, also optional, :as
followed by a symbol will cause that
symbol to be bound to the entire
init-expr:
(let [[a b c & d :as e] [1 2 3 4 5 6 7]]
[a b c d e])
->[1 2 3 (4 5 6 7) [1 2 3 4 5 6 7]]
I haven't started on clojure web stuff yet but, I will, here's the stuff I bookmarked.
https://docs.google.com/Doc?docid=0AQqGP1CDN0uIZGhmZjJmcGZfMjNjNHIycGZu&hl=en
https://github.com/weavejester/compojure/wiki/Routes-In-Detail
http://mmcgrana.github.com/2010/03/clojure-web-development-ring.html
What's the deal with the destructuring ({form-params :form-params})? What keywords are available for me when destructuring?
The keys available are those that are in the input map. Destructuring is available inside let and doseq forms, or inside the parameters to fn or defn
The following code will hopefully be informative:
(let [{a :thing-a
c :thing-c :as things} {:thing-a 0
:thing-b 1
:thing-c 2}]
[a c (keys things)])
=> [0 2 (:thing-b :thing-a :thing-c)]
a more advanced example, showing nested destructuring:
user> (let [{thing-id :id
{thing-color :color :as props} :properties} {:id 1
:properties {:shape
"square"
:color
0xffffff}}]
[thing-id thing-color (keys props)])
=> [1 16777215 (:color :shape)]
When used wisely, destructuring declutters your code by avoiding boilerplate data access. by using :as and printing the result (or the result's keys) you can get a better idea of what other data you could access.
Related
I'm trying to figure out how to do custom coercion with compojure-api and spec. By reading the docs and code I have been able to do coercion on the input (the body) but am unable to do coercion on the response body.
Specifically, I have a custom type, a timestamp, that is represented as a long within my app but for the web API I want to consume and return ISO timestamps (no, I don't want to use Joda internally).
The following is what I have that works for input coercion but I have been unable to properly coerce the response.
(ns foo
(:require [clj-time.core :as t]
[clj-time.coerce :as t.c]
[spec-tools.conform :as conform]
[spec-tools.core :as st]))
(def timestamp (st/create-spec
{:spec pos-int?
:form `pos-int?
:json-schema/default "2017-10-12T05:04:57.585Z"
:type :timestamp}))
(defn json-timestamp->long [_ val]
(t.c/to-long val))
(def custom-json-conforming
(st/type-conforming
(merge
conform/json-type-conforming
{:timestamp json-timestamp->long}
conform/strip-extra-keys-type-conforming)))
(def custom-coercion
(-> compojure.api.coercion.spec/default-options
(assoc-in [:body :formats "application/json"] custom-json-
conforming)
compojure.api.coercion.spec/create-coercion))
;; how do I use this for the response coercion?
(defn timestamp->json-string [_ val]
(t.c/to-string val))
;; I've tried the following but it doesn't work:
#_(def custom-coercion
(-> compojure.api.coercion.spec/default-options
(assoc-in [:body :formats "application/json"] custom-json-
conforming)
(assoc-in [:response :formats "application/json"]
(st/type-conforming
{:timestamp timestamp->json-string}))
compojure.api.coercion.spec/create-coercion))
Problem is that Spec Conforming is a one-way transformation pipeline:
s/conform (and because of that st/conform) does both transform and validate for the result. Your response coercion first converts the integer into date string and the validates it against the original spec predicate, which is pos-int? and it fails on that.
To support two-way transformations, you need to define the end result as either of the possible formats: e.g. change your predicate to something like #(or (pos-int? %) (string? %)) and it should work.
Or you can have two different Spec Records, one for input (timestamp-long with pos-int? predicate) and another for outputs (timestamp-string with string? predicate). But one needs to remember to use correct ones for request & responses.
CLJ-2251 could possible help if there was and extra :transform mode (not written in the issue yet), which would do conforming without validating the end results.
Normally, return transformations are done by the format encoder, but they usually dispatch on value types. For example Cheshire just sees an Long and has no clue that it should be written as date string.
Maybe people on the #clojure-spec slack could help. Would also like to know how to build this kind of two-way transformation with spec.
In a small app I'm building that uses Reagent and Re-frame I'm using multi-methods to dispatch which page should be shown based on a value in the app state:
(defmulti pages :name)
(defn main-panel []
(let [current-route (re-frame/subscribe [:current-route])]
(fn []
;...
(pages #current-route))))
and then I have methods such as:
(defmethod layout/pages :register [_] [register-page])
where the register-page function would generate the actual view:
(defn register-page []
(let [registration-form (re-frame/subscribe [:registration-form])]
(fn []
[:div
[:h1 "Register"]
;...
])))
I tried changing my app so that the methods generated the pages directly, as in:
(defmethod layout/pages :register [_]
(let [registration-form (re-frame/subscribe [:registration-form])]
(fn []
[:div
[:h1 "Register"]
;...
])))
and that caused no page to ever be rendered. In my main panel I changed the call to pages to square brackets so that Reagent would have visibility into it:
(defn main-panel []
(let [current-route (re-frame/subscribe [:current-route])]
(fn []
;...
[pages #current-route])))
and that caused the first visited page to work, but after that, clicking on links (which causes current-route to change) has no effect.
All the namespaces defining the individual methods are required in the file that is loaded first, that contains the init function, and the fact that I can pick any single page and have it displayed proves the code is loading (then, switching to another page doesn't work):
https://github.com/carouselapps/ninjatools/blob/master/src/cljs/ninjatools/core.cljs#L8-L12
In an effort to debug what's going on, I defined two routes, :about and :about2, one as a function and one as a method:
(defn about-page []
(fn []
[:div "This is the About Page."]))
(defmethod layout/pages :about [_]
[about-page])
(defmethod layout/pages :about2 [_]
(fn []
[:div "This is the About 2 Page."]))
and made the layout print the result of calling pages (had to use the explicit call instead of the square brackets of course). The wrapped function, the one that works, returns:
[#object[ninjatools$pages$about_page "function ninjatools$pages$about_page(){
return (function (){
return new cljs.core.PersistentVector(null, 2, 5, cljs.core.PersistentVector.EMPTY_NODE, [new cljs.core.Keyword(null,"div","div",1057191632),"This is the About Page."], null);
});
}"]]
while the method returns:
#object[Function "function (){
return new cljs.core.PersistentVector(null, 2, 5, cljs.core.PersistentVector.EMPTY_NODE, [new cljs.core.Keyword(null,"div","div",1057191632),"This is the About 2 Page."], null);
}"]
If I change the method to be:
(defmethod layout/pages :about2 [_]
[(fn []
[:div "This is the About 2 Page."])])
that is, returning the function in a vector, then, it starts to work. And if I make the reverse change to the wrapped function, it starts to fail in the same manner as the method:
(defn about-page []
(fn []
[:div "This is the About Page."]))
(defmethod layout/pages :about [_]
about-page)
Makes a bit of sense as Reagent's syntax is [function] but it was supposed to call the function automatically.
I also started outputting #current-route to the browser, as in:
[:main.container
[alerts/view]
[pages #current-route]
[:div (pr-str #current-route)]]
and I verified #current-route is being modified correctly and the output updated, just not [pages #current-route].
The full source code for my app can be found here: https://github.com/carouselapps/ninjatools/tree/multi-methods
Update: corrected the arity of the methods following Michał Marczyk's answer.
So, a component like this: [pages #some-ratom]
will rerender when pages changes or #some-ratom changes.
From reagent's point of view, pages hasn't changed since last time, it is still the same multi-method it was before. But #some-ratom might change, so that could trigger a rerender.
But when this rerender happens it will be done using a cached version of pages. After all, it does not appear to reagent that pages has changed. It is still the same multimethod it was before.
The cached version of pages will, of course, be the first version of pages which was rendered - the first version of the mutlimethod and not the new version we expect to see used.
Reagent does this caching because it must handle Form-2 functions. It has to keep the returned render function.
Bottom line: because of the caching, multimethods won't work very well, unless you find a way to completely blow up the component and start again, which is what the currently-top-voted approach does:
^{:key #current-route} [pages #current-route]
Of course, blowing up the component and starting again might have its own unwelcome implications (depending on what local state is held in that component).
Vaguely Related Background:
https://github.com/Day8/re-frame/wiki/Creating-Reagent-Components#appendix-a---lifting-the-lid-slightly
https://github.com/Day8/re-frame/wiki/When-do-components-update%3F
I don't have all the details, but apparently, when I was rendering pages like this:
[:main.container
[alerts/view]
[pages #current-route]]
Reagent was failing to notice that pages depended on the value of #current-route. The Chrome React plugin helped me figure it out. I tried using a ratom instead of a subscription and that seemed to work fine. Thankfully, telling Reagent/React the key to an element is easy enough:
[:main.container
[alerts/view]
^{:key #current-route} [pages #current-route]]
That works just fine.
The first problem that jumps out at me is that your methods take no arguments:
(defmethod layout/pages :register [] [register-page])
^ arglist
Here you have an empty arglist, but presumably you'll be calling this multimethod with one or two arguments (since its dispatch function is a keyword and keywords can be called with one or two arguments).
If you want to call this multimethod with a single argument and just ignore it inside the body of the :register method, change the above to
(defmethod layout/pages :register [_] [register-page])
^ argument to be ignored
Also, I expect you'll probably want to call pages yourself like you previously did (that is, revert the change to square brackets that you mentioned in the question).
This may or may not fix the app – there may be other problems – but it should get you started. (The multimethod will definitely not work with those empty arglists if you pass in any arguments.)
How about if you instead have a wrapper pages-component function which is a regular function that can be cached by reagent. It would look like this:
(defn pages-component [state]
(layout/pages #state))
I have compojure based app where I need to parse a request and retrieve parameters that can be numbers. I want to be able to verify that the parameters exist and that they are numbers before actually processing the request. This is what I have so far:
(defn get-int [str]
"Returns nil if str is not a number"
(try (Integer/parseInt str)
(catch NumberFormatException _)))
(defn some-request [request]
(let [some-number (get-int (get-in request [:route-params :some-number])
other-number (get-int (get-in request [:route-params :other-number])]
(if (every? identity [some-number other-number])
(process-the-request)
(bad-request "The request was malformed")))
Is there a better way to do string -> number conversion?
Is there a better way to do request validation?
This question contains good examples for parsing numbers in Clojure. If you are not sure that the string contains a valid number, your approach looks good.
If you can pass the parameters as part of the query string, you could use a route with regex to retrieve the value, e.g.
(GET ["/user/:id", :id #"[0-9]+"] [id]
(let [num (read-string id)]
(str "The number is: " num)))
The route would only match if the regex conditions are met, therefore you could skip the Integer/parseInt check.
Use Long/parseLong instead of Integer/parseInteger. The latter supports only 32 bits, which is often insufficient; for instance, Datomic entity IDs don't fit into Integer.
Never use read-string for user input. In addition, you must sanitize user input, removing injected scripts and such. https://github.com/alxlit/autoclave is a good start, although the defaults are arguably too aggressive.
I have the following routes definition:
(require '[compojure.core :as ccore]
'[ring.util.response :as response])
(def *main-routes*
(ccore/defroutes avalanche-routes
(ccore/GET "/" [] "Hello World 2")
(ccore/GET "/images/:id" [id] (get-image-response id))))
In this example, requesting / works like a charm and returns the expected Hello World 2.
The get-images-response method is defined like this:
(defn get-image-response
[id]
(let [record (db/get-image id false)]
(-> (response/response (:data record))
(response/content-type (:content-type record))
(response/header "Content-Length" (:size record)))))
I get a 404 though, so the serving of binary files doesn't quite work yet. Any ideas why?
Edit:
Ok, the issue relates to the fact that images are being requested on /images/name.jpg. As soon as I remove the .jpg the handler gets called. So the question becomes how do I match on anything but the extension?
Compojure uses clout for route matching. The dot character has a special meaning in clout routes. It represents a token separator, similarly to the slash character. The following characters all have this meaning in clout: / . , ; ?.
That means that a route like "/images/:id" will not match a uri of the form /images/name.jpg since images, name and jpg each represent a separate token in clout.
In order to match it, you could compose your route in a number of different ways, depending on your need.
If all your images have the .jpg extension, the easiest thing to do would be:
(GET "/images/:id.jpg" [id] ...)
If the extension varies you could do the following:
(GET "/images/:name.:extension" [name extension] ...)
If you want to restrict the extension, you can pass compojure/clout a regular expression:
(GET ["/images/:name.:ext", :ext #"(jpe?g|png|gif)"] [name ext] ...)
You could also go with a wildcard, which is less precise and would match any uri starting with /images/:
(GET "/images/*" [*] ...)
The real answer in this case was that there was a bug in the clojure-couchdb library. The patch is available on github here.
It boils down to adding the {:as :byte-array} map parameter and value to the request sent via clj-http to couch's api.
The other issue in my code was that ring doesn't really know what to do with byte-arrays when it's rendering them. Rather than patching ring, I just wrapped the byte-array into a java.io.ByteArrayInputStream. Here is the complete code for handling the download:
(defn get-image-response
[id]
(let [record (db/get-image id false)]
(-> (response/response (new java.io.ByteArrayInputStream (:data record)))
(response/content-type (:content-type (:content-type record)))
(response/header "Content-Length" (:size record)))))
I'd thought I'd post this as I got it to work through guesswork without a real understanding of what's going on and I thought it might be helpful if someone explained it.
I understand how to get at an element of the :params map in a Compojure handler:
(GET "/something" [some_arg] "this is the response body")
or
(GET "/something" {{some_arg "some_arg"} :params} "this is the response body")
although I don't completely understand what the {some_arg "some_arg"} part is doing :(
I also wanted to access the :remote-addr part of the request as well as some_arg. And I ended up with
(GET "/something" {{some_arg "some_arg"} :params ip :remote-addr}
(do-something-with some_arg ip))
So, I get that the unquoted strings some_arg and ip are the names of variables to which I want the values bound but the map above isn't a valid Clojure map. How does it work?
I also get that this is evaluated against the Ring request map (which is somehow supplied by the defroutes macro) but the expression above isn't a function or macro definition so how can it 'exist' as a valid expression in my code? Is there some sort of suspension of the normal rules for macro arguments? I've been unable to find a definition of the syntax of destructuring forms comprehensible to this non-Lisp'er.
The map is a valid destructuring map. In any place where you bind names, you can use destructuring. You could do the same thing in a let, like this:
user=> (let [{{some-arg "some_arg"} :params ip :remote-addr} {:remote-addr "127.0.0.1" :params {"some_arg" "some_value"}}] [ip some-arg])
["127.0.0.1" "some_value"]
I wrote a post about map destructuring in the context of named arguments, but it applies here. You might find this useful: Clojure - named arguments
There are a lot of blog posts demonstrating destructuring, including this one. I'm not sure which one would be a canonical place to learn from.
I don't pretend to know what exactly compojure does with that map under the hood, but I presume it throws it in a let or something similar as I demonstrated above. GET is a macro, so it doesn't have to evaluate the map you pass it, which is why you wouldn't get an error unless it evaluated it.
user=> (defmacro blah [m])
#'user/blah
user=> (blah {a "b" c "d"})
nil
user=> (defn blah [m])
#'user/blah
user=> (blah {a "b" c "d"})
java.lang.Exception: Unable to resolve symbol: a in this context (NO_SOURCE_FILE:9)
Under the hood, magic happens to that map and it gets passed to a function called destructuring that does the destructuring magic.
There isn't really anything special going on here other than normal macro/special form foo and delayed evaluation.
Destructing takes place within a binding form, and for map destructuring the var to be bound is on the left, and the key is on the right:
user=> (let [{a :foo} {:foo :bar}]
user=* a)
:bar
Compojure is doing a binding form behind the scenes, so that map destructuring form you were using above is effectively turned into something like:
(let [{{some_arg "some_arg"} :params} request]
...)
Where request is an implicitly provided map.
The vector version (e.g., [some_arg]), is an alternative that just binds against the :params map contained in the request.