Lambda Island

Compojure is one of the more popular routing libraries for Ring. It’s easy to pick up, and gives you a great foundation to further explore Clojure web development.

Transcript

Compojure is a routing library for Ring. It is particularly known for its minimalism, making it suitable for smaller apps and APIs. It’s also a great starting point for further exploring Clojure web development.

At the heart of any Clojure web stack you’ll find Ring. The Ring specification defines key abstractions for representing HTTP requests and responses using maps, providing a uniform interface to program to.

A Ring adapter is all you need to get started. It forms the bridge between a HTTP server and your own Ring handler, which is a function that handles requests.

Implementing Ring handlers from scratch is a great learning exercise, but in a real world app you don’t want to reinvent the wheel. Every app will need some kind of dispatching based on the requests URI path and HTTP method, like GET, PUT, or POST. This is the job of a routing library, such as Compojure.

I’m starting a new blank project to build upon in this and coming episodes.

lein new compobook

Most leiningen templates don’t yet initialize Git, so it’s got to do that manually before making any changes. This way it’s easy to see later on which parts are provided by the template, and which were added by you.

git init
git add -A
git commit -m '🌳'

In project.clj add some dependencies we’ll be needing: compojure, ring-jetty-adapter, and ring-devel.

You’ll need to know the right version number, which you can find on Clojars, or often also in the project’s README. I’m using the latest stable release of each.

If you’re using “clj-refactor”, then the “add project dependency” function allows you to simply pick the right version from a list. This has the added benefit that the library gets hot-loaded into your running REPL process, so you don’t have to restart it.

(defproject ringbook "0.1.0-SNAPSHOT"
  :dependencies [[org.clojure/clojure "1.8.0"]
                 [ring/ring-jetty-adapter "1.5.0"]
                 [ring/ring-devel "1.5.0"]
                 [compojure "1.5.1"]])

Now switch to core.clj, and get rid of this foo. In the ring.adapter.jetty namespace there’s a run-jetty function. This will launch a Jetty HTTP server, and hook it up to your Ring handler function.

(ns compobook.core
  (:require [ring.adapter.jetty :refer [run-jetty]]))

A handler is a function which takes a request map and returns a response. A response is a map containing a response code, headers, and a body. A 200 OK response is the default, so this is basically the “Hello, World!” of Ring handlers.

(defn handler [request]
  {:body "Lo and Behold, World!"})

Now you can start the Jetty server. Use defonce so this only happens once, even when reloading the namespace. Starting it a second time will cause an error, since only one server can listen on a given port.

The first argument is the handler function, but use the function’s var instead of the function itself. Thanks to this extra level of indirection, when the function is redefined, changes are automatically picked up. We’ll tell Jetty to listen on port 3000, and also to not join the main thread. That last bit is important to not block the REPL.

(defonce server (run-jetty #'handler {:port 3000 :join? false}))

So far so good, now load this namespace from the REPL and try visiting localhost:3000. Cool, that’s a good start.

This isn’t the most useful app yet. Or at least it’s a very limited app. No matter what kind of request you throw at it, it will always return the same thing. Let’s narrow it down a bit.

With pure Ring you could do something like this. Pull out the request method and uri by destructuring them in a let block, and based on these branch to different code paths. As a fallback case, return nil. Re-evaluate the function so the changes are picked up.

Now this handler will only respond to a GET request to the root path. Any other request will cause it to return nil, which the Jetty adapter turns into a 404 Not Found response.

(defn handler [request]
  (let [{:keys [request-method uri]} request]
    (case [request-method uri]
      [:get "/"]
      {:body "Lo and Behold, World!"}

      nil)))

Now let’s see how this looks when we’re using Compojure. Compojure provides a number of handy macros to match on request method and URI patterns. We’ll first look at GET.

The result of GET is itself a handler, so you can assign it to handler directly with def, rather than defn. GET is defined in compojure.core, don’t forget to require it.

This function will now either handle the request if the request method and URI match, or return nil. The last part in the GET form is the code that generates the response. I could return a response map with a body, but Compojure is smart enough to know that if I return just a string it should use that as the body.

A handler that takes care of specific requests and ignores the rest is also known as a route, so this GET creates a single route.

(ns ringbook.core
  (:require [ring.adapter.jetty :refer [run-jetty]]
            [compojure.core :refer [GET]]))

(def handler
  (GET "/" req
    "Lo and Behold, World!"))

The first argument to GET is a URI pattern. The second argument is just a name that we pick, it will create a local variable by that name in the route body, which comes next. Whenever the route body executes, the variable req will be bound to the Ring request map.

Let’s take an example that actually uses this req variable to look something up in the request map. Inside the request map is another map with the headers. Using get-in you can reach into these nested maps to get the value of the "referer" header, which contains the location the user came from.

(def handler
  (GET "/" req
    (str "You came from " (get-in req [:headers "referer"]))))

This req here is what is known as a “binding form”, it’s similar to what you would find in a function’s argument list, or on the left hand side of a let block. This means that, just as in a let block, you can use destructuring.

So let me change this route to look up the header using destructuring. The request is a map, so to destructure it you also use a map form. Inside that are the headers which are a map as well. HTTP headers are not case sensitive, so Ring always downcases them for easy access.

The Referer header is intentially misspelled by the way, and has been since the early nineties. One of those great historical accidents programmers euphemistically like to call “legacy”.

(def handler
  (GET "/" {{referer "referer"} :headers}
    (str "You came from " referer)))

If you expand the GET macro you’ll see something like this (I cleaned it up a bit for readability). Here’s the handler function which will be called when the route matches. You see the destructuring form is in fact now on the left-hand side of a let-block. Makes sense. It’s not a regular let though, but Compojure’s let-request, which has some superpowers of its own. We’ll cover those in a bit.

(make-route :get {:re #"/"}
  (fn [ring-request]
    (let-request [{{referer "referer"} :headers} ring-request]
      (str "You came from " referer))))

Up to now whenever I wanted some changes to show up I re-evaluated the form from my editor, but we can make things a little easier with the wrap-reload middleware.

Require it from the ring.middleware.reload namespace. Then rename handler to app-routes, and define handler as being the routes plus any added middleware.

You need to manually re-evaluate this code once more, or restart your REPL, but after that changed namespaces will be reloaded at the start of each request. This saves you a few keystrokes, but more importantly it saves you a lot of banging your head against the table when your program state starts drifting from what’s defined in the code.

(ns ringbook.core
  (:require [ring.middleware.reload :refer [wrap-reload]] ,,,))

(def app-routes
  (GET "/" req
    ,,,))

(def handler
  (wrap-reload #'app-routes))

(defonce server (run-jetty #'handler ,,,))

We’re building another contact book app, but this time instead of just an API it’ll serve up HTML, generated with hiccup.

Here are some initial contacts so we have some data to work with. Database persistence will have to wait for another time, so instead I’m using an atom again to store the application state.

Also add two helper functions. query-contacts queries the “database” for the list of contacts. You can imagine with some other storage backend that you would only need to change these query functions without touching the rest of the app.

After that create a “view”, a function which renders data to HTML. In this case it takes a list of contacts and shows them as a bullet list. I like to use for loops when turning a collection into Hiccup, I find it reads well. Destructure name and id out of each contact so we can link to the individual contact.

(def initial-contacts [{:id #uuid "a9481ce1-8711-4f4f-af5c-6fb703f5b632",
                        :name "Master Sammy",
                        :email "mastersammy@lambdaisland.com",
                        :twitter "@callmemasta"}
                       {:id #uuid "749db389-7702-4a6b-a761-ee5141451def",
                        :name "Brock Samson",
                        :email "brocksamson@yahoo.com",
                        :twitter "@bigboysamson"}
                       {:id #uuid "e79f8935-3eb7-4774-aa6e-39d862905fc9",
                        :name "Lana Kane",
                        :email "lanakane@lambdaisland.com",
                        :twitter "@gatorkane"}])

(def db (atom {:contacts initial-contacts}))

(defn query-contacts []
  (:contacts @db))

(defn contact-list-view [contacts]
  [:ul
   (for [{:keys [id name]} contacts]
     [:li
      [:a {:href (str "/contacts/" id)} name]])])

Next we need a new route that looks up the contacts and renders them. Compojure comes with a routes function to combine multiple routes into one.

Add routes to the namespace, and while you’re at it also add Hiccup’s html function, and two functions from ring.util.response which are helpful for creating Ring response maps.

Response returns a “200 OK”, while redirect creates a “302 Found” response, which causes the browser to redirect. We’ll use these in our handlers.

(ns ringbook.core
  (:require [compojure.core :refer [routes GET]]
            [hiccup.core :refer [html]]
            [ring.util.response :refer [response redirect]]
            ,,,))

(response "hello!")        ;;=> {:status 200, :headers {}, :body "hello!"}
(redirect "/contacts")     ;;=> {:status 302, :headers {"Location" "/contacts"}, :body ""}

Pass any number of routes to the routes function, and the result is a handler function which tries each routes in turn until it gets a non-nil response.

Remember that a single route (the result of calling GET) is just a function. Given a Ring request map it either returns a result, or nil. With routes you combine several of those into a single handler.

(def app-routes
  (routes
   (GET "/" req ,,,)
   (GET "/contacts" req
     (response (html (contact-list-view (query-contacts)))))))

Now if you look at the result in the browser, you can see the HTML, but it’s rendered as text. That’s because we’re not setting a “Content-Type” header, so the browser assumes it’s plain text.

We could set this header. Let’s first turn this into a threading form, because it’s getting unwieldy. Now assoc-in a Content-Type header and you’re done. Alternatively you can just drop the response function. When Compojure gets a string back as a response, it’ll assume it’s HTML, and it’ll set the right headers for us. Keep that in mind for times when you’re not serving HTML, and set the Content-Type accordingly.

routes is a small but handy helper function. In fact implementing it yourself only takes a few lines of code. Can you see what this does?

(This example is explained in more depth in episode 1. clojure.core/some.)

(defn routes [& rs]
  (fn [req]
    (some #(% req) rs)))

Let’s make a few more changes to these routes. It’s very common to define a set of routes like this and assign it to a var, so Compojure provides an easy macro to do just that, unsurpisingly called defroutes

When a user goes to the root of the app, then let it redirect to “/contacts”, since listing the contacts is all the app does at the moment.

Now in neither of these two routes we’re actually using the request, so let’s rename this variable to _, so it’s clear that it’s ignored.

This last part we cleaned up earlier with a threading macro. This is one refactoring that I use all the time. If your editor or IDE supports it I recommend getting familiar with it.

This way the transformation steps are also more clear, first we query the “database” for the contacts, then render that to hiccup with contact-list-view, then turn that Hiccup into a HTML string.

(defroutes app-routes
  (GET "/" _
    (redirect "/contacts"))
  (GET "/contacts" _
    (-> (query-contacts)
        contact-list-view
        html)))

Compojure has macros for the typical “create”, “read”, “update”, and “delete” operations, also known as “CRUD”, which in HTTP-speak would be POST, GET, PUT, and DELETE. There’s also an ANY macro which matches any HTTP method, and a few lesser used ones, namely HEAD, OPTIONS, and PATCH.

POST
GET
PUT
DELETE

ANY

HEAD
OPTIONS
PATCH

When you click on a contact name in the list then you get a 404 Not Found, let’s add one more route that fixes that.

This time there’s a dynamic segment in the URI, so we need to use a pattern to pull that out. Here’s what that looks like. By using :id in the URI pattern, Compojure knows this section of the path can be anything, and it will pull out the result and put it in the request map under :params.

(GET "/contacts/:id" _ ,,,)

As we saw before we can pull that param out of the response with destructuring right here where we choose what to bind the response map to.

(GET "/contacts/:id" {{:keys [id]} :params}
  ,,,)

But there’s an even easier way. Compojure’s destructuring adds some things on top of Clojure’s regular destructuring. Ring requests maps are always maps, but if you destructure them as a vector, then Compojure will find request parameters with the given names, and assign those. This is handled internally by let-request, which we saw earlier, and it leads to a rather elegant syntax.

(GET "/contacts/:id" [id]
  ,,,)

Now we need a query and a view method for this route, just like we did before.

(defn find-contact [id]
  (->> @db
       :contacts
       (filter #(= id (:id %)))
       first))

(defn contact-view [{:keys [name email twitter] :as contact}]
  [:div
   [:ul.contact
    [:li "Name: " name]
    [:li "Email: " email]
    [:li "Twitter: " twitter]]
   [:a {:href "/contacts"} "← Back"]])

(defroutes app-routes
  ,,,
  (GET "/contacts/:id" [id]
    (-> (find-contact id)
        contact-view
        html)))

With that in place you should now be able to try this in your browser. The 404 error is gone, and the new view seems to be rendering, but it’s not showing any data.

The problem is subtle. Identifiers in our database are UUID’s, but request parameters are always just strings, so we need to convert them first.

Converting incoming parameters to the correct type is such a common operation that Compojure has a special shorthand syntax for it.

In the binding form after the parameter name add this “:«” followed by a function that does the conversion. We’re using this static method on java’s UUID class, so you need to add an “import” clause for that to the namespace declaration.

Reload the page, and you’re done!

(ns ,,,
  (:import java.util.UUID))

(GET "/contacts/:id" [id :<< UUID/fromString]
    (-> (find-contact id)
        contact-view
        html))