Service Map

The service map is a blueprint that Pedestal uses to create all the necessary parts to begin processing requests: a service function, server function, chain provider, router, routes, and default set of interceptors.

Server vs. Service

A server is just the part of the overall system that listens for requests and sends responses; it’s the part most closely tied to your underlying servlet container (Jetty, Tomcat, and so forth). The service runs the show: it’s the server plus everything else: chain provider, the interceptors (including those responsible for routing), and so forth.

An application creates the service map and passes it to create-server. The result is a server map that is ready to be started.

Keep in mind, however, that this is strictly a convenience function that assembles the parts for you. There are use cases where you would not call create-server, but instead assemble a service function, chain provider, and so forth, directly.

Pedestal may add other keys to this map for its own use. Other applications should treat any such keys and their values as implementation details and their behaviour will remain unspecified.

Service Map Keys

In the details below, ::http is an alias to :io.pedestal.http.

Key Always present? Type Description

Key	Always present?	Type	Description
::http/allowed-origins	N	Function, map, or sequence of strings	Determines which origins are allowed for the `allow-origin` interceptor. See "CORS" below.
::http/chain-provider	N	Function	Only assigned when replacing the Servlet Interceptor. Receives the service map, returns an updated map with whatever additional pieces the server function expects. (See ::http/type, below.)
::http/container-options	N	Map	Map of options to pass to the container. Each container, such as Jetty 11, defines it own container-specific options.
::http/enable-csrf	N	Map	A settings map to pass to the `anti-forgery` interceptor. See CSRF below.
::http/enable-session	N	Map	A settings map to pass to the `session` interceptor. Settings are session-store specific. If non-`nil`, this interceptor is added. Default is `nil`.
::http/file-path	N	String	File path used as root by the `file` interceptor. If non-`nil`, this interceptor is added. Default is `nil`.
::http/host	N	String	Hostname, e.g., "localhost". Passed to the container. Defaults to `localhost` ^[1].
::http/initial-context	N	Map	The initial context map that is passed through the interceptor chain; This option makes it possible to place values into the context for all requests.
::http/interceptors	N	Vector	Vector of items that satisfy the `IntoInterceptor` protocol.
::http/join?	N	Boolean	If `false`, do not block the thread that starts the web server. Passed to the container.
::http/method-param-name	N	Keyword	Query string parameter used to set the current HTTP verb. Default is :_method.
::http/mime-types	N	Map of String → String	Mime-types map used by the `content-type` interceptor. Default is `{}`.
::http/not-found-interceptor	N	Interceptor	Interceptor to use when returning a 404 Not Found response. Default is the `not-found` interceptor.
::http/port	N	Integer	Port for the running server. If `nil`, Pedestal defaults to port 80 and HTTP.
::http/resource-path	N	String	File path used as root by the `resource` interceptor. If non-`nil`, the interceptor is added. Default is `nil`.
::http/router	N	Keyword or route constructor	The router implementation to use. Can be :linear-search, :map-tree :prefix-tree, or a custom `Router` constructor function. Defaults to :map-tree, which falls back to :prefix-tree.
::http/routes	Y	Function, `ExpandableRoutes`, or sequence of maps	A route specification that can be processed by `expand-routes` into a routing table.
::http/secure-headers	N	Map of keyword → string	A settings map for various secure headers. See "Secure Headers" below
::http/service-fn	N	Function	A function which can be used as an implementation of the `jakarta.servlet.Servlet.service` method. The function is defined by `create-server`.
::http/service-fn-options	N	Map	Service function options passed to `http-interceptor-service-fn`.
::http/servlet	N	`jakarta.servlet.Servlet`	Present if the servlet is running.
::http/start-fn	N	Function	Zero-arity function that starts the server. Part of the server map.
::http/stop-fn	N	Function	Zero-arity function that stops the server. Part of the server map.
::http/type	Y	Keyword or Function	Container for service or server function. As a keyword, names the container - currently, only :jetty is supported out of the box. As a function, acts as the server function. When omitted, Jetty is the default.
::http/websockets	N	Map	Defines websocket routing. See Websockets.

::http/allowed-origins

Function, map, or sequence of strings

Determines which origins are allowed for the allow-origin interceptor. See "CORS" below.

::http/chain-provider

Function

Only assigned when replacing the Servlet Interceptor. Receives the service map, returns an updated map with whatever additional pieces the server function expects. (See ::http/type, below.)

::http/container-options

Map

Map of options to pass to the container. Each container, such as Jetty 11, defines it own container-specific options.

::http/enable-csrf

Map

A settings map to pass to the anti-forgery interceptor. See CSRF below.

::http/enable-session

Map

A settings map to pass to the session interceptor. Settings are session-store specific. If non-nil, this interceptor is added. Default is nil.

::http/file-path

String

File path used as root by the file interceptor. If non-nil, this interceptor is added. Default is nil.

::http/host

String

Hostname, e.g., "localhost". Passed to the container. Defaults to localhost ^[1].

::http/initial-context

Map

The initial context map that is passed through the interceptor chain; This option makes it possible to place values into the context for all requests.

::http/interceptors

Vector

Vector of items that satisfy the IntoInterceptor protocol.

::http/join?

Boolean

If false, do not block the thread that starts the web server. Passed to the container.

::http/method-param-name

Keyword

Query string parameter used to set the current HTTP verb. Default is :_method.

::http/mime-types

Map of String → String

Mime-types map used by the content-type interceptor. Default is {}.

::http/not-found-interceptor

Interceptor

Interceptor to use when returning a 404 Not Found response. Default is the not-found interceptor.

::http/port

Integer

Port for the running server. If nil, Pedestal defaults to port 80 and HTTP.

::http/resource-path

String

File path used as root by the resource interceptor. If non-nil, the interceptor is added. Default is nil.

::http/router

Keyword or route constructor

The router implementation to use. Can be :linear-search, :map-tree :prefix-tree, or a custom Router constructor function. Defaults to :map-tree, which falls back to :prefix-tree.

::http/routes

Function, ExpandableRoutes, or sequence of maps

A route specification that can be processed by expand-routes into a routing table.

::http/secure-headers

Map of keyword → string

A settings map for various secure headers. See "Secure Headers" below

::http/service-fn

Function

A function which can be used as an implementation of the jakarta.servlet.Servlet.service method. The function is defined by create-server.

::http/service-fn-options

Map

Service function options passed to http-interceptor-service-fn.

::http/servlet

jakarta.servlet.Servlet

Present if the servlet is running.

::http/start-fn

Function

Zero-arity function that starts the server. Part of the server map.

::http/stop-fn

Function

Zero-arity function that stops the server. Part of the server map.

::http/type

Keyword or Function

Container for service or server function. As a keyword, names the container - currently, only :jetty is supported out of the box. As a function, acts as the server function. When omitted, Jetty is the default.

::http/websockets

Map

Defines websocket routing. See Websockets.

default-interceptors

The default-interceptors function is the primary user of the majority of the service map keys; it builds and attaches the ::http/interceptors key (a list of interceptors) from the various other service map keys, but only if the ::http/interceptors is itself nil or missing.

default-interceptors is called automatically from create-server.

You may find that you do not rely on default-interceptors logic, but build your own interceptor chain directly; in that case, simply attach the interceptors as ::http/interceptors before calling create-server. Many of the other service map keys will not be needed, beyond ::http/port and ::http/type.

Cross-Origin Resource Sharing (CORS)

If the ::http/allowed-origins key is non-nil, the allow-origin interceptor is added. The default is nil.

The allowed values are:

a function of one argument that returns a truthy value when an origin is allowed;
a map containing the following keys and values :allowed-origins sequence of strings or a function, :creds boolean indicating whether the client is allowed to send credentials, :max-age a long indicating the number of seconds a client should cache the response, and :methods, indicating the accepted HTTP methods, defaulting to "GET, POST, PUT, DELETE, HEAD, PATCH, OPTIONS";
a sequence of strings matching the scheme, host and port (scheme://host:port) of allowed origins.

Cross-Site Request Forgery (CSRF)

When a value for ::http/enable-csrf is present, the anti-forgery interceptor is added to the queue. This implies that support for HTTP sessions are enabled (Pedestal will add the necessary interceptor automatically).

The value must be a map with the following keys:

Key Value type Description

Key	Value type	Description
:read-token	Function	This function takes a request and returns an anti-forgery token or `nil` if the token does not exist.
:cookie-token	any	truthy value for CSRF double-submit cookies
:error-response	Function	This function takes the response body and returns a 403 Not Authorized response
:error-handler	Function	This function takes the context and returns the appropriate response.

:read-token

Function

This function takes a request and returns an anti-forgery token or nil if the token does not exist.

:cookie-token

any

truthy value for CSRF double-submit cookies

:error-response

Function

This function takes the response body and returns a 403 Not Authorized response

:error-handler

Function

This function takes the context and returns the appropriate response.

Only one of :error-response or :error-handler may be specified.

Secure Headers

When the ::http/secure-headers value is present and non-nil, the secure-headers interceptor is added.

If the key is simply not present in the service map, then a set of default secure headers will be provided:

Key	HTTP Header	Content
:hsts-settings	Strict-Transport-Security	"max-age=31536000; includeSubdomains"
:frame-options-settings	X-Frame-Options	"DENY"
:content-type-settings	X-Content-Type-Options	"nosniff"
:xss-protection-settings	X-XSS-Protection	"1; mode=block"
:download-options-settings	X-Download-Options	"noopen"
:cross-domain-policies-settings	X-Permitted-Cross-Domain-Policies	"none"
:content-security-policy-settings	Content-Security-Policy	"object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;"

Key

HTTP Header

Content

:hsts-settings

Strict-Transport-Security

"max-age=31536000; includeSubdomains"

:frame-options-settings

X-Frame-Options

"DENY"

:content-type-settings

X-Content-Type-Options

"nosniff"

:xss-protection-settings

X-XSS-Protection

"1; mode=block"

:download-options-settings

X-Download-Options

"noopen"

:cross-domain-policies-settings

X-Permitted-Cross-Domain-Policies

"none"

:content-security-policy-settings

Content-Security-Policy

"object-src 'none'; script-src 'unsafe-inline' 'unsafe-eval' 'strict-dynamic' https: http:;"

If the value for ::http/secure-headers is present, it may contain keys and string values for the security headers. Any other keys will be ignored.

Server Map

The server function converts the service map to a server map; much of this is the responsibility of the container-specific server function, such as server - the function is determined from the ::http/type key of the service map.

This function is passed the full service map, and a set of server options; these options are a subset of the service map keys: :host, :port, :join?, :container-options, and :websockets (each as a non-namespaced keyword).

The server function should create a service (e.g., a Jetty Server) and return a map with at least keys :start-fn and :stop-fn. These are then qualified into the io.pedestal.http namespace and merged into the service map.

The start and stop functions use the ::http/start-fn and ::http/stop-fn keys to start and stop the server instance.

Spec Validation

The service map can grow quite complex, with options controlling everything from routing, to security, to container-specific options.

The service map may be validated via Clojure spec; this involves loading the appropriate spec namespaces and using Clojure’s built-in instrumention and testing support.

1. localhost is a safe default and works with local testing, as your test code will be on the same host as the server. However, only connections originating on the local host will be accepted. For production deployments, however, you will usually set this to be 0.0.0.0, which accepts connections from anywhere. This is especially true when running Pedestal inside a Docker container, as all connections (even those from the host, or from another container on the same host) will be network, not localhost, connections.