Permalink
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?
ring/SPEC
Go to fileThis commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
141 lines (107 sloc)
4.67 KB
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
=== 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 | |
map. | |
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: | |
:server-port | |
(Required, Integer) | |
The port on which the request is being handled. | |
:server-name | |
(Required, String) | |
The resolved server name, or the server IP address. | |
:remote-addr | |
(Required, String) | |
The IP address of the client or the last proxy that sent the request. | |
:uri | |
(Required, String) | |
The request URI, excluding the query string and the "?" separator. | |
Must start with "/". | |
:query-string | |
(Optional, String) | |
The query string, if present. | |
:scheme | |
(Required, clojure.lang.Keyword) | |
The transport protocol, must be one of :http or :https. | |
:request-method | |
(Required, clojure.lang.Keyword) | |
The HTTP request method, must be a lowercase keyword corresponding to a HTTP | |
request method, such as :get or :post. | |
:protocol | |
(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. | |
:ssl-client-cert | |
(Optional, java.security.cert.X509Certificate) | |
The SSL client certificate, if supplied. | |
:headers | |
(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. | |
:body | |
(Optional, java.io.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: | |
:status | |
(Required, Integer) | |
The HTTP status code, must be greater than or equal to 100. | |
:headers | |
(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. | |
:body | |
(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: | |
String: | |
Contents are sent to the client as-is. | |
ISeq: | |
Each element of the seq is sent to the client as a string. | |
File: | |
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. | |
InputStream: | |
Contents are consumed from the stream and sent to the client. When the | |
stream is exhausted, it is .close'd. |