circuit-breaker-fn.core — circuit-breaker-fn 0.1.4

Main circuit-breaker-fn namespace. If not implementing your own constructs, this is all you need (otherwise see primitives.clj).

cb-agent clj

(cb-agent init & opts)

Var-arg version of cb-agent*.

cb-agent* clj

(cb-agent* init
           {:keys [fail-limit fail-window fail-window-unit success-limit
                   success-block open-timeout timeout-unit drop-fn ex-fn meta]
            :as cb-opts})

Returns a vector of three elements [agent wrapper cbs-atom]. <agent> - agent implementing circuit-breaking semantics (initialised with <init>). <wrapper> - function to call with your send-fn as its argument - returns the correct fn to send to <agent>. <cbs-atom> - an atom holding the internal state of the circuit-breaker. Super useful for debugging/testing. Should only ever be deref-ed (NEVER changed)!

<cb-opts> is expected to contain:

:fail-limit - see primitives/cb-error-handler :fail-window - Time-window in which :fail-limit has an effect (per :fail-window-unit). :success-limit - see primitives/cb-wrap-handler :open-timeout - see primitives/cb-error-handler :drop-fn - see primitives/cb-wrap-handler :ex-fn - see primitives/cb-error-handler

Can optionally contain:

:fail-window-unit - Time-unit for :fail-window (see keys of utils/time-units). :timeout-unit - Time-unit for :open-timeout (see keys of utils/time-units). :success-block - see primitives/cb-wrap-handler :meta - a subset of the agent's final metadata

Limitations/advice:

• You can NOT change the error-handler, nor the error-mode of the returned agent.
• You can/should NOT set a validator to the returned agent, unless you do want errors validation errors to participate in the circuit-breaker, otherwise it will interfere with the agent's custom error-handler.
• The agent returned already carries some metadata. Make sure they don't get lost. If you want your own metadata on the returned agent pass it here as part of cb-params (via the :meta key).
• De-structure the returned vector as [agent cb-wrap] (i.e. ignore the third element).

cb-fn clj

(cb-fn handler & opts)

Var-arg version of cb-fn*.

cb-fn* clj

(cb-fn* handler
        {:keys [fail-limit fail-window fail-window-unit success-limit
                open-timeout timeout-unit drop-fn success-block ex-fn locking?
                try-locking?]
         :as cb-opts})

Given a <handler> fn, returns a circuit-breaker version of it using the provided <cb-opts>.

<cb-opts> is expected to contain:

:fail-limit - see primitives/cb-error-handler :fail-window - Time-window in which :fail-limit has an effect (per :fail-window-unit). :success-limit - see primitives/cb-wrap-handler :open-timeout - see primitives/cb-error-handler :drop-fn - see primitives/cb-wrap-handler :ex-fn - see primitives/cb-error-handler

Can optionally contain:

:fail-window-unit - Time-unit for :fail-window (see keys of utils/time-units). :timeout-unit - Time-unit for :open-timeout (see keys of utils/time-units). :locking? - boolean indicating whether <handler> should be called after successfully acquiring a lock (will wait). :try-locking? - boolean indicating whether <handler> should be called after trying to acquire a lock (will NOT wait).

Providing both locking? & try-locking? doesn't make much sense, so locking? takes precedence. In a typical circuit-breaker scenario, none of them would be needed, simply because <handler> (and its usage) will typically not be racy.