Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 125 lines (95 sloc) 4.131 kB
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
1 === Ring Spec (Draft Version)
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
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
mmcgrana authored
4
5
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
6 == Handlers
7 Ring handlers constitute the core logic of the web application and are
8 abstracted from the details of the HTTP protocol. Handlers are implemented as
9 Clojure functions that process a given request map to generate and return a
10 response map.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
11
12
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
13 == Middleware
14 Ring middleware augments the functionality of handlers by invoking them in the
24fe773 @mmcgrana missing line break
mmcgrana authored
15 process of generating responses. Typically middleware will be implemented as a
16 higher-order function that takes one or more handlers and configuration options
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
17 as arguments and returns a new handler with the desired compound behavior.
18
19
20 == Adapters
21 Handlers are run via Ring adapters, which are in turn responsible for
22 implementing the HTTP protocol and abstracting the handlers that they run from
23 the details of the protocol.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
24
cbeebac @mmcgrana Initial refactor towards 0.1.
mmcgrana authored
25 Adapters are implemented as functions of two arguments: a handler and an options
26 map. The options map provides any needed configuration to the adapter, such as
27 the port on which to run.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
28
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
29 Once initialized, adapters receive HTTP requests, parse them to construct an
30 request map, and then invoke their handler with this request map as an
31 argument. Once the handler returns a response map, the adapter uses it to
32 construct and send an HTTP response to the client.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
33
34
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
35 == Request Map
36 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
mmcgrana authored
37 corresponding values:
38
39 :server-port
40 (Required, Integer)
41 The port on which the request is being handled.
42
43 :server-name
44 (Required, String)
45 The resolved server name, or the server IP address.
46
47 :remote-addr
48 (Required, String)
49 The IP address of the client or the last proxy that sent the request.
50
51 :uri
52 (Required, String)
53 The request URI. Must starts with "/".
54
55 :query-string
56 (Optional, String)
57 The query string, if present.
58
59 :scheme
60 (Required, Keyword)
61 The transport protocol, must be one of :http or :https.
62
63 :request-method
64 (Required, Keyword)
65 The HTTP request method, must be one of :get, :head, :options, :put, :post, or
66 :delete.
67
68 :content-type
69 (Optional, String)
70 The MIME type of the request body, if known.
71
72 :content-length
73 (Optional, Integer)
74 The number of bytes in the request body, if known.
75
76 :character-encoding
77 (Optional, String)
78 The name of the character encoding used in the request body, if known.
79
80 :headers
81 (Required, IPersistentMap)
82 A Clojure map of downcased header name Strings to corresponding header value
83 Strings.
84
85 :body
86 (Optional, InputStream)
87 An InputStream for the request body, if present.
88
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
89 If a component invokes another component with a request map containing
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
90 additional keys, these keys must be namespaced using the Clojure
91 :name.space/key-name convention. The ring.* namespaces are reserved.
92
93
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
94 == Response Map
95 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
mmcgrana authored
96
97 :status
98 (Required, Integer)
99 The HTTP status code, must be greater than or equal to 100.
100
101 :headers
102 (Required, IPersistentMap)
103 A Clojure map of HTTP header names to header values. These values may be
104 either Strings, in which case one name/value header will be sent in the
105 HTTP response, or a seq of Strings, in which case a name/value header will be
106 sent for each such String value.
107
108 :body
85690ef @mmcgrana Add ISeq to recognized list of :body types
mmcgrana authored
109 (Optional, {String, ISeq, File, InputStream})
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
110 A representation of the response body, if a response body is appropriate for
111 the response's status code. The respond body is handled according to its type:
112 String:
113 Contents are sent to the client as-is.
30598be @cgrand allow responses bodies to be seqs
cgrand authored
114 ISeq:
115 Each element of the seq is sent to the client as a string.
68e08fb @mmcgrana Initial import from http://github.com/mmcgrana/clj-garden
mmcgrana authored
116 File:
117 Contents at the specified location are sent to the client. The server may
118 use an optimized method to send the file if such a method is available.
119 InputStream:
120 Contents are consumed from the stream and sent to the client. When the
121 stream is exhausted, it is .close'd.
122
37ff268 @mmcgrana rework SPEC and README to reflect new terminology
mmcgrana authored
123 As with request maps, keys in response maps other than those listed above should
124 be appropriately namespaced.
Something went wrong with that request. Please try again.