Liking cljdoc? Tell your friends :D

Ring Nexus Middleware

Middleware to support FCIS (Functional Core, Imperative Shell) style programming in ring handlers through Nexus - a zero-dependency data-driven action dispatch system.

Why?
Getting started
Default actions
State snapshot
Mixing normal ring handlers with FCIS handlers
Error handling
Recommendations
Acknowledgments
License: MIT

Why?

Classic ring handlers are hard to test and 99% of time are impure functions. The classic ring handler goes like this:

Add dependencies (DB connection, client with internal secret, etc) to the request map (or to scope with a hoc)
Do impure stuff in the request handler body
Return a ring map based on the results

This is the "status quo" ring handler:

(defn impure-handler
  [system] ;; inject dependencies through HoF
  (fn [req]
    (let [{:keys [conn]} system
          db (d/db conn)
          input (:body req)
          stuff (get-stuff db)
          bad-input? (compute-bad-input db req)]
      (when bad-input?
        ;; throw response for early exit
        (http-response/bad-request! {:message "Bad input"}))

      (when (should-call-external-service? input)
        (try
          @(notify-service! input)
          (catch ExceptionInfo e
            (http-response/internal-error! {:message "Something went wrong"})))
        (http-response/ok! {:message "All good with notification"}))

      (if
        (should-be-parallel? req)
        (do
          (notify-service! input)
          (http-response/ok {:message "Request issued"}))

        (do
          @(d/transact conn [input])
          (http-response/ok {:message "All good"}))))))

This works, but it is hard to test independently, unless you start-up your entire component system, making your tests be at minimum integration tests or E2E tests.

Using an action dispatch system, ring handlers can become pure:

(defn pure-handler
  [req]
  (let [{:keys [db]} (:nexus/state req)
        input (:body req)
        stuff (get-stuff db)
        bad-input? (compute-bad-input db req)]
    (cond
      bad-input? [[:http-response/bad-request {:message "Bad input"}]]

      (should-call-external-service? input)
      [[:service/notify input
        {:on-success [[:db/transact [(merge stuff input)]]
                      [:http-response/ok
                       {:message "All good with notification"}]],
         :on-fail [[:http-response/internal-error
                    {:message "Something went wrong"}]]}]]

      (should-be-parallel? req)
      [[:process/parallel ;; parallel execution of the actions/effects
        [[:service/notify input]
         [:http-response/ok
          {:message "Request issued"}]]]]

      :else ;; All good, actions executed sequentially
      [[:db/transact [input]]
       [:http-response/ok {:message "All good!"}]])))

NOTE: In the above example, the DB is a pure snapshot (like datomic). For SQL dbs, there needs to be a pre-requisite step of getting all of the required info from the DB

Default actions

ring-nexus- by default provides several ring related effects/actions:

:http/respond effect - takes a ring response map and responds to the request with it.

Convenience actions over :http/respond

:http-response/ok
:http-response/bad-request
:http-response/unauthorized
:http-response/not-found
:http-response/internal-server-error
:http-response/forbidden

It's useful to have a state snapshot in the request, as we do in pure nexus actions. To achieve this, ring-nexus provides a snapshot of the state at the time of the request. The default key containing the state is :nexus/state:

(require '[ring-nexus-middleware :as ring-nexus])

(def store (atom {:hello :world}))

(def nexus
  {:nexus/system->state deref, ;; take store and get a snapshot
   :nexus/effects {:effects/save (fn [_ store path v]
                                   (swap! store assoc-in path v))}})

(defn print-state-handler
  [req]
  (let [state (:nexus/state req)] ;; pure snapshot
    [[:http-response/ok state]]))

(ring-nexus/wrap-nexus print-state-handler nexus store)

The state key can also be changed:

(require '[ring-nexus-middleware :as ring-nexus])

(defn create-user
  [req]
  (let [user-input (:body req)
        state (:my.cool/state req)]
    (if (conflict-input? state (:body req))
      [[:http-response/bad-request {:message "Email aleary exists"}]]
      [[:effects/save [:users (:email user-input)] user-input]
       [:http-response/ok {:message "User saved succesfully"}]])))

(ring-nexus/wrap-nexus create-user nexus store {:ring-nexus/state-k :my.cool/state})

Mixing normal ring handlers with FCIS handlers

ring-nexus mixes seamlessly with classing ring handlers. Simply return a classic ring map and the middleware will be bypassed. The action handler is only triggered when the return type is a vector (of actions).

(defn normal [req] {:status 200 :body {:message "I am normal ring response"}})

(defn nexus [req] [[:http-response/ok {:message "I am FCIS ring response"}]])

Error handling

By default, ring-nexus will throw any errors created in the handlers or during action/effect evaluation. The default error management strategy is fail-fast strategy.

You can overwrite this by passing :ring-nexus/fail-fast? false to wrap-nexus.

ring-nexus acceps :ring-nexus/on-error callback config option. This function will be called when an error triggers during action/effect execution. Combine this with :ring-nexus/fail-fast? false to make your FCIS handlers return regardless of errors.

(def store (atom {}))

(def nexus {:nexus/system->state deref
            :nexus/effects {:effects/save
                            (fn [_ store path v]
                              (throw (ex-info "Error saving to state" {:path path :v v}))
                              (swap! store assoc-in path v))}})

(defn no-throws-please
  [_]
  [[:effects/save [:a] 1]
   [:http-response/ok {:message "No error"}]])

(def handler (wrap-nexus no-throws-please nexus store {:ring-nexus/fail-fast? false
                                                       :ring-nexus/on-error #(prn "Error: " %)}))

(handler {}) ;;  => {:status 200 :body {:message "No error"} :headers {}}

;; Your console will print the error