io.pedestal.http

This namespace ties together the many other namespaces to make it possible to succinctly define a service and start and stop a server for that service.

This namespace is generic as to the underlying container for the server; in some cases, a namespace will be loaded on the fly to convert a service to a server (based on Jetty or Tomcat, or others).

In addition, there is support here for deploying a Pedestal application as part of a WAR file, via the ClojureVarServlet.

create-provider

(create-provider service-map)

Applies default-interceptors (if not already applied) and creates the interceptor chain provider (the basis for starting an embedded servlet container).

create-server

(create-server service-map)(create-server service-map init-fn)

Given a service map, creates and returns an initialized server map which is ready to be started via start. If init-fn, a zero arg function, is provided, it is invoked first.

Creating a server does not start the server; that occurs when the returned map is passed to start.

Notes: - If the service map option :io.pedestal.http/chain-provider is present, it is used to create the server, otherwise a servlet provider will be used. In this case, the type of servlet container created is determined by the :io.pedestal.http/type option. - For servlet containers, the resulting service-map will contain the io.pedestal.http/service-fn key which is useful for testing the service without starting it.

create-servlet

(create-servlet service-map)

Creates a servlet given an options map with keyword keys prefixed by namespace e.g. :io.pedestal.http/interceptors or ::bootstrap/interceptors if the namespace is aliased to bootstrap.

Options:

  • :io.pedestal.http/interceptors: A vector of interceptors that defines a service.

Note: Additional options are passed to default-interceptors if :interceptors is not set.

default-debug-observer-omit

added in 0.7.0

(default-debug-observer-omit key-path)

Default for key paths to ignore when using debug-observer. This is primarily the request and response bodies, anything private to the io.pedestal.interceptor.chain namespaces, and a few routing-related keys (that produce non-useful logged output).

default-interceptors

(default-interceptors service-map)

Builds a default vector of interceptors given a service map with keyword keys prefixed by namespace e.g. :io.pedestal.http/routes (or ::http/routes if the namespace is aliased to http); the interceptor are added to the ::interceptors key.

This function is called from create-servlet and create-provider.

When the ::interceptors key is already present in the context, this function does nothing. This allows application code to invoke default-interceptors, and then add or modify those interceptors before continuing on towards creating and starting a server.

Options:

  • :routes: Something that satisfies the ExpandableRoutes protocol, a function that returns routes when called, or a seq of route maps that defines a service’s routes.
  • :router: 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 on :prefix-tree
  • :file-path: File path used as root by the middlewares/file interceptor (exposing a local directory as the root). If nil, this interceptor is not added. Default is nil.
  • :resource-path: Resource path (on the classpath) used as root by the resource interceptor; If nil, no interceptor is added. Default is nil.
  • :method-param-name: Query string parameter used to set the current HTTP verb. Default is _method.
  • :allowed-origins: Determines what origins are allowed for the allow-origin interceptor. If nil, this interceptor is not added. Default is nil.
  • :not-found-interceptor: Interceptor to use when returning a not found response. Default is the not-found interceptor. Set to nil to disable.
  • :request-logger: Interceptor to log requests entering the interceptor chain. Default is the log-request interceptor. Set to nil to disable request logging.
  • :mime-types: Mime-types map used by the content-type interceptor. Defaults to an empty map.
  • :enable-session: A settings map to include the session middleware interceptor. If nil, this interceptor is not added. Default is nil.
  • :enable-csrf: A settings map to include the csrf-protection interceptor. This implies sessions are enabled. If nil, no interceptor is added. Default is nil.
  • :secure-headers: A settings map for various secure headers. Keys are: :hsts-settings :frame-options-settings :content-type-settings :xss-protection-settings :download-options-settings :cross-domain-policies-settings :content-security-policy-settings If nil, this interceptor is not added. Default is the default secure-headers settings
  • :path-params-decoder: An interceptor to decode path params. Default path-params-decoder. If nil, this interceptor is not added.
  • :tracing: An interceptor to handle telemetry request tracing; this is added as the first interceptor. Defaults to request-tracing-interceptor and can be set to nil to eliminate entirely (added in 0.7.0).

Note that none of the default interceptors will parse the content of the request body (for POST or other requests); individual routes that are of type POST should include the body-params interceptor to do so.

dev-interceptors

(dev-interceptors service-map)

Add dev-allow-origin and exception-debug interceptors to facilitate local development.

This should normally be invoked after default-interceptors.

edn-response

(edn-response obj)

Return a Ring response that will print the given obj to the HTTP output stream in EDN format.

enable-debug-interceptor-observer

added in 0.7.0

(enable-debug-interceptor-observer service-map)(enable-debug-interceptor-observer service-map debug-observer-options)

Enables debug-observer for all request executions. By default, uses default-debug-observer-omit to omit internal or overly verbose context map keys.

The debug observer should not be enabled in production: it is somewhat expensive to identify changes to the context, and some data in the context that might be logged can be verbose, sensitive, or both.

This modifies the ::initial-context key of the service map.

html-body

Set the Content-Type header to “text/html” if the body is a string and a type has not been set.

interceptor-chain-provider

(interceptor-chain-provider service-map)

Called from create-provider, uses the ::chain-provider or ::type key of the service map to create the chain provider.

json-body

Set the Content-Type header to “application/json” and convert the body to JSON if the body is a collection and a type has not been set.

json-print

(json-print obj)

Print object as JSON to out

json-response

(json-response obj)

Return a Ring response that will print the given obj to the HTTP output stream in JSON format.

log-request

Log the request’s method and uri.

not-found

An interceptor that returns a 404 when routing failed to resolve a route.

respond-with

added in 0.7.0

(respond-with context status)(respond-with context status body)(respond-with context status headers body)

Utility function to add a :response map to the interceptor context.

response?

(response? resp)

A valid response is any map that includes an integer :status value.

server

(server service-map)

Converts a service map to a server map.

A service map is largely configuration, including some special callbacks; most of the keys are namespaced. Some keys are applicable to any underlying implementation (such as Jetty or Tomcat), and some are specific to the particular implementation.

This function uses the ::type key to link the service map to a specific implementation; this should be a function that accepts a service map and returns a server map of an unstarted server.

::type can also be a keyword; this keyword is used to build a fully qualified symbol to resolve the function. For example, :jetty will be expanded into io.pedestal.http.jetty/service (but this approach is not favored as it can prevent AOT compilation from pre-compiling the indirectly referenced namespace).

The function is passed the service map and options; these options are a subset of the keys from the service map (::host, ::port, ::join?, ::container-options, and ::websockets); they are extracted from the service map and passed as the options map, after stripping out the namespaces (::host becomes :host).

Returns a server map, which merges the provided service map with additional keys from the map returned by the server-fn. The server map may be passed to start and stop.

A typical embedded app will call create-server, rather than calling this function directly.

service-fn

(service-fn {:io.pedestal.http/keys [interceptors initial-context service-fn-options], :as service-map})

Converts the interceptors for the service into a service function, which is a function that accepts a servlet, servlet request, and servlet response, and initiates the interceptor chain.

servlet

(servlet {service-fn :io.pedestal.http/service-fn, :as service-map})

Converts the service-fn in the service map to a servlet instance.

servlet-destroy

(servlet-destroy service)

servlet-init

(servlet-init service config)

servlet-service

(servlet-service service servlet-req servlet-resp)

start

(start server-map)

Given a server map, as returned by server (usually via create-server), starts the server. The server may later be stopped via stop.

Returns the server map unchanged.

stop

(stop server-map)

Given a server map (started by start), stops the server, if running.

Returns the server map unchanged.

transit-body

Same as transit-json-body – Set the Content-Type header to “application/transit+json” and convert the body to transit+json if the body is a collection and a type has not been set.

transit-body-interceptor

(transit-body-interceptor iname default-content-type transit-format)(transit-body-interceptor iname default-content-type transit-format transit-opts)

Returns an interceptor which sets the Content-Type header to the appropriate value depending on the transit format. Converts the body to the specified Transit format if the body is a collection and a type has not been set. Optionally accepts transit-opts which are handed to trasit/writer and may contain custom write handlers.

Expects the following arguments:

iname - namespaced keyword for the interceptor name default-content-type - content-type string to set in the response transit-format - either :json or :msgpack transit-options - optional. map of options for transit/writer

transit-json-body

Set the Content-Type header to “application/transit+json” and convert the body to transit+json if the body is a collection and a type has not been set.

transit-msgpack-body

Set the Content-Type header to “application/transit+msgpack” and convert the body to transit+msgpack if the body is a collection and a type has not been set.