io.pedestal.interceptor.chain

Interceptor pattern. Executes a chain of Interceptor functions on a common “context” map, maintaining a virtual “stack”, with error handling and support for asynchronous execution.

enqueue

(enqueue context interceptors)

Adds interceptors to the end of context’s execution queue. Creates the queue if necessary. Returns updated context.

enqueue*

(enqueue* context & interceptors-and-seq)

Like ‘enqueue’ but vararg. If the last argument is a sequence of interceptors, they’re unpacked and to added to the context’s execution queue.

execute

(execute context)(execute context interceptors)

Executes a queue of Interceptors attached to the context. Context must be a map, Interceptors are added with ‘enqueue’.

An Interceptor is a map or map-like object with the keys :enter, :leave, and :error. The value of each key is a function; missing keys or nil values are ignored. When executing a context, first all the :enter functions are invoked in order. As this happens, the Interceptors are pushed on to a stack.

When execution reaches the end of the queue, it begins popping Interceptors off the stack and calling their :leave functions. Therefore :leave functions are called in the opposite order from :enter functions.

Both the :enter and :leave functions are called on a single argument, the context map, and return an updated context.

If any Interceptor function throws an exception, execution stops and begins popping Interceptors off the stack and calling their :error functions. The :error function takes two arguments: the context and an exception. It may either handle the exception, in which case the execution continues with the next :leave function on the stack; or re-throw the exception, passing control to the :error function on the stack. If the exception reaches the end of the stack without being handled, execute will throw it.

execute-only

(execute-only context interceptor-key)(execute-only context interceptor-key interceptors)

Like execute, but only processes the interceptors in a single direction, using interceptor-key (i.e. :enter, :leave) to determine which functions to call.

Executes a queue of Interceptors attached to the context. Context must be a map, Interceptors are added with ‘enqueue’.

An Interceptor Record has keys :enter, :leave, and :error. The value of each key is a function; missing keys or nil values are ignored. When executing a context, all the interceptor-key functions are invoked in order. As this happens, the Interceptors are pushed on to a stack.

terminate

(terminate context)

Removes all remaining interceptors from context’s execution queue. This effectively short-circuits execution of Interceptors’ :enter functions and begins executing the :leave functions.

terminate-when

(terminate-when context pred)

Adds pred as a terminating condition of the context. pred is a function that takes a context as its argument. It will be invoked after every Interceptor’s :enter function. If pred returns logical true, execution will stop at that Interceptor.