/ring forked from ring-clojure/ring

Permalink
ring/SPEC
Newer
Older
Raw Normal view History
100644 124 lines (95 sloc) 3.86 KB
5f39911 @weavejester Client certificates and OutputStreams for 1.1 SPEC
weavejester authored Dec 28, 2011
1 === Ring Spec (1.1-SNAPSHOT)
9d80bfa @mmcgrana Update readme and spec to reflect 0.1
authored Sep 6, 2009
2 Ring is defined in terms of handlers, middleware, adapters, requests maps, and
3 response maps, each of which are described below.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
4
5
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
6 == Handlers
9d80bfa @mmcgrana Update readme and spec to reflect 0.1
authored Sep 6, 2009
7 Ring handlers constitute the core logic of the web application. Handlers are
8 implemented as Clojure functions that process a given request map to generate
9 and return a response map.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
10
11
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
12 == Middleware
13 Ring middleware augments the functionality of handlers by invoking them in the
24fe773 @mmcgrana missing line break
authored May 5, 2009
14 process of generating responses. Typically middleware will be implemented as a
15 higher-order function that takes one or more handlers and configuration options
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
16 as arguments and returns a new handler with the desired compound behavior.
17
18
19 == Adapters
20 Handlers are run via Ring adapters, which are in turn responsible for
21 implementing the HTTP protocol and abstracting the handlers that they run from
22 the details of the protocol.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
23
cbeebac @mmcgrana Initial refactor towards 0.1.
authored Jul 11, 2009
24 Adapters are implemented as functions of two arguments: a handler and an options
25 map. The options map provides any needed configuration to the adapter, such as
26 the port on which to run.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
27
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
28 Once initialized, adapters receive HTTP requests, parse them to construct an
29 request map, and then invoke their handler with this request map as an
30 argument. Once the handler returns a response map, the adapter uses it to
31 construct and send an HTTP response to the client.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
32
33
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
34 == Request Map
35 A request map is a Clojure map containing at least the following keys and
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
36 corresponding values:
37
38 :server-port
39 (Required, Integer)
40 The port on which the request is being handled.
41
42 :server-name
43 (Required, String)
44 The resolved server name, or the server IP address.
45
46 :remote-addr
47 (Required, String)
48 The IP address of the client or the last proxy that sent the request.
49
50 :uri
51 (Required, String)
7629093 @arsatiki Fixed typo in SPEC
arsatiki authored May 11, 2010
52 The request URI. Must start with "/".
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
53
54 :query-string
55 (Optional, String)
56 The query string, if present.
57
58 :scheme
59 (Required, Keyword)
60 The transport protocol, must be one of :http or :https.
61
62 :request-method
63 (Required, Keyword)
64 The HTTP request method, must be one of :get, :head, :options, :put, :post, or
65 :delete.
66
67 :content-type
68 (Optional, String)
69 The MIME type of the request body, if known.
70
71 :content-length
72 (Optional, Integer)
73 The number of bytes in the request body, if known.
74
75 :character-encoding
76 (Optional, String)
77 The name of the character encoding used in the request body, if known.
78
5f39911 @weavejester Client certificates and OutputStreams for 1.1 SPEC
weavejester authored Dec 28, 2011
79 :ssl-client-cert
80 (Optional, X509Certificate)
81 The SSL client certificate, if supplied.
82
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
83 :headers
84 (Required, IPersistentMap)
85 A Clojure map of downcased header name Strings to corresponding header value
86 Strings.
87
88 :body
89 (Optional, InputStream)
90 An InputStream for the request body, if present.
91
92
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
authored May 5, 2009
93 == Response Map
94 A response map is a Clojure map containing at least the following keys and corresponding values:
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
95
96 :status
97 (Required, Integer)
98 The HTTP status code, must be greater than or equal to 100.
99
100 :headers
101 (Required, IPersistentMap)
102 A Clojure map of HTTP header names to header values. These values may be
103 either Strings, in which case one name/value header will be sent in the
104 HTTP response, or a seq of Strings, in which case a name/value header will be
105 sent for each such String value.
106
107 :body
5f39911 @weavejester Client certificates and OutputStreams for 1.1 SPEC
weavejester authored Dec 28, 2011
108 (Optional, {String, ISeq, File, InputStream, Fn})
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
109 A representation of the response body, if a response body is appropriate for
110 the response's status code. The respond body is handled according to its type:
111 String:
112 Contents are sent to the client as-is.
30598be @cgrand allow responses bodies to be seqs
cgrand authored Jan 20, 2009
113 ISeq:
114 Each element of the seq is sent to the client as a string.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
authored Jan 12, 2009
115 File:
116 Contents at the specified location are sent to the client. The server may
117 use an optimized method to send the file if such a method is available.
118 InputStream:
119 Contents are consumed from the stream and sent to the client. When the
120 stream is exhausted, it is .close'd.
5f39911 @weavejester Client certificates and OutputStreams for 1.1 SPEC
weavejester authored Dec 28, 2011
121 Fn:
122 The OutputStream of the response is passed to the specified function as
123 its only argument.