SPEC

=== Ring Spec (1.2-DRAFT)
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:

: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. Must start with "/".

:query-string
  (Optional, String)
  The query string, if present.

:scheme
  (Required, Keyword)
  The transport protocol, must be one of :http or :https.

:request-method 
  (Required, Keyword) 
  The HTTP request method, must be a lowercase keyword corresponding to a HTTP
  request method, such as :get or :post.

: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, X509Certificate)
  The SSL client certificate, if supplied.

:headers
  (Required, IPersistentMap)
  A Clojure map of downcased header name Strings to corresponding header value 
  Strings.

:body
  (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:

:status
  (Required, Integer)
  The HTTP status code, must be greater than or equal to 100.

:headers
  (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.

:body
  (Optional, {String, File, InputStream, ISeq, CollReduce})
  A representation of the response body, if a response body is appropriate for
  the response's status code. The response body is handled according to its type
  or satisfying protocol:
  String:
    Contents are sent to the client as-is.
  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.
  ISeq or CollReduce (>=1.4, satisfies protocol):
    The body is `reduce`d and each element produced is sent to the client as a
    string.