Pedestal

Important Protocols

The major parts of Pedestal are isolated via Clojure protocols. The protocols are for internal structure and external extension. This reference identifies the most important protocols in Pedestal’s structure and how you might use them in an application.

Interceptor Protocols

IntoInterceptor

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.

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

Routing Protocols

These protocols break up the lifecycle of routes and allow both extension points and alternative strategies in several places.

To give you an idea what that means, there are three built-in route definition syntaxes: table, terse, and verbose. There are three built in routing algorithms: linear-search, prefix-tree, and map-tree. An application can use any syntax with any algorithm. Or, an application can create a new syntax while using a built-in algorithm. Or, an application could use a built-in syntax with a new algorithm!

Router

This protocol defines one function: find-route. It takes the router itself and a request map. It must return the route map for the route that it matched.

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

Key

Constructor

:linear-search

linear-search/router

:prefix-tree

prefix-tree/router

:map-tree

map-tree/router

application-supplied function

The function itself, called with sequence of routes as returned by RouterSpecification’s `router-spec function.

RouterSpecification

RouterSpecification creates a routing interceptor from some definition of routes and a constructor. This is the final step in the process of turning route definitions into the executable router.

Whatever is returned from the router-spec function of the protocol must be an interceptor. It must accept a context map and enquque interceptors based on whatever criteria is chooses.

ExpandableRoutes

ExpandableRoutes abstracts over anything that expand-routes knows how to use.

Pedestal extends ExpandableRoutes as follows:

Type

Behavior

clojure.lang.APersistentVector

Interpret the vector as terse routing syntax.

clojure.lang.APersistentMap

Interpret the map as verbose routing syntax.

clojure.lang.APersistentSet

Interpret the set as table routing syntax.

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

Servlet Protocols

These protocols only apply when using the servlet interceptor.

WritableBody

This protocol applies to anything that can be in the :body key of a response map. 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.

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

WritableBodyAsync

This protocol is a more specific version of WritableBody. If the value in the :body key of a response map satisfies WritableBodyAsync, then Pedestal treats it as a streaming result. See Streaming 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.