Pedestal

Service Map

Description

The service map provides a configuration that Pedestal turns into a service function, server function, chain provider, router, routes, and default set of interceptors. This map takes the place of a "builder" API in other frameworks.

An application creates the service map and passes it to create-server for "one stop shopping."

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, etc. directly. See the chain provider sample.

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

Key Always present? Type Description

::http/allowed-origins

N

Function, map, or sequence of strings

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

::http/chain-provider

N

Function

Only assigned when replacing the servlet interceptor. Receives the service-map, returns a service-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. See Deployment and Operations for container-specific options.

::http/enable-csrf

N

Map

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

::http/enable-session

N

Map

A settings map to pass to the ring-middlewares/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 ring-middlewares/file interceptor. If non-nil, this interceptor is added. Default is nil.

::http/host

N

String

Hostname, e.g., "localhost". Passed to the container.

::http/interceptors

N

Vector

Vector of items that satisfy interceptor/IntoInterceptor. No additional interceptors are added if this key is non-nil. The default interceptors are defined by the service map options and http/default-interceptors.

::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 ring-middlewares/content-type interceptor. Default is {}.

::http/not-found-interceptor

N

Interceptor

Interceptor to use when returning a 404 Not Found response. Default is the http/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 ring-middlewares/resource interceptor. If non-nil, the interceptor is added. Default is nil.

::http/router

N

Keyword or route constructor

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

::http/routes

Y

Function, ExpandableRoutes, or sequence of maps

Something that satisfies the route/ExpandableRoutes protocol, a function that returns routes when called, or a seq of route maps that defines a service’s routes. If passing in a seq of route maps, it’s recommended to use route/expand-routes as the full route map contains some redundancies to make processing easier which expand-routes adds automatically.

::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 javax.servlet.Servlet.service method. The function is defined by http/create-server.

::http/servlet

N

javax.servlet.Servlet

Present if the servlet is running.

::http/start-fn

N

function

Zero-arity function that starts the server.

::http/stop-fn

N

function

Zero-arity function that stops the server.

::http/type

Y

Keyword or Function

Container for service or server function. As a keyword, names the container. One of :jetty, :immutant, or :tomcat. As a function, acts as the server function.

CORS

If the ::http/allowed-origins key is non-nil, this 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 the scheme, host and port (scheme://host:port) of allowed origins.

CSRF

When a value for ::http/enable-csrf is present, the CSRF interceptor is added to the queue. This implies sessions are enabled. The value must be a map with the following keys:

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.

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/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"

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.