Skip to content
Newer
Older
100644 207 lines (200 sloc) 11.3 KB
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Dec 31, 2010
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 May 22, 2011
6 A Rack application is a Ruby object (not a class) that
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
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 Mar 17, 2012
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 Jan 1, 2011
54 In addition to this, the Rack environment must include these
55 Rack-specific variables:
56 <tt>rack.version</tt>:: The Array [1,1], representing this version of Rack.
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 Jan 4, 2013
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 Jan 1, 2011
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 Jan 4, 2013
96 * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
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 May 23, 2011
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 Jan 1, 2011
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 Jan 4, 2013
136 === Hijacking
137 If rack.hijack? is true then rack.hijack must respond to #call.
138 rack.hijack should return the io that will also be assigned (or is
139 already present, in rack.hijack_io.
140
141 rack.hijack_io must respond to:
142 <tt>read, write, read_nonblock, write_nonblock, flush, close,
143 close_read, close_write, closed?</tt>
144
145 The semantics of these IO methods must be a best effort match to
146 those of a normal ruby IO or Socket object, using standard
147 arguments and raising standard exceptions. Servers are encouraged
148 to simply pass on real IO objects, although it is recognized that
149 this approach is not directly compatible with SPDY and HTTP 2.0.
150
151 IO provided in rack.hijack_io should preference the
152 IO::WaitReadable and IO::WaitWritable APIs wherever supported.
153
154 There is a deliberate lack of full specification around
155 rack.hijack_io, as semantics will change from server to server.
156 Users are encouraged to utilize this API with a knowledge of their
157 server choice, and servers may extend the functionality of
158 hijack_io to provide additional features to users. The purpose of
159 rack.hijack is for Rack to "get out of the way", as such, Rack only
160 provides the minimum of specification and support.
161
162 If rack.hijack? is false, then rack.hijack should not be set.
163
164 If rack.hijack? is false, then rack.hijack_io should not be set.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
165 == The Response
166 === The Status
167 This is an HTTP status. When parsed as integer (+to_i+), it must be
168 greater than or equal to 100.
169 === The Headers
170 The header must respond to +each+, and yield values of key and value.
171 The header keys must be Strings.
172 The header must not contain a +Status+ key,
173 contain keys with <tt>:</tt> or newlines in their name,
174 contain keys names that end in <tt>-</tt> or <tt>_</tt>,
175 but only contain keys that consist of
176 letters, digits, <tt>_</tt> or <tt>-</tt> and start with a letter.
177 The values of the header must be Strings,
178 consisting of lines (for multiple header values, e.g. multiple
179 <tt>Set-Cookie</tt> values) seperated by "\n".
180 The lines must not contain characters below 037.
181 === The Content-Type
2138f0b @raggi Cleanup Lint Content-Type section after 3623d04
raggi authored Dec 30, 2012
182 There must not be a <tt>Content-Type</tt>, when the +Status+ is 1xx,
183 204, 205 or 304.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
184 === The Content-Length
185 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 Aug 15, 2011
186 +Status+ is 1xx, 204, 205 or 304.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
187 === The Body
188 The Body must respond to +each+
189 and must only yield String values.
190 The Body itself should not be an instance of String, as this will
191 break in Ruby 1.9.
90650c1 @raggi Clarify the body.close spec section
raggi authored Dec 28, 2012
192 If the Body responds to +close+, it will be called after iteration. If
193 the body is replaced by a middleware after action, the original body
194 must be closed first, if it repsonds to close.
859ab9f @raggi Adding SPEC with rake task dependencies
raggi authored Jan 1, 2011
195 If the Body responds to +to_path+, it must return a String
196 identifying the location of a file whose contents are identical
197 to that produced by calling +each+; this may be used by the
198 server as an alternative, possibly more efficient way to
199 transport the response.
200 The Body commonly is an Array of Strings, the application
201 instance itself, or a File-like object.
202 == Thanks
203 Some parts of this specification are adopted from PEP333: Python
204 Web Server Gateway Interface
205 v1.0 (http://www.python.org/dev/peps/pep-0333/). I'd like to thank
206 everyone involved in that effort.
Something went wrong with that request. Please try again.