03-engine.md

Engine

So far, we've only used claro.engine/run!! to resolve our values. But claro's engine offers a lot more.

First off, both [[run!!]] and [[run!]] use the default engine but you can build a custom one using [[claro.engine/engine]]. Engines implement IFn, so they can be called like functions.

(defonce run-engine
  (engine/engine ...))

@(run-engine (->Person 1))

The next sections describe the moving/customizable parts.

Deferred Values

Instead of blocking during resolution, [[run!]] produces a deferred value:

(engine/run! (->Person 1))
;; => << … >>

The default implementation uses Manifold, so you can set execution timeouts or register error handlers:

(-> (->Person 1)
    (engine/run!)
    (d/catch
      (fn [_]
        ::error))
    (d/timeout! 1000 ::timeout))

To use a different implementation (e.g. the one provided in claro.runtime.impl.core-async), use the two-parameter engine constructor:

(defonce run-engine
  (engine/engine
    claro.runtime.impl.core-async/impl
    {}))

This will work for any Resolvable returning a core.async channel.

Note: The implementation used by an engine can be accessed using the [[impl]] function.

Environment

Meaningful data access without configuration pointing at a datasource is rare, so it is necessary for Resolvable values to be aware of said configuration. There are multiple possibilities:

• store it in global vars,
• store it in dynamic vars and use binding around the resolution call,
• store it in the Resolvable record.

These are viable options for claro, too, but the preferred way would be to bind an engine to your environment, using the :env key:

(defonce run-engine
  (engine/engine
    {:env {:db {:subprotocol "postgresql", ...}}}))

The environment will be passed as the second parameter to both [[resolve!]] and [[resolve-batch!]] and can contain things like datastore connections, a user to scope resolution too, etc ...

Parts of the environment can be added or replaced when calling the engine:

(run-engine
  (->Person 1)
  {:env {:db {:subprotocol "mysql", ...}}})

Selector

During each iteration, the resolution engine selects a set of resolvables to process. By default, it attempts to resolve all availble values, but this behaviour can be adjusted by supplying a different [[Selector]] when creating the engine:

(defonce run-engine
  (engine/engine
    {:selector (claro.data.selector/parallel-selector 2)}))

Just like :env this can be overridden on a per-call basis, so you are able to use specialized selection for cases where you need it.

See the [[claro.engine.selector]] namespace for more variants.

Middlewares

The resolver function can be wrapped with custom middlewares using [[claro.engine/wrap]]. It takes two parameters: the environment and the batch of resolvables – all of the same class – and produces a deferred value.

For example, we can write a middleware that attaches a timeout to each single Resolvable batch:

(defn wrap-timeout
  [engine timeout-ms]
  (->> (fn [resolver]
         (fn [env batch]
           (-> (resolver env batch)
               (d/timeout! timeout-ms))))
       (engine/wrap engine)))

More possibilities include caching, tracing, monitoring, circuit-breaking, etc... I recommend checking out the existing middlewares (in claro.middleware.*) for more examples.