seqdiag {
"Interceptor Chain" -> Interceptor [label=":enter"]
"Interceptor Chain" <- Interceptor
"Interceptor Chain" -> "Other Interceptors"
"Interceptor Chain" <- "Other Interceptors"
"Interceptor Chain" -> Interceptor [label=":leave"]
"Interceptor Chain" <- Interceptor
}
Liking cljdoc? Tell your friends :D
Interceptors
|
This is the detailed interceptor reference; if you are new to Pedestal you may want to start with the guides:what-is-an-interceptor.adoc. |
Interceptors are the basic unit of work in Pedestal. The core library provides interceptors that are generally useful for creating HTTP web services. Applications augment those with their own logic to handle everything specific the application’s domain.
An interceptor is a Clojure record with four keys:
-
:name
-
:enter
-
:leave
-
:error
The :name key is a keyword, often a namespace-qualified keyword. The :enter and :leave keys are unary functions. The :error key is used for error handling.
An interceptor must provide a :name [1] and at least one of :enter, :leave and :error.
Each function is called with a context-map.adoc and must return either a context map or a {core_async} channel that will deliver a context map; the latter case triggers asynchronous request processing.
Pedestal calls the :enter function on the way "in" to handling a request. It calls the :leave function on the way back "out". This is shown here for a single interceptor:
Either the :enter or :leave function may be omitted without harm.
Before executing the interceptor chain, the interceptors are added to a queue, in the specific order of execution.
During the :enter phase, the next interceptor is popped off the queue, pushed onto the leave stack, and its :enter function, if any, is executed.
Once the handler (or other interceptor) adds a :response to the context, the chain logic switches to :leave mode: it pops interceptors off the leave stack and invokes the :leave function, if any.
Because it’s the leave stack the :leave functions are invoked in the opposite order from the :enter functions.
seqdiag {
"Interceptor Chain" -> A [label=":enter"]
"Interceptor Chain" <- A
"Interceptor Chain" -> B [label=":enter"]
"Interceptor Chain" <- B
"Interceptor Chain" -> C [label=":enter"]
"Interceptor Chain" <- C
"Interceptor Chain" -> C [label=":leave"]
"Interceptor Chain" <- C
"Interceptor Chain" -> B [label=":leave"]
"Interceptor Chain" <- B
"Interceptor Chain" -> A [label=":leave"]
"Interceptor Chain" <- A
}
Both the queue and the stack reside in the context map. Since interceptors can modify the context map, that means they can change the plan of execution for the rest of the request! Interceptors are allowed to enqueue more interceptors to be called, or they can terminate the request.
This process, of running all the interceptor :enter functions, then running the interceptor :leave functions, is called executing the interceptor chain.
Context Bindings
Interceptors expect certain keys to be present in the context map. These context bindings are part of the contract between Pedestal connector and interceptors.
The most important keys are :request, which holds the request-map.adoc, and :response, which (once added to the context) holds the response-map.adoc.
|
Technically, the interceptor pipeline doesn’t know about :request and :response, because the interceptor pipeline is not specifically purposed with HTTP processing; the Pedestal connector or servlet-interceptor.adoc adds these details. |
Further keys are described in the context-map.adoc reference.
Interceptor Return Values
Interceptor functions must return the context passed to it, or a modification of that context.
Returning nil will cause an internal server error.
An :enter or :leave function may return a context map directly. In this case, processing continues with the next interceptor.
If the interceptor is expected to take a long time to return a result, it may instead return a {core_async} channel. Pedestal will yield the request processing thread back to the network adapter (so that it can process other incoming requests) and wait for a value to be produced.
Only one value will be consumed from the returned channel, and the value must be a context map.
Request processing continues once the channel delivers the context map.
|
Chaining With Async Interceptors
Any interceptor downstream of an asynchronous interceptor will be executed in the {core_async} dispatch thread pool. This can be problematic if any later interceptor or handler performs any blocking I/O, as the thread pool is a fixed size. Generally speaking, if any interceptor is asynchronous, all following non-trivial interceptors should also be asynchronous. Trivial interceptors do short computations or make changes to the context map; they do not perform any I/O or other operations that could block the thread they execute on, such as any file or socket I/O. If blocking operations are unavoidable, the interceptor should
make use of the core.async When an interceptor returns a channel, the request processing thread can be returned to the servlet container. This may allow another pending request to be processed while the initial request is parked, waiting for the channel returned by an interceptor to convey the new context map. |
IntoInterceptor
An Interceptor is specifically an instance of the Interceptor record type.
Pedestal is able to convert other values into interceptors using the api:IntoInterceptor[ns=io.pedestal.interceptor] protocol.
Pedestal extends that protocol to the following types:
| Type | Interpretation |
|---|---|
Map | The :enter, :leave, :error, and :name keys are used directly. |
Function | The function is interpreted as a handler. |
List | The list is evaluated and its result is used as an interceptor. [2] Support for List is deprecated. |
Cons | Same as List (and also deprecated) |
Symbol | The symbol is resolved and its target is converted to an interceptor. |
Var | The var is de-referenced and its value is converted to an interceptor. |
Most of these cases are provided to make routing syntax easier, or reflect earlier attempts to improve live reloading at the REPL.
Applications should mainly use the map form as shown in the earlier examples when defining interceptors for routing purposes.
Manipulating the interceptor queue
The queue of interceptors remaining to execute is held in the context-map.adoc. This means that an interceptor can enqueue other interceptors to be executed. In fact, this is exactly how routing works, the router is an interceptor that matches information from incoming requests to specific routes, then enqueues interceptors for that specific route.
Use api:enqueue[ns=io.pedestal.interceptor.chain] to push more interceptors onto the queue.
Use api:terminate[ns=io.pedestal.interceptor.chain] if processing should not continue - though normally, this is accomplished by attaching a :response map (the response-map.adoc) to the context-map.adoc.
|
Interceptor Records
Interceptors that are explicitly enqueued by the application must be defined using the api:interceptor[ns=io.pedestal.interceptor] function. This function takes a value which extends the IntoInterceptor protocol, and returns an Interceptor record. This is not necessary when constructing interceptors used in routing because interceptor representations are transformed to Interceptor records during route expansion. Likewise, interceptors added to the connector-map.adoc (via api:with-interceptor[ns=io.pedestal.connector]) are converted as they are added. |
It’s worth noting that when an interceptor queues additional interceptors for execution, they execute after all interceptors already in the queue (not immediately after the interceptor that modified the queue). This means you could, for example, put a routing interceptor first in the queue, then a few interceptors that provide behavior common to all routes, and those common interceptors will run before any route-specific interceptors.
Handlers
A handler function is a special case of an interceptor. Pedestal treats the handler as a function that accepts a request-map.adoc parameter, and returns a response-map.adoc result.
A handler does not have access to the full execution context, therefore, it cannot manipulate the interceptor queue.
Because a handler takes one kind of thing (request) and returns a different kind of thing (response), it can only be used in the last position of an interceptor stack.
Handlers return a response map; alternately, an asynchronous handler should return a channel that conveys the response map.
Interceptors should always have names [3]. When a handler function is converted to an Interceptor, Pedestal will check to see if the function has :name metadata and use that as the Interceptor’s name.
Failing that, Pedestal will generate an interceptor name from the function’s class name; this does not always provide ideal results.
|
When using terse-syntax.adoc or verbose-syntax.adoc to define routes, a final interceptor with no specfic name (i.e., generated from a handler function) will have its name set to match the route name. In 0.8.0, handler functions will normally always have a name. So, when upgrading from 0.7.x to 0.8.x, you might find that specific interceptors have different names. This is unlikely to cause any issues, but in the unlikely event that this behavior proves to be a problem, it can be disabled. |
| Provide a keyword :name metadata on your function. |
Example:
(def version-handler
^{:name ::get-version} (1)
(fn [_request] {:status 200 :body "0.3.7"}))
; Later, in routes
["/api/version" :get version-handler] (2)| 1 | This is metadata applied to the function itself. If using defn, the metadata would be applied
to the Var, not the function. |
| 2 | Prior to release 0.8.0, this route would be an error, because there is no explicit route name; now the route name will be the same as the interceptor’s name (whether set explicitly, or derived from the function’s class name). |
Error Handling
Pedestal supports defining interceptor-specific error handlers via the :error key. Refer to the error-handling.adoc reference for more details.
Pedestal Interceptors
The io.pedestal/pedestal.service library includes a large set of interceptors that are specialized for HTTP request handling. Many of these interceptors are automatically added to the interceptor queue via api:with-default-interceptors[ns=io.pedestal.connector] or by the api:default-interceptors[] function, using information from the service-map.adoc.
-
api:allow-origin[ns=io.pedestal.http.cors]
-
api:anti-forgery[ns=io.pedestal.http.csrf]
-
api:body-params[ns=io.pedestal.http.body-params]
-
api:dev-allow-origin[ns=io.pedestal.http.cors]
-
api:method-param[ns=io.pedestal.http.route]
-
api:negotiate-content[ns=io.pedestal.http.content-negotiation]
-
api:path-params-decoder[ns=io.pedestal.http.route]
-
api:query-params[ns=io.pedestal.http.route]
-
several from api:*[ns=io.pedestal.http.ring-middlewares] (see also ring.adoc)
Routing-related interceptors are provided by the io.pedestal/pedestal.route library:
-
api:path-params-decoder[ns=io.pedestal.http.route]
-
api:query-params[ns=io.pedestal.http.route]
-
api:router[ns=io.pedestal.http.route]
But these are usually provided automatically, such as via api:with-routes[ns=io.pedestal.connector].
1. Omitting the name may result in a deprecation warning; in the future it may cause a runtime exception.
2. This is supported behavior related to the table router syntax, but is no longer commonly used and is deprecated.
3. In Pedestal 0.8.0 anonymous interceptors are deprecated; in a future release anonymous interceptors may result in a runtime exeption.
Can you improve this documentation? These fine people already did:
Howard M. Lewis Ship & Howard Lewis ShipEdit on GitHub
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close