You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: SPEC.rdoc
+16-16Lines changed: 16 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,8 +34,8 @@ The remainder of the request URL's "path", designating the virtual "location" of
34
34
35
35
The <tt>PATH_INFO</tt>, if provided, must be a valid request target or an empty string, as defined by {RFC9110}[https://datatracker.ietf.org/doc/html/rfc9110#target.resource].
36
36
* Only <tt>OPTIONS</tt> requests may have <tt>PATH_INFO</tt> set to <tt>*</tt> (asterisk-form).
37
-
* Only <tt>CONNECT</tt> requests may have <tt>PATH_INFO</tt> set to an authority (authority-form). Note that in <tt>HTTP/2+</tt>, the authority-form is not a valid request target.
38
-
* <tt>CONNECT</tt> and <tt>OPTIONS</tt> requests must not have <tt>PATH_INFO</tt> set to a <tt>URI</tt> (absolute-form).
37
+
* Only <tt>CONNECT</tt> requests may have <tt>PATH_INFO</tt> set to an authority (authority-form). Note that in HTTP/2+, the authority-form is not a valid request target.
38
+
* <tt>CONNECT</tt> and <tt>OPTIONS</tt> requests must not have <tt>PATH_INFO</tt> set to a URI (absolute-form).
39
39
* Otherwise, <tt>PATH_INFO</tt> must start with a <tt>/</tt> and must not include a fragment part starting with <tt>#</tt> (origin-form).
40
40
41
41
==== <tt>QUERY_STRING</tt>
@@ -88,7 +88,7 @@ The URL scheme, which must be one of <tt>http</tt>, <tt>https</tt>, <tt>ws</tt>
88
88
89
89
==== <tt>rack.protocol</tt>
90
90
91
-
An optional +Array+ of +String+ values, containing the protocols advertised by the client in the <tt>upgrade</tt> header (<tt>HTTP/1</tt>) or the <tt>:protocol</tt> pseudo-header (<tt>HTTP/2+</tt>).
91
+
An optional +Array+ of +String+ values, containing the protocols advertised by the client in the <tt>upgrade</tt> header (HTTP/1) or the <tt>:protocol</tt> pseudo-header (HTTP/2+).
92
92
93
93
==== <tt>rack.session</tt>
94
94
@@ -145,12 +145,12 @@ If present, an array of callables that will be run by the server after the respo
145
145
=== The Input Stream
146
146
147
147
The input stream is an +IO+-like object which contains the raw HTTP request data. When applicable, its external encoding must be <tt>ASCII-8BIT</tt> and it must be opened in binary mode. The input stream must respond to +gets+, +each+, and +read+:
148
-
* +gets+ must be called without arguments and return a +String+, or +nil+ on <tt>EOF</tt>.
148
+
* +gets+ must be called without arguments and return a +String+, or +nil+ on EOF (end-of-file).
149
149
* +read+ behaves like <tt>IO#read</tt>. Its signature is <tt>read([length, [buffer]])</tt>.
150
150
* If given, +length+ must be a non-negative Integer (>= 0) or +nil+, and +buffer+ must be a +String+ and may not be +nil+.
151
151
* If +length+ is given and not +nil+, then this method reads at most +length+ bytes from the input stream.
152
-
* If +length+ is not given or +nil+, then this method reads all data until <tt>EOF</tt>.
153
-
* When <tt>EOF</tt> is reached, this method returns +nil+ if +length+ is given and not +nil+, or +""+ if +length+ is not given or is +nil+.
152
+
* If +length+ is not given or +nil+, then this method reads all data until EOF.
153
+
* When EOF is reached, this method returns +nil+ if +length+ is given and not +nil+, or +""+ if +length+ is not given or is +nil+.
154
154
* If +buffer+ is given, then the read data will be placed into +buffer+ instead of a newly created +String+.
155
155
* +each+ must be called without arguments and only yield +String+ values.
156
156
* +close+ can be called on the input stream to indicate that any remaining input is not needed.
@@ -167,13 +167,13 @@ The error stream must respond to +puts+, +write+ and +flush+:
167
167
168
168
The hijacking interfaces provides a means for an application to take control of the HTTP connection. There are two distinct hijack interfaces: full hijacking where the application takes over the raw connection, and partial hijacking where the application takes over just the response body stream. In both cases, the application is responsible for closing the hijacked stream.
169
169
170
-
Full hijacking only works with <tt>HTTP/1</tt>. Partial hijacking is functionally equivalent to streaming bodies, and is still optionally supported for backwards compatibility with older Rack versions.
170
+
Full hijacking only works with HTTP/1. Partial hijacking is functionally equivalent to streaming bodies, and is still optionally supported for backwards compatibility with older Rack versions.
171
171
172
172
==== Full Hijack
173
173
174
-
Full hijack is used to completely take over an <tt>HTTP/1</tt> connection. It occurs before any headers are written and causes the server to ignore any response generated by the application. It is intended to be used when applications need access to the raw <tt>HTTP/1</tt> connection.
174
+
Full hijack is used to completely take over an HTTP/1 connection. It occurs before any headers are written and causes the server to ignore any response generated by the application. It is intended to be used when applications need access to the raw HTTP/1 connection.
175
175
176
-
If <tt>rack.hijack</tt> is present in +env+, it must respond to +call+ and return an +IO+ object which can be used to read and write to the underlying connection using <tt>HTTP/1</tt> semantics and formatting.
176
+
If <tt>rack.hijack</tt> is present in +env+, it must respond to +call+ and return an +IO+ object which can be used to read and write to the underlying connection using HTTP/1 semantics and formatting.
177
177
178
178
==== Partial Hijack
179
179
@@ -205,8 +205,8 @@ This is an HTTP status. It must be an Integer greater than or equal to 100.
205
205
The headers must be an unfrozen +Hash+. The header keys must be +String+ values. Special headers starting <tt>rack.</tt> are for communicating with the server, and must not be sent back to the client.
206
206
207
207
* The headers must not contain a <tt>"status"</tt> key.
208
-
* Header keys must conform to {RFC7230}[https://tools.ietf.org/html/rfc7230] token specification, i.e. cannot contain non-printable <tt>ASCII</tt>, <tt>DQUOTE</tt> or <tt>(),/:;<=>?@[\]{}</tt>.
209
-
* Header keys must not contain uppercase <tt>ASCII</tt> characters (A-Z).
208
+
* Header keys must conform to {RFC7230}[https://tools.ietf.org/html/rfc7230] token specification, i.e. cannot contain non-printable ASCII, <tt>DQUOTE</tt> or <tt>(),/:;<=>?@[\]{}</tt>.
209
+
* Header keys must not contain uppercase ASCII characters (A-Z).
210
210
* Header values must be either a +String+, or an +Array+ of +String+ values, such that each +String+ must not contain <tt>NUL</tt> (<tt>\0</tt>), <tt>CR</tt> (<tt>\r</tt>), or <tt>LF</tt> (<tt>\n</tt>).
211
211
212
212
==== The <tt>content-type</tt> Header
@@ -221,11 +221,11 @@ There must not be a <tt>content-length</tt> header key when the status is <tt>1x
221
221
222
222
If the <tt>rack.protocol</tt> header is present, it must be a +String+, and must be one of the values from the <tt>rack.protocol</tt> array from the environment.
223
223
224
-
Setting this value informs the server that it should perform a connection upgrade. In <tt>HTTP/1</tt>, this is done using the +upgrade+ header. In <tt>HTTP/2</tt>, this is done by accepting the request.
224
+
Setting this value informs the server that it should perform a connection upgrade. In HTTP/1, this is done using the +upgrade+ header. In HTTP/2+, this is done by accepting the request.
225
225
226
226
=== The Body
227
227
228
-
The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+, or a +File+-like object.
228
+
The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+, or an +IO+-like object.
229
229
230
230
The Body must respond to +each+ or +call+. It may optionally respond to +to_path+ or +to_ary+. A Body that responds to +each+ is considered to be an Enumerable Body. A Body that responds to +call+ is considered to be a Streaming Body.
231
231
@@ -239,17 +239,17 @@ If the Body responds to +to_path+, it must return either +nil+ or a +String+. If
239
239
240
240
==== Enumerable Body
241
241
242
-
The Enumerable Body must respond to +each+. It must only be consumed once (calling this method consumes the body). It must not be called after being closed, and must only yield +String+ values.
242
+
The Enumerable Body must respond to +each+, which must only be called once, must not be called after being closed, and must only yield +String+ values.
243
243
244
244
Middleware must not call +each+ directly on the Body. Instead, middleware can return a new Body that calls +each+ on the original Body, yielding at least once per iteration.
245
245
246
246
If the Body responds to +to_ary+, it must return an +Array+ whose contents are identical to that produced by calling +each+. Middleware may call +to_ary+ directly on the Body and return a new Body in its place. In other words, middleware can only process the Body directly if it responds to +to_ary+. If the Body responds to both +to_ary+ and +close+, its implementation of +to_ary+ must call +close+.
247
247
248
248
==== Streaming Body
249
249
250
-
The Streaming Body must respond to +call+. It must only be consumed once (calling this method consumes the body). It must not be called after being closed. It takes a +stream+ argument.
250
+
The Streaming Body must respond to +call+, which must only be called once, must not be called after being closed, and accept a +stream+ argument.
251
251
252
-
The +stream+ argument must respond to: +read+, +write+, <tt><<</tt>, +flush+, +close+, +close_read+, +close_write+, and +closed?+. The semantics of these +IO+ methods must be a best effort match to those of a normal Ruby +IO+ or +Socket+ object, using standard arguments and raising standard exceptions. Servers may simply pass on real +IO+ objects to the Streaming Body. In some cases (e.g. when using <tt>transfer-encoding</tt> or <tt>HTTP/2+</tt>), the server may need to provide a wrapper that implements the required methods, in order to provide the correct semantics.
252
+
The +stream+ argument must respond to: +read+, +write+, <tt><<</tt>, +flush+, +close+, +close_read+, +close_write+, and +closed?+. The semantics of these +IO+ methods must be a best effort match to those of a normal Ruby +IO+ or +Socket+ object, using standard arguments and raising standard exceptions. Servers may simply pass on real +IO+ objects to the Streaming Body. In some cases (e.g. when using <tt>transfer-encoding</tt> or HTTP/2+), the server may need to provide a wrapper that implements the required methods, in order to provide the correct semantics.
0 commit comments