Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 238 lines (228 sloc) 13.149 kb
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
1 This specification aims to formalize the Rack protocol. You
2 can (and should) use Rack::Lint to enforce it.
3 When you develop middleware, be sure to add a Lint before and
4 after to catch all mistakes.
5 = Rack applications
85312d6 @raggi Update SPEC
raggi authored
6 A Rack application is a Ruby object (not a class) that
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
7 responds to +call+.
8 It takes exactly one argument, the *environment*
9 and returns an Array of exactly three values:
10 The *status*,
11 the *headers*,
12 and the *body*.
13 == The Environment
14 The environment must be an instance of Hash that includes
15 CGI-like headers. The application is free to modify the
16 environment.
17 The environment is required to include these variables
18 (adopted from PEP333), except when they'd be empty, but see
19 below.
20 <tt>REQUEST_METHOD</tt>:: The HTTP request method, such as
21 "GET" or "POST". This cannot ever
22 be an empty string, and so is
23 always required.
24 <tt>SCRIPT_NAME</tt>:: The initial portion of the request
25 URL's "path" that corresponds to the
26 application object, so that the
27 application knows its virtual
28 "location". This may be an empty
29 string, if the application corresponds
30 to the "root" of the server.
31 <tt>PATH_INFO</tt>:: The remainder of the request URL's
32 "path", designating the virtual
33 "location" of the request's target
34 within the application. This may be an
35 empty string, if the request URL targets
36 the application root and does not have a
37 trailing slash. This value may be
38 percent-encoded when I originating from
39 a URL.
40 <tt>QUERY_STRING</tt>:: The portion of the request URL that
41 follows the <tt>?</tt>, if any. May be
42 empty, but is always required!
43 <tt>SERVER_NAME</tt>, <tt>SERVER_PORT</tt>:: When combined with <tt>SCRIPT_NAME</tt> and <tt>PATH_INFO</tt>, these variables can be used to complete the URL. Note, however, that <tt>HTTP_HOST</tt>, if present, should be used in preference to <tt>SERVER_NAME</tt> for reconstructing the request URL. <tt>SERVER_NAME</tt> and <tt>SERVER_PORT</tt> can never be empty strings, and so are always required.
44 <tt>HTTP_</tt> Variables:: Variables corresponding to the
45 client-supplied HTTP request
46 headers (i.e., variables whose
47 names begin with <tt>HTTP_</tt>). The
48 presence or absence of these
49 variables should correspond with
50 the presence or absence of the
51 appropriate HTTP header in the
9c0c41d @raggi Add link to RFC3875 in Lint and SPEC. Closes #352.
raggi authored
52 request. See <a href="https://tools.ietf.org/html/rfc3875#section-4.1.18">
53 RFC3875 section 4.1.18</a> for specific behavior.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
54 In addition to this, the Rack environment must include these
55 Rack-specific variables:
a947462 @raggi Remove specific version code from Lint
raggi authored
56 <tt>rack.version</tt>:: The Array representing this version of Rack. See Rack::VERSION, that corresponds to the version of this SPEC.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
57 <tt>rack.url_scheme</tt>:: +http+ or +https+, depending on the request URL.
58 <tt>rack.input</tt>:: See below, the input stream.
59 <tt>rack.errors</tt>:: See below, the error stream.
60 <tt>rack.multithread</tt>:: true if the application object may be simultaneously invoked by another thread in the same process, false otherwise.
61 <tt>rack.multiprocess</tt>:: true if an equivalent application object may be simultaneously invoked by another process, false otherwise.
62 <tt>rack.run_once</tt>:: true if the server expects (but does not guarantee!) that the application will only be invoked this one time during the life of its containing process. Normally, this will only be true for a server based on CGI (or something similar).
36a2145 @raggi Straw man for rack.hijack*, connection hijacking!
raggi authored
63 <tt>rack.hijack?</tt>:: present and true if the server supports connection hijacking. See below, hijacking.
64 <tt>rack.hijack</tt>:: an object responding to #call that must be called at least once before using rack.hijack_io. It is recommended #call return rack.hijack_io as well as setting it in env if necessary.
65 <tt>rack.hijack_io</tt>:: if rack.hijack? is true, and rack.hijack has received #call, this will contain an object resembling an IO. See hijacking.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
66 Additional environment specifications have approved to
67 standardized middleware APIs. None of these are required to
68 be implemented by the server.
69 <tt>rack.session</tt>:: A hash like interface for storing request session data.
70 The store must implement:
71 store(key, value) (aliased as []=);
72 fetch(key, default = nil) (aliased as []);
73 delete(key);
74 clear;
75 <tt>rack.logger</tt>:: A common object interface for logging messages.
76 The object must implement:
77 info(message, &block)
78 debug(message, &block)
79 warn(message, &block)
80 error(message, &block)
81 fatal(message, &block)
82 The server or the application can store their own data in the
83 environment, too. The keys must contain at least one dot,
84 and should be prefixed uniquely. The prefix <tt>rack.</tt>
85 is reserved for use with the Rack core distribution and other
86 accepted specifications and must not be used otherwise.
87 The environment must not contain the keys
88 <tt>HTTP_CONTENT_TYPE</tt> or <tt>HTTP_CONTENT_LENGTH</tt>
89 (use the versions without <tt>HTTP_</tt>).
90 The CGI keys (named without a period) must have String values.
91 There are the following restrictions:
92 * <tt>rack.version</tt> must be an array of Integers.
93 * <tt>rack.url_scheme</tt> must either be +http+ or +https+.
94 * There must be a valid input stream in <tt>rack.input</tt>.
95 * There must be a valid error stream in <tt>rack.errors</tt>.
36a2145 @raggi Straw man for rack.hijack*, connection hijacking!
raggi authored
96 * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
97 * The <tt>REQUEST_METHOD</tt> must be a valid token.
98 * The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
99 * The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
100 * The <tt>CONTENT_LENGTH</tt>, if given, must consist of digits only.
101 * One of <tt>SCRIPT_NAME</tt> or <tt>PATH_INFO</tt> must be
102 set. <tt>PATH_INFO</tt> should be <tt>/</tt> if
103 <tt>SCRIPT_NAME</tt> is empty.
104 <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
105 === The Input Stream
106 The input stream is an IO-like object which contains the raw HTTP
107 POST data.
108 When applicable, its external encoding must be "ASCII-8BIT" and it
109 must be opened in binary mode, for Ruby 1.9 compatibility.
110 The input stream must respond to +gets+, +each+, +read+ and +rewind+.
111 * +gets+ must be called without arguments and return a string,
112 or +nil+ on EOF.
113 * +read+ behaves like IO#read. Its signature is <tt>read([length, [buffer]])</tt>.
85312d6 @raggi Update SPEC
raggi authored
114 If given, +length+ must be a non-negative Integer (>= 0) or +nil+, and +buffer+ must
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
115 be a String and may not be nil. If +length+ is given and not nil, then this method
116 reads at most +length+ bytes from the input stream. If +length+ is not given or nil,
117 then this method reads all data until EOF.
118 When EOF is reached, this method returns nil if +length+ is given and not nil, or ""
119 if +length+ is not given or is nil.
120 If +buffer+ is given, then the read data will be placed into +buffer+ instead of a
121 newly created String object.
122 * +each+ must be called without arguments and only yield Strings.
123 * +rewind+ must be called without arguments. It rewinds the input
124 stream back to the beginning. It must not raise Errno::ESPIPE:
125 that is, it may not be a pipe or a socket. Therefore, handler
126 developers must buffer the input data into some rewindable object
127 if the underlying input stream is not rewindable.
128 * +close+ must never be called on the input stream.
129 === The Error Stream
130 The error stream must respond to +puts+, +write+ and +flush+.
131 * +puts+ must be called with a single argument that responds to +to_s+.
132 * +write+ must be called with a single argument that is a String.
133 * +flush+ must be called without arguments and must be called
134 in order to make the error appear for sure.
135 * +close+ must never be called on the error stream.
36a2145 @raggi Straw man for rack.hijack*, connection hijacking!
raggi authored
136 === Hijacking
8a311fb @raggi Add straw man for the after-headers hijack
raggi authored
137 ==== Request (before status)
36a2145 @raggi Straw man for rack.hijack*, connection hijacking!
raggi authored
138 If rack.hijack? is true then rack.hijack must respond to #call.
c33efb8 @raggi Hijack SPEC changes after review discussion
raggi authored
139 rack.hijack must return the io that will also be assigned (or is
36a2145 @raggi Straw man for rack.hijack*, connection hijacking!
raggi authored
140 already present, in rack.hijack_io.
141
142 rack.hijack_io must respond to:
143 <tt>read, write, read_nonblock, write_nonblock, flush, close,
144 close_read, close_write, closed?</tt>
145
146 The semantics of these IO methods must be a best effort match to
147 those of a normal ruby IO or Socket object, using standard
148 arguments and raising standard exceptions. Servers are encouraged
149 to simply pass on real IO objects, although it is recognized that
150 this approach is not directly compatible with SPDY and HTTP 2.0.
151
152 IO provided in rack.hijack_io should preference the
153 IO::WaitReadable and IO::WaitWritable APIs wherever supported.
154
155 There is a deliberate lack of full specification around
156 rack.hijack_io, as semantics will change from server to server.
157 Users are encouraged to utilize this API with a knowledge of their
158 server choice, and servers may extend the functionality of
159 hijack_io to provide additional features to users. The purpose of
160 rack.hijack is for Rack to "get out of the way", as such, Rack only
161 provides the minimum of specification and support.
162
163 If rack.hijack? is false, then rack.hijack should not be set.
164
165 If rack.hijack? is false, then rack.hijack_io should not be set.
8a311fb @raggi Add straw man for the after-headers hijack
raggi authored
166 ==== Response (after headers)
167 It is also possible to hijack a response after the status and headers
168 have been sent.
169 In order to do this, an application may set the special header
170 <tt>rack.hijack</tt> to an object that responds to <tt>call</tt>
171 accepting an argument that conforms to the <tt>rack.hijack_io</tt>
172 protocol.
173
174 After the headers have been sent, and this hijack callback has been
175 called, the application is now responsible for the remaining lifecycle
176 of the IO. The application is also responsible for maintaining HTTP
177 semantics. Of specific note, in almost all cases in the current SPEC,
178 applications will have wanted to specify the header Connection:close in
179 HTTP/1.1, and not Connection:keep-alive, as there is no protocol for
180 returning hijacked sockets to the web server. For that purpose, use the
181 body streaming API instead (progressively yielding strings via each).
182
183 Servers must ignore the <tt>body</tt> part of the response tuple when
184 the <tt>rack.hijack</tt> response API is in use.
185
186 The special response header <tt>rack.hijack</tt> must only be set
187 if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
c33efb8 @raggi Hijack SPEC changes after review discussion
raggi authored
188 ==== Conventions
189 * Middleware should not use hijack unless it is handling the whole
190 response.
191 * Middleware may wrap the IO object for the response pattern.
192 * Middleware should not wrap the IO object for the request pattern. The
193 request pattern is intended to provide the hijacker with "raw tcp".
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
194 == The Response
195 === The Status
196 This is an HTTP status. When parsed as integer (+to_i+), it must be
197 greater than or equal to 100.
198 === The Headers
199 The header must respond to +each+, and yield values of key and value.
8a311fb @raggi Add straw man for the after-headers hijack
raggi authored
200 Special headers starting "rack." are for communicating with the
201 server, and must not be sent back to the client.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
202 The header keys must be Strings.
203 The header must not contain a +Status+ key,
204 contain keys with <tt>:</tt> or newlines in their name,
205 contain keys names that end in <tt>-</tt> or <tt>_</tt>,
206 but only contain keys that consist of
207 letters, digits, <tt>_</tt> or <tt>-</tt> and start with a letter.
208 The values of the header must be Strings,
209 consisting of lines (for multiple header values, e.g. multiple
210 <tt>Set-Cookie</tt> values) seperated by "\n".
211 The lines must not contain characters below 037.
212 === The Content-Type
2138f0b @raggi Cleanup Lint Content-Type section after 3623d04
raggi authored
213 There must not be a <tt>Content-Type</tt>, when the +Status+ is 1xx,
214 204, 205 or 304.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
215 === The Content-Length
216 There must not be a <tt>Content-Length</tt> header when the
2c5b076 @dkubb Add 205 Reset Content to the list of statuses without a message body
dkubb authored
217 +Status+ is 1xx, 204, 205 or 304.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
218 === The Body
219 The Body must respond to +each+
220 and must only yield String values.
221 The Body itself should not be an instance of String, as this will
222 break in Ruby 1.9.
90650c1 @raggi Clarify the body.close spec section
raggi authored
223 If the Body responds to +close+, it will be called after iteration. If
224 the body is replaced by a middleware after action, the original body
225 must be closed first, if it repsonds to close.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored
226 If the Body responds to +to_path+, it must return a String
227 identifying the location of a file whose contents are identical
228 to that produced by calling +each+; this may be used by the
229 server as an alternative, possibly more efficient way to
230 transport the response.
231 The Body commonly is an Array of Strings, the application
232 instance itself, or a File-like object.
233 == Thanks
234 Some parts of this specification are adopted from PEP333: Python
235 Web Server Gateway Interface
236 v1.0 (http://www.python.org/dev/peps/pep-0333/). I'd like to thank
237 everyone involved in that effort.
Something went wrong with that request. Please try again.