io.aviso/rook¶

Rook Routes¶

The route meta is either two or three terms, in a vector:

• The verb to use, such as :get, :post, :head, ... or :all.
• The path to match.
• (optional) A map of path variable constraints.

For example, we might define some additional endpoints to flesh out a CRUD API:

(defn get-widget
  {:rook-route [:get "/:id" {:id #"\d{6}"}]}
  [^:path-param id]
  (r/not-found "WIDGET NOT FOUND"))

(defn update-widget
  {:rook-route [:post "/:id" {:id #"\d{6}"}]}
  [^:path-param id ^:request body]
  (r/response "OK"))

The URI for the get-widget endpoint is /widgets/:id, where the :id path parameter must match the regular expression (six numeric digits).

This is because the namespace’s URI is /widgets and the endpoint’s path is appended to that. Likewise, the update-widget endpoint is also mapped to the URI /widgets/:id, but with the POST verb.

Because of how Pedestal routing is designed, a URI where the :id variable doesn’t match the regular expression will be ignored (it might match some other endpoint, but will most likely match nothing and result in a 404 NOT FOUND response).

This example also illustrates another major feature of Rook: endpoints can have any number of parameters, but use metadata on the parameters to identify what is to be supplied.

• :path-param is used to mark function parameters that should match against a path parameter.
• :request is used to mark function parameters that should match a key stored in the Ring request map.

Namespace Metadata¶

That repetition about the :id path parameter constraint is bothersome. Fortunately, Rook merges metadata from the namespace with metadata from the endpoint, allowing such things to be just defined once:

(ns org.example.widgets
  {:constraints {:id #"\d{6}"}}
  (:require [ring.util.response :as r])

(defn list-widgets
  {:rook-route [:get ""]}
  []
  (r/response {:widgets []})

(defn get-widget
  {:rook-route [:get "/:id"]}
  [^:path-param id]
  (r/not-found "WIDGET NOT FOUND"))

(defn update-widget
  {:rook-route [:post "/:id"]}
  [^:path-param id ^:request body]
  (r/response "OK"))

Here, each endpoint inherits the :id constraint from the namespace.

Namespace Inheritance¶

Nested namespaces may inherit some data from their containing namespace:

• :arg-resolvers - a map from keyword to argument resolver factory
• :interceptors - a vector of interceptors
• :constraints - a map from keyword to regular expression, for constraints

These options flow as follows:

At the function meta data, :arg-resolvers and :interceptors are handled uniformly, but :constraints overrides come from the third value in the :rook-route metadata.

In all cases, a deep merge takes place:

• nested maps are merged together, later overriding earlier
• sequences are concatenated together (using concat for sequences, or into for vectors)

This inheritance is quite useful: for example, the org.example.hotels namespace may define a :hotel-id constraint that will be inherited by the org.example.rooms namespace endpoints.

Interceptor Values¶

The interceptor values can be any of the values that Pedestal accepts as an interceptor:

• An interceptor, as by io.pedestal.interceptor/interceptor.
• A map, which is converted to an interceptor
• A bunch of other things that make sense in terms of Pedestal’s deprecated terse routing syntax

Rook adds one additional option, a keyword.

The keyword references the :interceptor-defs option (passed to io.aviso.rook/gen-table-routes).

A matching value must exist (otherwise, an exception is thrown).

The value is typically a configured interceptor value.

Alternately, the value might be an interceptor generator: a function with metadata :endpoint-interceptor-fn.

Interceptor Generators¶

An interceptor generator is a function that creates an interceptor customized to the particular endpoint.

It is passed a map that describes the endpoint, and returns an interceptor.

The endpoint description has the following keys:

:var

The Clojure Var containing the endpoint function.

:meta

The metadata map for the endpoint function.

:endpoint-name

A string version of the fully qualified name of the var

In this way, the interceptor can use the details of the particular endpoint to generate a custom interceptor.

For example, an interceptor that did some special validation, or authentication, might use metadata on the endpoint function to determine what validations and authentications are necessary for that particular endpoint.

For example, part of Rook’s test suite, uses this Interceptor generator:

(ns sample.dynamic-interceptors
  (:require [io.pedestal.interceptor :refer [interceptor]]))

(def endpoint-labeler
  ;; Note the distinction: this puts the meta data on the function itself, not the Var referencing the
  ;; function.
  ^:endpoint-interceptor-fn
  (fn [endpoint]
    (interceptor {:name ::endpoint-labeler
                  :leave (fn [context]
                           (assoc-in context
                                     [:response :headers "Endpoint"]
                                     (:endpoint-name endpoint)))})))

Applying Interceptors¶

When a namespace provides :interceptor metadata, that’s a list of interceptors to add to every endpoint in the namespace, and in any nested namespaces.

This can cast a wider net than is desirable.

However, each individual endpoint will ultimately end up with its own individual interceptor list.

Further, none of those interceptors will actually execute in a request unless routing selects that particular endpoint to handle the request.

The default interceptors are usually provided by io.pedestal.http/create-server. These cover a number of cases such as handling requests for unmapped URIs, logging, preventing cross-site scripting forgery, and so forth.

The :interceptor metadata in namespaces and elsewhere simply builds up the Endpoint’s Interceptors stage.