Important Protocols

IntoInterceptor allows pretty much anything to become an interceptor when needed.

Routers use this when building routes: anything that satisfies IntoInterceptor is legal to use in the interceptor vector of a route.

This protocol also comes into play when appending new interceptors to the queue.

Pedestal extends IntoInterceptor onto a variety of Clojure and Java types. See the interceptors reference for details of their behaviors.

The combination of routing specification with a routing algorithm results in an instance of the Router interface.

The Router protocol defines just one function: find-route. find-route is passed the Router itself and a request-map.adoc, and must return the route map for the route that it matched. The route map not only identifies the interceptors and handler to add to the interceptor queue, but further captures path variables that may be part of the matched URL (further details TBD).

An instance of Router is returned by the router constructor identified in the application’s service-map.adoc by the key :io.pedestal.http/router.

Whether built-in, or supplied by the application, the constructor is just a function that is passed an expanded route specification, and returns an instance of Router.

The RouterSpecification protocol is used to create a routing interceptor from some definition of routes, and a single Router. This is the final step in the process of turning a routing specification into a routing interceptor.

Whatever is returned from the api:router-spec[ns=io.pedestal.http.route] function of the protocol must be an interceptor. The returned interceptor will include an :enter function that must accept a context-map.adoc and enqueue interceptors based on whatever criteria it chooses.

ExpandableRoutes can convert all kinds of data structures representing a routing specification into a single canonical format that can be used to construct a Router. This occurs inside the api:expand-routes[ns=io.pedestal.http.route] function.

Pedestal provides implementations of ExpandableRoutes for several types:

Since the call to expand-routes comes from application code, it would be rare for an application to need to extend ExpandableRoutes.

The result of expand-routes is a seq of maps that will be passed to the Router.

This protocol applies to anything that can be in the :body key of a response-map.adoc. The two functions in the protocol tell Pedestal what content type the body implies, and how to serialize the body to an output stream.

Pedestal extends this protocol to several Java and Clojure types to produce the behavior detailed in response-bodies.adoc.

Applications should not assume any output stream type more specific than java.io.OutputStream.

This protocol is a more specific version of WritableBody. If the value in the :body key of a response-map.adoc satisfies WritableBodyAsync, then Pedestal treats it as a streaming result. See streaming.adoc for full details.

It would be rare for an application to extend this protocol. Most of the time, an application would be better off providing an NIO channel or a {core_async} channel in the response body.