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)

Creates the base Interceptor Chain provider, connecting a backend to the interceptor chain.

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-interceptors

(default-interceptors service-map)

Builds 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).

Note: No additional interceptors are added if :interceptors key is set.

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. If passing in a seq of route maps, it’s recommended to use io.pedestal.http.route/expand-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. If nil, this interceptor is not added. Default is nil.
  • :resource-path: File path 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, no 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.

dev-interceptors

(dev-interceptors service-map)

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

edn-response

(edn-response obj)

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

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)

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.

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 server-fn. The server map may be passed to start and stop.

service-fn

(service-fn {interceptors :io.pedestal.http/interceptors, :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 service-map)

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

Returns service-map on success.

stop

(stop service-map)

Given service map, stops the server, if running.

Returns service-map on success.

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.