Writing Handler Middleware

This page has nothing to do with ring middleware. It is about re-frame middleware used in the client. It has nothing to do with servers handling requests.

Sometimes I feel like I’m just pretending to have imposter syndrome.

                                                                                                                         credit

Middleware Makes Imposters

A Middleware is a function.

(handler) -> handler

It takes one parameter, an event handler. And it will return an event handler.

But here's the thing: it won't return a real handler - it will return something that pretends to be a handler.

This imposter handler will often modify the behavior of the original handler, or side-effect in some useful way.

Template

Every Middleware function fits this template:

(defn my-middleware
  [handler]                 ;;  <--- middleware takes a handler argument
  ... in here we return a handler)

And almost 100% of Middleware matches this more fleshed-out template:

(defn my-middleware
  [handler]                 ;;  <--- Middleware takes a handler argument
  (fn imposter-handler      ;;  <--- returns what looks like a handler to me
     [db v]                 ;;  <--- yep takes the right parameters
     ... something in here)))  ;; <--- what happens in here ??

Null Middleware

This is the simplest possible Middleware. But it isn't much of an imposter. It actually returns the original handler untouched. Duh! It was thrown out of middleware school.

(defn does-nothing-middleware
  [handler]
  handler))   ;; give back the same handler

Here's a slightly more complicated version of the Null Middleware:

(defn almost-does-nothing-middleware
  [handler]
  (fn imposter-handler
    [db v]
    (handler db v)))    ;; just on-calls the original handler

Horrible Mistake Middleware

Due to someone else's mistake (probably the guys in marketing), the following Middleware has a bug. It always forwards the wrong event.

(defn buggy-middleware
   [handler]
   (fn imposter-handler
     [db v]
     (handler db [:send-spam true])))    ;; yikes. on-calls with the wrong 'v'

Do you see how the middleware-returned handler "wraps" the given handler. Here this wrapping means the handler gets the wrong event. But it can be used for both good and evil.

Trim-V Middleware

Events (v) always have the form: [:some-id some other parameters]. It would be good if we could trim off that annoying first element :some-id. How about this ...

(defn trim-v
   [handler]
   (fn imposter-handler
     [db v]
     (handler db (rest v))))    ;; get rid of the pesky first element of v

Simple, but slightly risky. v comes in as a vector, but is passed on as a list. Probably wise to put a vec around the rest.

Any handler "wrapped" in `trim-v will have this slightly neater look:

(defn my-handler
   [db [param1 param2]  ;; there's no ugly '_' before param1 
   ...)

Outsideware

In another page I claimed that Middleware should be called Outsideware because it normally does something either before or after the call to the real handler. Either side. Like the bread either side of ham in a sandwich.

Here is an more sophisticated template:

(defn my-middleware
  [handler]                 
  (fn imposter-handler     
     [db v]                 
     (let [ ......  do something BEFORE the handler is called
            val   (handler db v)   ;;   <---- original handler called here
            ......  do something AFTER the handler is called]
     ... return val ?)))

When Middleware does something in the BEFORE position, it is often altering db or v, ahead of passing them into handler. trim-v was this kind of Middleware - it altered v before on-calling.

When Middleware does something in the AFTER position it is often modifying the value returned.

But not always. A great many Middleware don't change db, v or the return at all, and instead they just need to be in the pipeline to produce a side effect, like logging.

A Pure Handler

Okay, now we get interesting.

By default, the re-frame router will pass app-db as the first handler parameter. But that's an atom. If, in our handler, we we start using reset! and swap! on this atom, we'll be writing functions which side-effect. That's ugly. We want to write pure functions.

We'd like to write pure functions which take a map (the value in the atom) and then return a modified map to be put back into the atom.

(defn my-pure-handler
  [m v]               ;;   <-- in first position, 'm' is a map, not an atom
  (assoc m :driven :snow))   ;; returns an updated version of 'm'

But how do we register such a "pure" handler? The answer is that we have to wrap the handler in the right Middleware called pure.

(register-handler 
   :white-event
   (pure my-pure-handler)   ;; <--- pure is middleware which 'adapts' my-pure-handler

This pure middleware is surprisingly easy to write:

(defn pure 
  [handler]
  (fn new-handler
    [app-db event-vec]
    (reset! app-db (handler @app-db event-vec)))

For a more complete version, look for pure in: https://github.com/Day8/re-frame/blob/master/src/re_frame/middleware.cljs

Middleware Factories

A Middleware Factory is a function which returns Middleware. It provides a way of parameterizing the behavior of a Middleware.

Template

Every Middleware Factory fits this template:

(defn a-factory 
  [params]
  (fn middleware              ;;  <-- returns a middleware
    [handler]                 ;;  <--- middleware takes a handler argument
    (fn imposter-handler      ;;  <--- returns what looks like a handler to me
       [db v]                 ;;  <--- yep takes the right parameters
       ... something in here)))  ;; <--- what happens in here ??

Notice that our imposter-handler now closes over (and can use) params.

Look at path in: https://github.com/Day8/re-frame/blob/master/src/re_frame/middleware.cljs