Debugging Event Handlers

This page describes useful techniques for debugging re-frame's event handlers.

Event handlers are fairly central to a re-frame app. Only event handlers can update app-db, to "step" an application "forward" from one state to the next.

Approx three kinds of bugs happen in event handlers:

1. an exception gets thrown
2. a handler does not update app-db correctly
3. a handler corrupts app-db

1. An Exception Is Thrown

Under the covers, re-frame uses core.async and, while it is wonderful, core.async produces a special kind of hell when in comes to stacktraces. By the time an exception has passed through a go-loop its stack is mangled beyond repair and you'll have no idea where the exception was thrown.

So, to get an informative stack, you'll need to intercept any exception thrown which is thrown in an event handler, and report it before it disappears into the core.async sausage machine.

Here's some helpful middleware log-ex (will be built-in in v0.3.0):

(defn log-ex
  [handler]
  (fn log-ex-handler
    [db v]
    (try
        (handler-fn db v)     ;; call the handler with a wrapping try
        (catch :default e     ;; ooops
          (do
            (.error js/console e.stack)
            (throw e))))))

If this is complete double dutch to you, then there are other Wiki pages which show how to use and write middleware.

How do I add this log-ex middleware?

Use the 3-arity version of register-handler:

(register-handler 
    :my-event-id
    log-ex      ;;  <----  middleware for my-handler-fn !!!
    my-handler-fn)

Now, every time my-handler-fn throws, I see a sane stacktrace printed to console.

We'd want to have this middleware on every handler, right? Certainly in development. But, in production we might instead want to send the exception to someone like Airbrake.

So our registration might look like this:

(register-handler 
    :my-event-id
    (if goog.DEBUG log-ex log-ex-to-airbrake)     ;; alternative middleware
    my-handler-fn)

goog.DEBUG is a compile time constant, set to false when :optimizations is :advanced, otherwise true. It is supplied by the Google Closure compiler.

2. Updating Incorrectly

You might wonder: is my handler making the right changes to app-db?

The built-in debug middleware can be helpful in this regard. It shows, via console.log:

1. the event, for example: [:attempt-world-record true]
2. the db changes made by the handler in processing the event.

Regarding point 2, debug uses clojure.data/diff to compare the state of db before and after the handler ran. If you look at the docs, you'll notice that diff returns a triple, the first two of which will be displayed by debug in console.log (the 3rd is not interesting).

Two middlewares

So, now we have two middlewares to put on every handler: debug and log-ex.

At the top of our handlers.cljs we might define:

(def standard-middlewares  [log-ex debug])

And then include this standard-middlewares in every handler registration below:

(register-handler 
    :some-id
    standard-middlewares      ;;  <----  here!
    some-handler-fn)

No, wait. I don't want this debug middleware hanging about in my production version, just at develop time. And we still need those runtime exceptions going to airbrake.

So now, we make it:

(def standard-middlewares [ (if goog.DEBUG log-ex log-ex-to-airbrake) 
                            (when goog.DEBUG debug)]) 

Ha! I see a problem, you say. In production, that when is going to leave a nil in the vector. No problem. re-frame filters out nils.

Ha! Ha! I see another problem, you say. Some of my handlers have other middleware. One of them looks like this:

(register-handler 
    :ev-id
    (path :todos)       ;;  <-- already has middleware
    todos-fn)

How can I add this standard-middlewares where there is already middleware?

Like this:

(register-handler 
    :ev-id
    [standard-middlewares (path :todos)]       ;;  <--  put both in a vector
    todos-fn)

But that's a vector in a vector? Surely, that a problem?. Actually, no, re-frame will flatten any level of vector nesting, and remove nils before composing the resulting middleware.

3. Checking DB Integrity

I'd recommend always having a schema for your app-db, specifically a Prismatic Schema. If ever herbert is ported to clojurescript, it might be a good candidate too but, for the moment, a Prismatic Schema.

Schemas serve as invaluable documentation, plus ...

Once you have a schema for your app-db, you can check it is valid at any time. The most obvious time to recheck the integrity of app-db is immediately after a handler has changed it. In effect, we want to recheck after any handler has run.

Let's start with a schema and a way to validate a db against that schema. I would typically put this stuff in db.cljs.

(ns my.namespace.db
  (:require
    [schema.core :as s]))

;; As exactly as possible, describe the correct shape of app-db 
;; Add a lot of helpful comments. This will be an important resource
;; for someone looking at you code for the first time.
(def schema           
  {:a {:b s/Str
       :c s/Int}
   :d [{:e s/Keyword
        :f [s/Num]}]})

(defn valid-schema?
  "validate the given db, writing any problems to console.error"
  [db]
  (let [res (s/check schema db)]
    (if (some? res)
      (.error js/console (str "schema problem: " res)))))

Now, let's organise for our app-db to be validated against the schema after every handler. We'll use the built-in after middleware factory:

(def standard-middlewares [(if goog.DEBUG log-ex log-ex-to-airbrake) 
                           (when goog.DEBUG debug)
                           (when goog.DEBUG (after db/valid-schema?))]) ;; <-- new

BTW, we could have written it without vectors, using comp:

(def standard-middlewares (if goog.DEBUG               ;; not a vector
                            (comp log-ex debug (after db/valid-schema?))  ;; comp used
                            log-ex-to-airbrake))

Now, the instant a handler messes up the structure of app-db you'll be alerted. But this overhead won't be there in production.

These 3 steps will go a very long way to helping you to debug your event handlers.