Skip to content
127 lines (97 sloc) 3.95 KB
=== Ring Spec (1.3)
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 that process a given request map to generate
and return a response map.
== 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, Keyword)
The transport protocol, must be one of :http or :https.
(Required, 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.
(Optional, X509Certificate)
The SSL client certificate, if supplied.
(Required, IPersistentMap)
A Clojure map of downcased header name Strings to corresponding header value
(Optional, InputStream)
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, 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, {String, ISeq, File, InputStream})
A representation of the response body, if a response body is appropriate for
the response's status code. The respond body is handled according to its type:
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.
Jump to Line
Something went wrong with that request. Please try again.