Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file
Latest commit 033a323 May 2, 2017 History
6 contributors

Users who have contributed to this file

@weavejester @mmcgrana @sdegutis @mvitz @cgrand @arsatiki
=== Ring Spec (1.4)
Ring is defined in terms of handlers, middleware, adapters, requests maps, and
response maps, each of which are described below.
== Handlers
Ring handlers constitute the core logic of the web application. Handlers are
implemented as Clojure functions.
A synchronous handler takes 1 argument, a request map, and returns a response
An asynchronous handler takes 3 arguments: a request map, a callback function
for sending a response and a callback function for raising an exception. The
response callback takes a response map as its argument. The exception callback
takes an exception as its argument.
A handler function may simultaneously support synchronous and asynchronous
behavior by accepting both arities.
== Middleware
Ring middleware augments the functionality of handlers by invoking them in the
process of generating responses. Typically middleware will be implemented as a
higher-order function that takes one or more handlers and configuration options
as arguments and returns a new handler with the desired compound behavior.
== Adapters
Handlers are run via Ring adapters, which are in turn responsible for
implementing the HTTP protocol and abstracting the handlers that they run from
the details of the protocol.
Adapters are implemented as functions of two arguments: a handler and an options
map. The options map provides any needed configuration to the adapter, such as
the port on which to run.
Once initialized, adapters receive HTTP requests, parse them to construct a
request map, and then invoke their handler with this request map as an
argument. Once the handler returns a response map, the adapter uses it to
construct and send an HTTP response to the client.
== Request Map
A request map is a Clojure map containing at least the following keys and
corresponding values:
(Required, Integer)
The port on which the request is being handled.
(Required, String)
The resolved server name, or the server IP address.
(Required, String)
The IP address of the client or the last proxy that sent the request.
(Required, String)
The request URI, excluding the query string and the "?" separator.
Must start with "/".
(Optional, String)
The query string, if present.
(Required, clojure.lang.Keyword)
The transport protocol, must be one of :http or :https.
(Required, clojure.lang.Keyword)
The HTTP request method, must be a lowercase keyword corresponding to a HTTP
request method, such as :get or :post.
(Required, String)
The protocol the request was made with, e.g. "HTTP/1.1".
:content-type [DEPRECATED]
(Optional, String)
The MIME type of the request body, if known.
:content-length [DEPRECATED]
(Optional, Integer)
The number of bytes in the request body, if known.
:character-encoding [DEPRECATED]
(Optional, String)
The name of the character encoding used in the request body, if known.
The SSL client certificate, if supplied.
(Required, clojure.lang.IPersistentMap)
A Clojure map of downcased header name Strings to corresponding header value
Strings. When there are multiple headers with the same name, the header
values are concatenated together, separated by the "," character.
An InputStream for the request body, if present.
== Response Map
A response map is a Clojure map containing at least the following keys and
corresponding values:
(Required, Integer)
The HTTP status code, must be greater than or equal to 100.
(Required, clojure.lang.IPersistentMap)
A Clojure map of HTTP header names to header values. These values may be
either Strings, in which case one name/value header will be sent in the
HTTP response, or a seq of Strings, in which case a name/value header will be
sent for each such String value.
(Optional, ring.core.protocols/StreamableResponseBody)
A representation of the response body, if a response body is appropriate for
the response's status code. The response body must satisfy the
StreamableResponseBody protocol located in the ring.core.protocols namespace.
By default the protocol is satisfied by the following types:
Contents are sent to the client as-is.
Each element of the seq is sent to the client as a string.
Contents at the specified location are sent to the client. The server may
use an optimized method to send the file if such a method is available.
Contents are consumed from the stream and sent to the client. When the
stream is exhausted, it is .close'd.