Why does the order of Ring middleware need to be reversed?

Question

I'm writing some middleware for Ring and I'm really confused as to why I have to reverse the order of the middleware.

I've found this blog post but it doesn't explain why I have to reverse it.

Here's a quick excerpt from the blog post:

(def app
  (wrap-keyword-params (wrap-params my-handler)))

The response would be:

{; Trimmed for brevity
 :params {"my_param" "54"}}

Note that the wrap keyword params didn't get called on it because the params hash didn't exist yet. But when you reverse the order of the middleware like so:

(def app
  (wrap-params (wrap-keyword-params my-handler)))

{; Trimmed for brevity
 :params {:my_param "54"}}

It works.

Could somebody please explain why you have to reverse the order of the middleware?

Answer 1

The answer by danneu is nice, but it only really "clicked" for me after I visualized it in code to see how the chaining of middleware really looks like without the "->" threading macro magic (here's a link if you're not familiar with it). This is what I ended up with:

Let's say you have a request handler that looks like this:

(def amazing-handler
  (-> #'some-amazing-fn
      some-mware
      another-mware
      one-more-mware))

^^ The above handler, written without using a threading macro, would look like this (and I'm extending the indentation on purpose, so it is visually easier to understand which request belongs to which handler):

(def amazing-handler 
  (one-more-mware
                (another-mware
                        ((some-mware #'some-amazing-fn) request-from-another-mware)
                    request-from-one-more-mware)
   original-request))

^^ The above is a style of code that requires us to read it from inside out (which sometimes is hard to follow), the threading macros (-> and ->>) allow us to read code in a natural left-to-right way, but it requires understanding on our part of how exactly it allows us to compose code in this "natural" way behind the scene.

Here's a more complete example:

;; For reference: this is how the end result of the entire "threading" looks like:
;; (((#'some-amazing-fn req-from-up-passed-down) req-from-up-passed-down) original-request)

(defn some-amazing-fn [req] ;; this "req" is the one that will get passed to this function from "some-mware"
  (println "this is the final destination of the req", req)
  (ring.util.http-response/ok {:body "some funny response"}))


(defn one-more-mware [some-argument] ;; the "some-argument" in this case is (another-mware (some-mware #'some-amazing-fn))
  (fn [req] ;; the "req" here is the original request generated by the ring adaptors and passed to this chain of middleware
    (println "|--> from fn inside one-more-mware")
    (some-argument req))) ;; here we provide the another-mware with the request that it will then pass down the chain of middleware, you can imagine that chain, at this point in time, to look like this:
    ;; ((another-mware (some-mware #'some-amazing-fn)) req)


(defn another-mware [dunno-something] ;; the "dunno-something" in this case is (some-mware #'some-amazing-fn)
  (fn [req] ;; the "req" here is passed from one-more-mware function
    (println "|--> from fn inside another-mware")
    (dunno-something req))) ;; here we are passing the "req" down the line to the (some-mware #'some-amazing-fn), so the entire thing behind the scenes, at this point in time, looks like this:
    ;; ((some-mware #'some-amazing-fn) req)


(defn some-mware [some-handler] ;; the "some-handler" arg here refers to #'some-amazing-fn
  (fn [req] ;; the "req" here is passed to this function from another-mware function
    (println "|--> from fn inside some-mware")
    (some-handler req))) ;; here is where we are passing a "req" argument to the #'some-amazing-fn, so behind the scenes it could be thought of as looking like this:
    ;; (#'some-amazing-fn req)


(def amazing-handler
  (-> #'some-amazing-fn
      some-mware
      another-mware
      one-more-mware))

;; |--> from fn inside one-more-mware
;; |--> from fn inside another-mware
;; |--> from fn inside some-mware
;; |--> this is the final destination of the req {.. .. ..}

Answer 2

As you may know the ring app is actually just a function that receives a request map and returns a response map.

In the first case the order in which the functions are applied is this:

request -> [wrap-keyword-params -> wrap-params -> my-handler] -> response

wrap-keyword-params looks for the key :params in the request but it's not there since wrap-params is the one who adds that key based on the "urlencoded parameters from the query string and form body".

When you invert the order of those two:

request -> [wrap-params -> wrap-keyword-params -> my-handler] -> response

You get the desired result since once the request gets to wrap-keyword-params, wrap-params has already added the corresponding keys.

Answer 3

It helps to visualize what middleware actually is.

(defn middleware [handler]
  (fn [request]
    ;; ...
    ;; Do something to the request before sending it down the chain.
    ;; ...
    (let [response (handler request)]
      ;; ...
      ;; Do something to the response that's coming back up the chain.
      ;; ...
      response)))

That right there was pretty much the a-ha moment for me.

What's confusing at first glance is that middleware isn't applied to the request, which is what you're thinking of.

Recall that a Ring app is just a function that takes a request and returns a response (which means it's a handler):

((fn [request] {:status 200, ...}) request)  ;=> response

Let's zoom out a little bit. We get another handler:

((GET "/" [] "Hello") request)  ;=> response

Let's zoom out a little more. We find the my-routes handler:

(my-routes request)  ;=> response

Well, what if you wanted to do something before sending the request to the my-routes handler? You can wrap it with another handler.

((fn [req] (println "Request came in!") (my-routes req)) request)  ;=> response

That's a little hard to read, so let's break out for clarity. We can define a function that returns that handler. Middleware are functions that take a handler and wrap it another handler. It doesn't return a response. It returns a handler that can return a response.

(defn println-middleware [wrapped-func]
  (fn [req]
    (println "Request came in!")
    (wrapped-func req)))

((println-middleware my-route) request)  ;=> response

And if we need to do something before even println-middleware gets the request, then we can wrap it again:

((outer-middleware (println-middleware my-routes)) request)  ;=> response

The key is that my-routes, just like your my-handler, is the only named function that actually takes the request as an argument.

One final demonstration:

(handler3 (handler2 (handler1 request)))  ;=> response
((middleware1 (middleware2 (middleware3 handler1))) request)  ;=> response

I write so much because I can sympathize. But scroll back up to my first middleware example and hopefully it makes more sense.

Answer 4

The ring middleware is a series of functions which when stacked up return a handler function.

The section of the article that answers your question:

In case of Ring wrappers, typically we have “before” decorators that perform some preparations before calling the “real” business function. Since they are higher order functions and not direct function calls, they are applied in reversed order. If one depends on the other, the dependent one needs to be on the “inside”.

Here is a contrived example:

(let [post-wrap (fn [handler]
                  (fn [request]
                    (str (handler request) ", post-wrapped")))
      pre-wrap (fn [handler]
                 (fn [request]
                   (handler (str request ", pre-wrapped"))))
      around (fn [handler]
               (fn [request]
                 (str (handler (str request ", pre-around")) ", post-around")))
      handler (-> (pre-wrap identity)
                  post-wrap
                  around)]
  (println (handler "(this was the input)")))

This prints and returns:

(this was the input), pre-around, pre-wrapped, post-wrapped, post-around
nil