reitit/doc/ring/data_driven_middleware.md

Data-driven Middleware

Ring defines middleware as a function of type handler & args => request => response. It is relatively easy to understand and allows for good performance. A downside is that the middleware chain is just a opaque function, making things like debugging and composition hard. It is too easy to apply the middlewares in wrong order.

For the basics of reitit middleware, read this first.

Reitit defines middleware as data:

1. A middleware can be defined as first-class data entries
2. A middleware can be mounted as a duct-style vector (of middlewares)
3. A middleware can be optimized & compiled against an endpoint
4. A middleware chain can be transformed by the router

Middleware as data

All values in the :middleware vector of route data are expanded into reitit.middleware/Middleware Records by using the reitit.middleware/IntoMiddleware Protocol. By default, functions, maps and Middleware records are allowed.

Records can have arbitrary keys, but the following keys have special purpose:

key	description
:name	Name of the middleware as a qualified keyword
:spec	clojure.spec definition for the route data, see route data validation (optional)
:wrap	The actual middleware function of handler & args => request => response
:compile	Middleware compilation function, see compiling middleware.

Middleware Records are accessible in their raw form in the compiled route results, and thus are available for inventories, creating api-docs, etc.

For the actual request processing, the Records are unwrapped into normal functions and composed into a middleware function chain, yielding zero runtime penalty.

Creating Middleware

The following examples produce identical middleware runtime functions.

Function

(defn wrap [handler id]
  (fn [request]
    (handler (update request ::acc (fnil conj []) id))))

Map

(def wrap3
  {:name ::wrap3
   :description "Middleware that does things."
   :wrap wrap})

Record

(require '[reitit.middleware :as middleware])

(def wrap2
  (middleware/map->Middleware
    {:name ::wrap2
     :description "Middleware that does things."
     :wrap wrap}))

Using Middleware

:middleware is merged to endpoints by the router.

(require '[reitit.ring :as ring])

(defn handler [{::keys [acc]}]
  {:status 200, :body (conj acc :handler)})

(def app
  (ring/ring-handler
    (ring/router
      ["/api" {:middleware [[wrap 1] [wrap2 2]]}
       ["/ping" {:get {:middleware [[wrap3 3]]
                       :handler handler}}]])))

All the middlewares are applied correctly:

(app {:request-method :get, :uri "/api/ping"})
; {:status 200, :body [1 2 3 :handler]}

Compiling middleware

Middlewares can be optimized against an endpoint using middleware compilation.

Ideas for the future

• Support Middleware dependency resolution with new keys :requires and :provides. Values are set of top-level keys of the request. e.g.
  • InjectUserIntoRequestMiddleware requires #{:session} and provides #{:user}
  • AuthorizationMiddleware requires #{:user}

Ideas welcome & see issues for details.