rack 2.2.4 → 3.0.0.beta1

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of rack might be problematic. Click here for more details.

Files changed (84) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +152 -71
  3. data/CONTRIBUTING.md +53 -47
  4. data/MIT-LICENSE +1 -1
  5. data/README.md +287 -0
  6. data/Rakefile +40 -7
  7. data/SPEC.rdoc +175 -130
  8. data/contrib/LICENSE.md +7 -0
  9. data/contrib/logo.webp +0 -0
  10. data/lib/rack/auth/abstract/handler.rb +3 -1
  11. data/lib/rack/auth/abstract/request.rb +3 -1
  12. data/lib/rack/auth/digest/md5.rb +1 -131
  13. data/lib/rack/auth/digest/nonce.rb +1 -54
  14. data/lib/rack/auth/digest/params.rb +1 -54
  15. data/lib/rack/auth/digest/request.rb +1 -43
  16. data/lib/rack/auth/digest.rb +256 -0
  17. data/lib/rack/body_proxy.rb +3 -1
  18. data/lib/rack/builder.rb +60 -42
  19. data/lib/rack/cascade.rb +2 -0
  20. data/lib/rack/chunked.rb +16 -13
  21. data/lib/rack/common_logger.rb +23 -18
  22. data/lib/rack/conditional_get.rb +18 -15
  23. data/lib/rack/constants.rb +62 -0
  24. data/lib/rack/content_length.rb +12 -16
  25. data/lib/rack/content_type.rb +8 -5
  26. data/lib/rack/deflater.rb +40 -26
  27. data/lib/rack/directory.rb +9 -3
  28. data/lib/rack/etag.rb +14 -23
  29. data/lib/rack/events.rb +4 -0
  30. data/lib/rack/file.rb +2 -0
  31. data/lib/rack/files.rb +15 -17
  32. data/lib/rack/head.rb +9 -8
  33. data/lib/rack/headers.rb +154 -0
  34. data/lib/rack/lint.rb +764 -684
  35. data/lib/rack/lock.rb +2 -5
  36. data/lib/rack/logger.rb +2 -0
  37. data/lib/rack/media_type.rb +1 -1
  38. data/lib/rack/method_override.rb +4 -0
  39. data/lib/rack/mime.rb +8 -0
  40. data/lib/rack/mock.rb +1 -271
  41. data/lib/rack/mock_request.rb +166 -0
  42. data/lib/rack/mock_response.rb +124 -0
  43. data/lib/rack/multipart/generator.rb +7 -5
  44. data/lib/rack/multipart/parser.rb +118 -61
  45. data/lib/rack/multipart/uploaded_file.rb +4 -0
  46. data/lib/rack/multipart.rb +20 -40
  47. data/lib/rack/null_logger.rb +9 -0
  48. data/lib/rack/query_parser.rb +76 -44
  49. data/lib/rack/recursive.rb +2 -0
  50. data/lib/rack/reloader.rb +0 -2
  51. data/lib/rack/request.rb +187 -89
  52. data/lib/rack/response.rb +131 -61
  53. data/lib/rack/rewindable_input.rb +24 -5
  54. data/lib/rack/runtime.rb +7 -6
  55. data/lib/rack/sendfile.rb +30 -25
  56. data/lib/rack/show_exceptions.rb +15 -2
  57. data/lib/rack/show_status.rb +17 -7
  58. data/lib/rack/static.rb +8 -8
  59. data/lib/rack/tempfile_reaper.rb +15 -4
  60. data/lib/rack/urlmap.rb +3 -1
  61. data/lib/rack/utils.rb +199 -173
  62. data/lib/rack/version.rb +9 -4
  63. data/lib/rack.rb +5 -76
  64. data/rack.gemspec +6 -6
  65. metadata +22 -34
  66. data/README.rdoc +0 -306
  67. data/bin/rackup +0 -5
  68. data/contrib/rack.png +0 -0
  69. data/contrib/rack.svg +0 -150
  70. data/contrib/rack_logo.svg +0 -164
  71. data/lib/rack/core_ext/regexp.rb +0 -14
  72. data/lib/rack/handler/cgi.rb +0 -59
  73. data/lib/rack/handler/fastcgi.rb +0 -100
  74. data/lib/rack/handler/lsws.rb +0 -61
  75. data/lib/rack/handler/scgi.rb +0 -71
  76. data/lib/rack/handler/thin.rb +0 -36
  77. data/lib/rack/handler/webrick.rb +0 -129
  78. data/lib/rack/handler.rb +0 -104
  79. data/lib/rack/lobster.rb +0 -70
  80. data/lib/rack/server.rb +0 -466
  81. data/lib/rack/session/abstract/id.rb +0 -523
  82. data/lib/rack/session/cookie.rb +0 -203
  83. data/lib/rack/session/memcache.rb +0 -10
  84. data/lib/rack/session/pool.rb +0 -85
data/lib/rack/lint.rb CHANGED
@@ -2,6 +2,9 @@
2
2
 
3
3
  require 'forwardable'
4
4
 
5
+ require_relative 'constants'
6
+ require_relative 'utils'
7
+
5
8
  module Rack
6
9
  # Rack::Lint validates your application and the requests and
7
10
  # responses according to the Rack spec.
@@ -9,798 +12,875 @@ module Rack
9
12
  class Lint
10
13
  def initialize(app)
11
14
  @app = app
12
- @content_length = nil
13
15
  end
14
16
 
15
17
  # :stopdoc:
16
18
 
17
19
  class LintError < RuntimeError; end
18
- module Assertion
19
- def assert(message)
20
- unless yield
21
- raise LintError, message
22
- end
23
- end
24
- end
25
- include Assertion
26
-
27
- ## This specification aims to formalize the Rack protocol. You
20
+ # AUTHORS: n.b. The trailing whitespace between paragraphs is important and
21
+ # should not be removed. The whitespace creates paragraphs in the RDoc
22
+ # output.
23
+ #
24
+ ## This specification aims to formalize the Rack protocol. You
28
25
  ## can (and should) use Rack::Lint to enforce it.
29
26
  ##
30
27
  ## When you develop middleware, be sure to add a Lint before and
31
28
  ## after to catch all mistakes.
32
-
29
+ ##
33
30
  ## = Rack applications
34
-
31
+ ##
35
32
  ## A Rack application is a Ruby object (not a class) that
36
33
  ## responds to +call+.
37
34
  def call(env = nil)
38
- dup._call(env)
35
+ Wrapper.new(@app, env).response
39
36
  end
40
37
 
41
- def _call(env)
42
- ## It takes exactly one argument, the *environment*
43
- assert("No env given") { env }
44
- check_env env
45
-
46
- env[RACK_INPUT] = InputWrapper.new(env[RACK_INPUT])
47
- env[RACK_ERRORS] = ErrorWrapper.new(env[RACK_ERRORS])
48
-
49
- ## and returns an Array of exactly three values:
50
- ary = @app.call(env)
51
- assert("response is not an Array, but #{ary.class}") {
52
- ary.kind_of? Array
53
- }
54
- assert("response array has #{ary.size} elements instead of 3") {
55
- ary.size == 3
56
- }
57
-
58
- status, headers, @body = ary
59
- ## The *status*,
60
- check_status status
61
- ## the *headers*,
62
- check_headers headers
63
-
64
- hijack_proc = check_hijack_response headers, env
65
- if hijack_proc && headers.is_a?(Hash)
66
- headers[RACK_HIJACK] = hijack_proc
38
+ class Wrapper
39
+ def initialize(app, env)
40
+ @app = app
41
+ @env = env
42
+ @response = nil
43
+ @head_request = false
44
+
45
+ @status = nil
46
+ @headers = nil
47
+ @body = nil
48
+ @invoked = nil
49
+ @content_length = nil
50
+ @closed = false
51
+ @size = 0
67
52
  end
68
53
 
69
- ## and the *body*.
70
- check_content_type status, headers
71
- check_content_length status, headers
72
- @head_request = env[REQUEST_METHOD] == HEAD
73
- [status, headers, self]
74
- end
54
+ def response
55
+ ## It takes exactly one argument, the *environment*
56
+ raise LintError, "No env given" unless @env
57
+ check_environment(@env)
75
58
 
76
- ## == The Environment
77
- def check_env(env)
78
- ## The environment must be an unfrozen instance of Hash that includes
79
- ## CGI-like headers. The application is free to modify the
80
- ## environment.
81
- assert("env #{env.inspect} is not a Hash, but #{env.class}") {
82
- env.kind_of? Hash
83
- }
84
- assert("env should not be frozen, but is") {
85
- !env.frozen?
86
- }
87
-
88
- ##
89
- ## The environment is required to include these variables
90
- ## (adopted from PEP333), except when they'd be empty, but see
91
- ## below.
92
-
93
- ## <tt>REQUEST_METHOD</tt>:: The HTTP request method, such as
94
- ## "GET" or "POST". This cannot ever
95
- ## be an empty string, and so is
96
- ## always required.
97
-
98
- ## <tt>SCRIPT_NAME</tt>:: The initial portion of the request
99
- ## URL's "path" that corresponds to the
100
- ## application object, so that the
101
- ## application knows its virtual
102
- ## "location". This may be an empty
103
- ## string, if the application corresponds
104
- ## to the "root" of the server.
105
-
106
- ## <tt>PATH_INFO</tt>:: The remainder of the request URL's
107
- ## "path", designating the virtual
108
- ## "location" of the request's target
109
- ## within the application. This may be an
110
- ## empty string, if the request URL targets
111
- ## the application root and does not have a
112
- ## trailing slash. This value may be
113
- ## percent-encoded when originating from
114
- ## a URL.
115
-
116
- ## <tt>QUERY_STRING</tt>:: The portion of the request URL that
117
- ## follows the <tt>?</tt>, if any. May be
118
- ## empty, but is always required!
119
-
120
- ## <tt>SERVER_NAME</tt>:: When combined with <tt>SCRIPT_NAME</tt> and
121
- ## <tt>PATH_INFO</tt>, these variables can be
122
- ## used to complete the URL. Note, however,
123
- ## that <tt>HTTP_HOST</tt>, if present,
124
- ## should be used in preference to
125
- ## <tt>SERVER_NAME</tt> for reconstructing
126
- ## the request URL.
127
- ## <tt>SERVER_NAME</tt> can never be an empty
128
- ## string, and so is always required.
129
-
130
- ## <tt>SERVER_PORT</tt>:: An optional +Integer+ which is the port the
131
- ## server is running on. Should be specified if
132
- ## the server is running on a non-standard port.
133
-
134
- ## <tt>HTTP_</tt> Variables:: Variables corresponding to the
135
- ## client-supplied HTTP request
136
- ## headers (i.e., variables whose
137
- ## names begin with <tt>HTTP_</tt>). The
138
- ## presence or absence of these
139
- ## variables should correspond with
140
- ## the presence or absence of the
141
- ## appropriate HTTP header in the
142
- ## request. See
143
- ## {RFC3875 section 4.1.18}[https://tools.ietf.org/html/rfc3875#section-4.1.18]
144
- ## for specific behavior.
145
-
146
- ## In addition to this, the Rack environment must include these
147
- ## Rack-specific variables:
148
-
149
- ## <tt>rack.version</tt>:: The Array representing this version of Rack
150
- ## See Rack::VERSION, that corresponds to
151
- ## the version of this SPEC.
152
-
153
- ## <tt>rack.url_scheme</tt>:: +http+ or +https+, depending on the
154
- ## request URL.
155
-
156
- ## <tt>rack.input</tt>:: See below, the input stream.
157
-
158
- ## <tt>rack.errors</tt>:: See below, the error stream.
159
-
160
- ## <tt>rack.multithread</tt>:: true if the application object may be
161
- ## simultaneously invoked by another thread
162
- ## in the same process, false otherwise.
163
-
164
- ## <tt>rack.multiprocess</tt>:: true if an equivalent application object
165
- ## may be simultaneously invoked by another
166
- ## process, false otherwise.
167
-
168
- ## <tt>rack.run_once</tt>:: true if the server expects
169
- ## (but does not guarantee!) that the
170
- ## application will only be invoked this one
171
- ## time during the life of its containing
172
- ## process. Normally, this will only be true
173
- ## for a server based on CGI
174
- ## (or something similar).
175
-
176
- ## <tt>rack.hijack?</tt>:: present and true if the server supports
177
- ## connection hijacking. See below, hijacking.
178
-
179
- ## <tt>rack.hijack</tt>:: an object responding to #call that must be
180
- ## called at least once before using
181
- ## rack.hijack_io.
182
- ## It is recommended #call return rack.hijack_io
183
- ## as well as setting it in env if necessary.
184
-
185
- ## <tt>rack.hijack_io</tt>:: if rack.hijack? is true, and rack.hijack
186
- ## has received #call, this will contain
187
- ## an object resembling an IO. See hijacking.
188
-
189
- ## Additional environment specifications have approved to
190
- ## standardized middleware APIs. None of these are required to
191
- ## be implemented by the server.
192
-
193
- ## <tt>rack.session</tt>:: A hash like interface for storing
194
- ## request session data.
195
- ## The store must implement:
196
- if session = env[RACK_SESSION]
197
- ## store(key, value) (aliased as []=);
198
- assert("session #{session.inspect} must respond to store and []=") {
199
- session.respond_to?(:store) && session.respond_to?(:[]=)
200
- }
59
+ @env[RACK_INPUT] = InputWrapper.new(@env[RACK_INPUT])
60
+ @env[RACK_ERRORS] = ErrorWrapper.new(@env[RACK_ERRORS])
201
61
 
202
- ## fetch(key, default = nil) (aliased as []);
203
- assert("session #{session.inspect} must respond to fetch and []") {
204
- session.respond_to?(:fetch) && session.respond_to?(:[])
205
- }
62
+ ## and returns a non-frozen Array of exactly three values:
63
+ @response = @app.call(@env)
64
+ raise LintError, "response is not an Array, but #{@response.class}" unless @response.kind_of? Array
65
+ raise LintError, "response is frozen" if @response.frozen?
66
+ raise LintError, "response array has #{@response.size} elements instead of 3" unless @response.size == 3
206
67
 
207
- ## delete(key);
208
- assert("session #{session.inspect} must respond to delete") {
209
- session.respond_to?(:delete)
210
- }
68
+ @status, @headers, @body = @response
69
+ ## The *status*,
70
+ check_status(@status)
211
71
 
212
- ## clear;
213
- assert("session #{session.inspect} must respond to clear") {
214
- session.respond_to?(:clear)
215
- }
72
+ ## the *headers*,
73
+ check_headers(@headers)
216
74
 
217
- ## to_hash (returning unfrozen Hash instance);
218
- assert("session #{session.inspect} must respond to to_hash and return unfrozen Hash instance") {
219
- session.respond_to?(:to_hash) && session.to_hash.kind_of?(Hash) && !session.to_hash.frozen?
220
- }
75
+ hijack_proc = check_hijack_response(@headers, @env)
76
+ if hijack_proc
77
+ @headers[RACK_HIJACK] = hijack_proc
78
+ end
79
+
80
+ ## and the *body*.
81
+ check_content_type(@status, @headers)
82
+ check_content_length(@status, @headers)
83
+ @head_request = @env[REQUEST_METHOD] == HEAD
84
+
85
+ @lint = (@env['rack.lint'] ||= []) << self
86
+
87
+ if (@env['rack.lint.body_iteration'] ||= 0) > 0
88
+ raise LintError, "Middleware must not call #each directly"
89
+ end
90
+
91
+ return [@status, @headers, self]
221
92
  end
222
93
 
223
- ## <tt>rack.logger</tt>:: A common object interface for logging messages.
224
- ## The object must implement:
225
- if logger = env[RACK_LOGGER]
226
- ## info(message, &block)
227
- assert("logger #{logger.inspect} must respond to info") {
228
- logger.respond_to?(:info)
229
- }
94
+ ##
95
+ ## == The Environment
96
+ ##
97
+ def check_environment(env)
98
+ ## The environment must be an unfrozen instance of Hash that includes
99
+ ## CGI-like headers. The Rack application is free to modify the
100
+ ## environment.
101
+ raise LintError, "env #{env.inspect} is not a Hash, but #{env.class}" unless env.kind_of? Hash
102
+ raise LintError, "env should not be frozen, but is" if env.frozen?
230
103
 
231
- ## debug(message, &block)
232
- assert("logger #{logger.inspect} must respond to debug") {
233
- logger.respond_to?(:debug)
234
- }
104
+ ##
105
+ ## The environment is required to include these variables
106
+ ## (adopted from {PEP 333}[https://peps.python.org/pep-0333/]), except when they'd be empty, but see
107
+ ## below.
108
+
109
+ ## <tt>REQUEST_METHOD</tt>:: The HTTP request method, such as
110
+ ## "GET" or "POST". This cannot ever
111
+ ## be an empty string, and so is
112
+ ## always required.
113
+
114
+ ## <tt>SCRIPT_NAME</tt>:: The initial portion of the request
115
+ ## URL's "path" that corresponds to the
116
+ ## application object, so that the
117
+ ## application knows its virtual
118
+ ## "location". This may be an empty
119
+ ## string, if the application corresponds
120
+ ## to the "root" of the server.
121
+
122
+ ## <tt>PATH_INFO</tt>:: The remainder of the request URL's
123
+ ## "path", designating the virtual
124
+ ## "location" of the request's target
125
+ ## within the application. This may be an
126
+ ## empty string, if the request URL targets
127
+ ## the application root and does not have a
128
+ ## trailing slash. This value may be
129
+ ## percent-encoded when originating from
130
+ ## a URL.
131
+
132
+ ## <tt>QUERY_STRING</tt>:: The portion of the request URL that
133
+ ## follows the <tt>?</tt>, if any. May be
134
+ ## empty, but is always required!
135
+
136
+ ## <tt>SERVER_NAME</tt>:: When combined with <tt>SCRIPT_NAME</tt> and
137
+ ## <tt>PATH_INFO</tt>, these variables can be
138
+ ## used to complete the URL. Note, however,
139
+ ## that <tt>HTTP_HOST</tt>, if present,
140
+ ## should be used in preference to
141
+ ## <tt>SERVER_NAME</tt> for reconstructing
142
+ ## the request URL.
143
+ ## <tt>SERVER_NAME</tt> can never be an empty
144
+ ## string, and so is always required.
145
+
146
+ ## <tt>SERVER_PORT</tt>:: An optional +Integer+ which is the port the
147
+ ## server is running on. Should be specified if
148
+ ## the server is running on a non-standard port.
149
+
150
+ ## <tt>SERVER_PROTOCOL</tt>:: A string representing the HTTP version used
151
+ ## for the request.
152
+
153
+ ## <tt>HTTP_</tt> Variables:: Variables corresponding to the
154
+ ## client-supplied HTTP request
155
+ ## headers (i.e., variables whose
156
+ ## names begin with <tt>HTTP_</tt>). The
157
+ ## presence or absence of these
158
+ ## variables should correspond with
159
+ ## the presence or absence of the
160
+ ## appropriate HTTP header in the
161
+ ## request. See
162
+ ## {RFC3875 section 4.1.18}[https://tools.ietf.org/html/rfc3875#section-4.1.18]
163
+ ## for specific behavior.
164
+
165
+ ## In addition to this, the Rack environment must include these
166
+ ## Rack-specific variables:
167
+
168
+ ## <tt>rack.url_scheme</tt>:: +http+ or +https+, depending on the
169
+ ## request URL.
170
+
171
+ ## <tt>rack.input</tt>:: See below, the input stream.
172
+
173
+ ## <tt>rack.errors</tt>:: See below, the error stream.
174
+
175
+ ## <tt>rack.hijack?</tt>:: See below, if present and true, indicates
176
+ ## that the server supports partial hijacking.
177
+
178
+ ## <tt>rack.hijack</tt>:: See below, if present, an object responding
179
+ ## to +call+ that is used to perform a full
180
+ ## hijack.
181
+
182
+ ## Additional environment specifications have approved to
183
+ ## standardized middleware APIs. None of these are required to
184
+ ## be implemented by the server.
185
+
186
+ ## <tt>rack.session</tt>:: A hash-like interface for storing
187
+ ## request session data.
188
+ ## The store must implement:
189
+ if session = env[RACK_SESSION]
190
+ ## store(key, value) (aliased as []=);
191
+ unless session.respond_to?(:store) && session.respond_to?(:[]=)
192
+ raise LintError, "session #{session.inspect} must respond to store and []="
193
+ end
235
194
 
236
- ## warn(message, &block)
237
- assert("logger #{logger.inspect} must respond to warn") {
238
- logger.respond_to?(:warn)
239
- }
195
+ ## fetch(key, default = nil) (aliased as []);
196
+ unless session.respond_to?(:fetch) && session.respond_to?(:[])
197
+ raise LintError, "session #{session.inspect} must respond to fetch and []"
198
+ end
240
199
 
241
- ## error(message, &block)
242
- assert("logger #{logger.inspect} must respond to error") {
243
- logger.respond_to?(:error)
244
- }
200
+ ## delete(key);
201
+ unless session.respond_to?(:delete)
202
+ raise LintError, "session #{session.inspect} must respond to delete"
203
+ end
245
204
 
246
- ## fatal(message, &block)
247
- assert("logger #{logger.inspect} must respond to fatal") {
248
- logger.respond_to?(:fatal)
249
- }
250
- end
205
+ ## clear;
206
+ unless session.respond_to?(:clear)
207
+ raise LintError, "session #{session.inspect} must respond to clear"
208
+ end
251
209
 
252
- ## <tt>rack.multipart.buffer_size</tt>:: An Integer hint to the multipart parser as to what chunk size to use for reads and writes.
253
- if bufsize = env[RACK_MULTIPART_BUFFER_SIZE]
254
- assert("rack.multipart.buffer_size must be an Integer > 0 if specified") {
255
- bufsize.is_a?(Integer) && bufsize > 0
256
- }
257
- end
210
+ ## to_hash (returning unfrozen Hash instance);
211
+ unless session.respond_to?(:to_hash) && session.to_hash.kind_of?(Hash) && !session.to_hash.frozen?
212
+ raise LintError, "session #{session.inspect} must respond to to_hash and return unfrozen Hash instance"
213
+ end
214
+ end
215
+
216
+ ## <tt>rack.logger</tt>:: A common object interface for logging messages.
217
+ ## The object must implement:
218
+ if logger = env[RACK_LOGGER]
219
+ ## info(message, &block)
220
+ unless logger.respond_to?(:info)
221
+ raise LintError, "logger #{logger.inspect} must respond to info"
222
+ end
223
+
224
+ ## debug(message, &block)
225
+ unless logger.respond_to?(:debug)
226
+ raise LintError, "logger #{logger.inspect} must respond to debug"
227
+ end
228
+
229
+ ## warn(message, &block)
230
+ unless logger.respond_to?(:warn)
231
+ raise LintError, "logger #{logger.inspect} must respond to warn"
232
+ end
258
233
 
259
- ## <tt>rack.multipart.tempfile_factory</tt>:: An object responding to #call with two arguments, the filename and content_type given for the multipart form field, and returning an IO-like object that responds to #<< and optionally #rewind. This factory will be used to instantiate the tempfile for each multipart form file upload field, rather than the default class of Tempfile.
260
- if tempfile_factory = env[RACK_MULTIPART_TEMPFILE_FACTORY]
261
- assert("rack.multipart.tempfile_factory must respond to #call") { tempfile_factory.respond_to?(:call) }
262
- env[RACK_MULTIPART_TEMPFILE_FACTORY] = lambda do |filename, content_type|
263
- io = tempfile_factory.call(filename, content_type)
264
- assert("rack.multipart.tempfile_factory return value must respond to #<<") { io.respond_to?(:<<) }
265
- io
234
+ ## error(message, &block)
235
+ unless logger.respond_to?(:error)
236
+ raise LintError, "logger #{logger.inspect} must respond to error"
237
+ end
238
+
239
+ ## fatal(message, &block)
240
+ unless logger.respond_to?(:fatal)
241
+ raise LintError, "logger #{logger.inspect} must respond to fatal"
242
+ end
266
243
  end
267
- end
268
244
 
269
- ## The server or the application can store their own data in the
270
- ## environment, too. The keys must contain at least one dot,
271
- ## and should be prefixed uniquely. The prefix <tt>rack.</tt>
272
- ## is reserved for use with the Rack core distribution and other
273
- ## accepted specifications and must not be used otherwise.
274
- ##
245
+ ## <tt>rack.multipart.buffer_size</tt>:: An Integer hint to the multipart parser as to what chunk size to use for reads and writes.
246
+ if bufsize = env[RACK_MULTIPART_BUFFER_SIZE]
247
+ unless bufsize.is_a?(Integer) && bufsize > 0
248
+ raise LintError, "rack.multipart.buffer_size must be an Integer > 0 if specified"
249
+ end
250
+ end
251
+
252
+ ## <tt>rack.multipart.tempfile_factory</tt>:: An object responding to #call with two arguments, the filename and content_type given for the multipart form field, and returning an IO-like object that responds to #<< and optionally #rewind. This factory will be used to instantiate the tempfile for each multipart form file upload field, rather than the default class of Tempfile.
253
+ if tempfile_factory = env[RACK_MULTIPART_TEMPFILE_FACTORY]
254
+ raise LintError, "rack.multipart.tempfile_factory must respond to #call" unless tempfile_factory.respond_to?(:call)
255
+ env[RACK_MULTIPART_TEMPFILE_FACTORY] = lambda do |filename, content_type|
256
+ io = tempfile_factory.call(filename, content_type)
257
+ raise LintError, "rack.multipart.tempfile_factory return value must respond to #<<" unless io.respond_to?(:<<)
258
+ io
259
+ end
260
+ end
261
+
262
+ ## The server or the application can store their own data in the
263
+ ## environment, too. The keys must contain at least one dot,
264
+ ## and should be prefixed uniquely. The prefix <tt>rack.</tt>
265
+ ## is reserved for use with the Rack core distribution and other
266
+ ## accepted specifications and must not be used otherwise.
267
+ ##
275
268
 
276
- %w[REQUEST_METHOD SERVER_NAME QUERY_STRING
277
- rack.version rack.input rack.errors
278
- rack.multithread rack.multiprocess rack.run_once].each { |header|
279
- assert("env missing required key #{header}") { env.include? header }
280
- }
269
+ %w[REQUEST_METHOD SERVER_NAME QUERY_STRING SERVER_PROTOCOL
270
+ rack.input rack.errors].each { |header|
271
+ raise LintError, "env missing required key #{header}" unless env.include? header
272
+ }
281
273
 
282
- ## The <tt>SERVER_PORT</tt> must be an Integer if set.
283
- assert("env[SERVER_PORT] is not an Integer") do
274
+ ## The <tt>SERVER_PORT</tt> must be an Integer if set.
284
275
  server_port = env["SERVER_PORT"]
285
- server_port.nil? || (Integer(server_port) rescue false)
286
- end
276
+ unless server_port.nil? || (Integer(server_port) rescue false)
277
+ raise LintError, "env[SERVER_PORT] is not an Integer"
278
+ end
287
279
 
288
- ## The <tt>SERVER_NAME</tt> must be a valid authority as defined by RFC7540.
289
- assert("#{env[SERVER_NAME]} must be a valid authority") do
290
- URI.parse("http://#{env[SERVER_NAME]}/") rescue false
291
- end
280
+ ## The <tt>SERVER_NAME</tt> must be a valid authority as defined by RFC7540.
281
+ unless (URI.parse("http://#{env[SERVER_NAME]}/") rescue false)
282
+ raise LintError, "#{env[SERVER_NAME]} must be a valid authority"
283
+ end
292
284
 
293
- ## The <tt>HTTP_HOST</tt> must be a valid authority as defined by RFC7540.
294
- assert("#{env[HTTP_HOST]} must be a valid authority") do
295
- URI.parse("http://#{env[HTTP_HOST]}/") rescue false
296
- end
285
+ ## The <tt>HTTP_HOST</tt> must be a valid authority as defined by RFC7540.
286
+ unless (URI.parse("http://#{env[HTTP_HOST]}/") rescue false)
287
+ raise LintError, "#{env[HTTP_HOST]} must be a valid authority"
288
+ end
297
289
 
298
- ## The environment must not contain the keys
299
- ## <tt>HTTP_CONTENT_TYPE</tt> or <tt>HTTP_CONTENT_LENGTH</tt>
300
- ## (use the versions without <tt>HTTP_</tt>).
301
- %w[HTTP_CONTENT_TYPE HTTP_CONTENT_LENGTH].each { |header|
302
- assert("env contains #{header}, must use #{header[5, -1]}") {
303
- not env.include? header
304
- }
305
- }
306
-
307
- ## The CGI keys (named without a period) must have String values.
308
- ## If the string values for CGI keys contain non-ASCII characters,
309
- ## they should use ASCII-8BIT encoding.
310
- env.each { |key, value|
311
- next if key.include? "." # Skip extensions
312
- assert("env variable #{key} has non-string value #{value.inspect}") {
313
- value.kind_of? String
314
- }
315
- next if value.encoding == Encoding::ASCII_8BIT
316
- assert("env variable #{key} has value containing non-ASCII characters and has non-ASCII-8BIT encoding #{value.inspect} encoding: #{value.encoding}") {
317
- value.b !~ /[\x80-\xff]/n
290
+ ## The <tt>SERVER_PROTOCOL</tt> must match the regexp <tt>HTTP/\d(\.\d)?</tt>.
291
+ server_protocol = env['SERVER_PROTOCOL']
292
+ unless %r{HTTP/\d(\.\d)?}.match?(server_protocol)
293
+ raise LintError, "env[SERVER_PROTOCOL] does not match HTTP/\\d(\\.\\d)?"
294
+ end
295
+
296
+ ## If the <tt>HTTP_VERSION</tt> is present, it must equal the <tt>SERVER_PROTOCOL</tt>.
297
+ if env['HTTP_VERSION'] && env['HTTP_VERSION'] != server_protocol
298
+ raise LintError, "env[HTTP_VERSION] does not equal env[SERVER_PROTOCOL]"
299
+ end
300
+
301
+ ## The environment must not contain the keys
302
+ ## <tt>HTTP_CONTENT_TYPE</tt> or <tt>HTTP_CONTENT_LENGTH</tt>
303
+ ## (use the versions without <tt>HTTP_</tt>).
304
+ %w[HTTP_CONTENT_TYPE HTTP_CONTENT_LENGTH].each { |header|
305
+ if env.include? header
306
+ raise LintError, "env contains #{header}, must use #{header[5, -1]}"
307
+ end
318
308
  }
319
- }
320
-
321
- ## There are the following restrictions:
322
-
323
- ## * <tt>rack.version</tt> must be an array of Integers.
324
- assert("rack.version must be an Array, was #{env[RACK_VERSION].class}") {
325
- env[RACK_VERSION].kind_of? Array
326
- }
327
- ## * <tt>rack.url_scheme</tt> must either be +http+ or +https+.
328
- assert("rack.url_scheme unknown: #{env[RACK_URL_SCHEME].inspect}") {
329
- %w[http https].include?(env[RACK_URL_SCHEME])
330
- }
331
-
332
- ## * There must be a valid input stream in <tt>rack.input</tt>.
333
- check_input env[RACK_INPUT]
334
- ## * There must be a valid error stream in <tt>rack.errors</tt>.
335
- check_error env[RACK_ERRORS]
336
- ## * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
337
- check_hijack env
338
-
339
- ## * The <tt>REQUEST_METHOD</tt> must be a valid token.
340
- assert("REQUEST_METHOD unknown: #{env[REQUEST_METHOD].dump}") {
341
- env[REQUEST_METHOD] =~ /\A[0-9A-Za-z!\#$%&'*+.^_`|~-]+\z/
342
- }
343
-
344
- ## * The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
345
- assert("SCRIPT_NAME must start with /") {
346
- !env.include?(SCRIPT_NAME) ||
347
- env[SCRIPT_NAME] == "" ||
348
- env[SCRIPT_NAME] =~ /\A\//
349
- }
350
- ## * The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
351
- assert("PATH_INFO must start with /") {
352
- !env.include?(PATH_INFO) ||
353
- env[PATH_INFO] == "" ||
354
- env[PATH_INFO] =~ /\A\//
355
- }
356
- ## * The <tt>CONTENT_LENGTH</tt>, if given, must consist of digits only.
357
- assert("Invalid CONTENT_LENGTH: #{env["CONTENT_LENGTH"]}") {
358
- !env.include?("CONTENT_LENGTH") || env["CONTENT_LENGTH"] =~ /\A\d+\z/
359
- }
360
-
361
- ## * One of <tt>SCRIPT_NAME</tt> or <tt>PATH_INFO</tt> must be
362
- ## set. <tt>PATH_INFO</tt> should be <tt>/</tt> if
363
- ## <tt>SCRIPT_NAME</tt> is empty.
364
- assert("One of SCRIPT_NAME or PATH_INFO must be set (make PATH_INFO '/' if SCRIPT_NAME is empty)") {
365
- env[SCRIPT_NAME] || env[PATH_INFO]
366
- }
367
- ## <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
368
- assert("SCRIPT_NAME cannot be '/', make it '' and PATH_INFO '/'") {
369
- env[SCRIPT_NAME] != "/"
370
- }
371
- end
372
309
 
373
- ## === The Input Stream
374
- ##
375
- ## The input stream is an IO-like object which contains the raw HTTP
376
- ## POST data.
377
- def check_input(input)
378
- ## When applicable, its external encoding must be "ASCII-8BIT" and it
379
- ## must be opened in binary mode, for Ruby 1.9 compatibility.
380
- assert("rack.input #{input} does not have ASCII-8BIT as its external encoding") {
381
- input.external_encoding == Encoding::ASCII_8BIT
382
- } if input.respond_to?(:external_encoding)
383
- assert("rack.input #{input} is not opened in binary mode") {
384
- input.binmode?
385
- } if input.respond_to?(:binmode?)
386
-
387
- ## The input stream must respond to +gets+, +each+, +read+ and +rewind+.
388
- [:gets, :each, :read, :rewind].each { |method|
389
- assert("rack.input #{input} does not respond to ##{method}") {
390
- input.respond_to? method
310
+ ## The CGI keys (named without a period) must have String values.
311
+ ## If the string values for CGI keys contain non-ASCII characters,
312
+ ## they should use ASCII-8BIT encoding.
313
+ env.each { |key, value|
314
+ next if key.include? "." # Skip extensions
315
+ unless value.kind_of? String
316
+ raise LintError, "env variable #{key} has non-string value #{value.inspect}"
317
+ end
318
+ next if value.encoding == Encoding::ASCII_8BIT
319
+ unless value.b !~ /[\x80-\xff]/n
320
+ raise LintError, "env variable #{key} has value containing non-ASCII characters and has non-ASCII-8BIT encoding #{value.inspect} encoding: #{value.encoding}"
321
+ end
391
322
  }
392
- }
393
- end
394
323
 
395
- class InputWrapper
396
- include Assertion
324
+ ## There are the following restrictions:
397
325
 
398
- def initialize(input)
399
- @input = input
400
- end
326
+ ## * <tt>rack.url_scheme</tt> must either be +http+ or +https+.
327
+ unless %w[http https].include?(env[RACK_URL_SCHEME])
328
+ raise LintError, "rack.url_scheme unknown: #{env[RACK_URL_SCHEME].inspect}"
329
+ end
401
330
 
402
- ## * +gets+ must be called without arguments and return a string,
403
- ## or +nil+ on EOF.
404
- def gets(*args)
405
- assert("rack.input#gets called with arguments") { args.size == 0 }
406
- v = @input.gets
407
- assert("rack.input#gets didn't return a String") {
408
- v.nil? or v.kind_of? String
409
- }
410
- v
331
+ ## * There must be a valid input stream in <tt>rack.input</tt>.
332
+ check_input env[RACK_INPUT]
333
+ ## * There must be a valid error stream in <tt>rack.errors</tt>.
334
+ check_error env[RACK_ERRORS]
335
+ ## * There may be a valid hijack callback in <tt>rack.hijack</tt>
336
+ check_hijack env
337
+
338
+ ## * The <tt>REQUEST_METHOD</tt> must be a valid token.
339
+ unless env[REQUEST_METHOD] =~ /\A[0-9A-Za-z!\#$%&'*+.^_`|~-]+\z/
340
+ raise LintError, "REQUEST_METHOD unknown: #{env[REQUEST_METHOD].dump}"
341
+ end
342
+
343
+ ## * The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
344
+ if env.include?(SCRIPT_NAME) && env[SCRIPT_NAME] != "" && env[SCRIPT_NAME] !~ /\A\//
345
+ raise LintError, "SCRIPT_NAME must start with /"
346
+ end
347
+ ## * The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
348
+ if env.include?(PATH_INFO) && env[PATH_INFO] != "" && env[PATH_INFO] !~ /\A\//
349
+ raise LintError, "PATH_INFO must start with /"
350
+ end
351
+ ## * The <tt>CONTENT_LENGTH</tt>, if given, must consist of digits only.
352
+ if env.include?("CONTENT_LENGTH") && env["CONTENT_LENGTH"] !~ /\A\d+\z/
353
+ raise LintError, "Invalid CONTENT_LENGTH: #{env["CONTENT_LENGTH"]}"
354
+ end
355
+
356
+ ## * One of <tt>SCRIPT_NAME</tt> or <tt>PATH_INFO</tt> must be
357
+ ## set. <tt>PATH_INFO</tt> should be <tt>/</tt> if
358
+ ## <tt>SCRIPT_NAME</tt> is empty.
359
+ unless env[SCRIPT_NAME] || env[PATH_INFO]
360
+ raise LintError, "One of SCRIPT_NAME or PATH_INFO must be set (make PATH_INFO '/' if SCRIPT_NAME is empty)"
361
+ end
362
+ ## <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
363
+ unless env[SCRIPT_NAME] != "/"
364
+ raise LintError, "SCRIPT_NAME cannot be '/', make it '' and PATH_INFO '/'"
365
+ end
411
366
  end
412
367
 
413
- ## * +read+ behaves like IO#read.
414
- ## Its signature is <tt>read([length, [buffer]])</tt>.
415
- ##
416
- ## If given, +length+ must be a non-negative Integer (>= 0) or +nil+,
417
- ## and +buffer+ must be a String and may not be nil.
418
368
  ##
419
- ## If +length+ is given and not nil, then this method reads at most
420
- ## +length+ bytes from the input stream.
369
+ ## === The Input Stream
421
370
  ##
422
- ## If +length+ is not given or nil, then this method reads
423
- ## all data until EOF.
424
- ##
425
- ## When EOF is reached, this method returns nil if +length+ is given
426
- ## and not nil, or "" if +length+ is not given or is nil.
427
- ##
428
- ## If +buffer+ is given, then the read data will be placed
429
- ## into +buffer+ instead of a newly created String object.
430
- def read(*args)
431
- assert("rack.input#read called with too many arguments") {
432
- args.size <= 2
433
- }
434
- if args.size >= 1
435
- assert("rack.input#read called with non-integer and non-nil length") {
436
- args.first.kind_of?(Integer) || args.first.nil?
437
- }
438
- assert("rack.input#read called with a negative length") {
439
- args.first.nil? || args.first >= 0
440
- }
371
+ ## The input stream is an IO-like object which contains the raw HTTP
372
+ ## POST data.
373
+ def check_input(input)
374
+ ## When applicable, its external encoding must be "ASCII-8BIT" and it
375
+ ## must be opened in binary mode, for Ruby 1.9 compatibility.
376
+ if input.respond_to?(:external_encoding) && input.external_encoding != Encoding::ASCII_8BIT
377
+ raise LintError, "rack.input #{input} does not have ASCII-8BIT as its external encoding"
441
378
  end
442
- if args.size >= 2
443
- assert("rack.input#read called with non-String buffer") {
444
- args[1].kind_of?(String)
445
- }
379
+ if input.respond_to?(:binmode?) && !input.binmode?
380
+ raise LintError, "rack.input #{input} is not opened in binary mode"
446
381
  end
447
382
 
448
- v = @input.read(*args)
449
-
450
- assert("rack.input#read didn't return nil or a String") {
451
- v.nil? or v.kind_of? String
383
+ ## The input stream must respond to +gets+, +each+, and +read+.
384
+ [:gets, :each, :read].each { |method|
385
+ unless input.respond_to? method
386
+ raise LintError, "rack.input #{input} does not respond to ##{method}"
387
+ end
452
388
  }
453
- if args[0].nil?
454
- assert("rack.input#read(nil) returned nil on EOF") {
455
- !v.nil?
456
- }
389
+ end
390
+
391
+ class InputWrapper
392
+ def initialize(input)
393
+ @input = input
457
394
  end
458
395
 
459
- v
460
- end
396
+ ## * +gets+ must be called without arguments and return a string,
397
+ ## or +nil+ on EOF.
398
+ def gets(*args)
399
+ raise LintError, "rack.input#gets called with arguments" unless args.size == 0
400
+ v = @input.gets
401
+ unless v.nil? or v.kind_of? String
402
+ raise LintError, "rack.input#gets didn't return a String"
403
+ end
404
+ v
405
+ end
406
+
407
+ ## * +read+ behaves like IO#read.
408
+ ## Its signature is <tt>read([length, [buffer]])</tt>.
409
+ ##
410
+ ## If given, +length+ must be a non-negative Integer (>= 0) or +nil+,
411
+ ## and +buffer+ must be a String and may not be nil.
412
+ ##
413
+ ## If +length+ is given and not nil, then this method reads at most
414
+ ## +length+ bytes from the input stream.
415
+ ##
416
+ ## If +length+ is not given or nil, then this method reads
417
+ ## all data until EOF.
418
+ ##
419
+ ## When EOF is reached, this method returns nil if +length+ is given
420
+ ## and not nil, or "" if +length+ is not given or is nil.
421
+ ##
422
+ ## If +buffer+ is given, then the read data will be placed
423
+ ## into +buffer+ instead of a newly created String object.
424
+ def read(*args)
425
+ unless args.size <= 2
426
+ raise LintError, "rack.input#read called with too many arguments"
427
+ end
428
+ if args.size >= 1
429
+ unless args.first.kind_of?(Integer) || args.first.nil?
430
+ raise LintError, "rack.input#read called with non-integer and non-nil length"
431
+ end
432
+ unless args.first.nil? || args.first >= 0
433
+ raise LintError, "rack.input#read called with a negative length"
434
+ end
435
+ end
436
+ if args.size >= 2
437
+ unless args[1].kind_of?(String)
438
+ raise LintError, "rack.input#read called with non-String buffer"
439
+ end
440
+ end
441
+
442
+ v = @input.read(*args)
443
+
444
+ unless v.nil? or v.kind_of? String
445
+ raise LintError, "rack.input#read didn't return nil or a String"
446
+ end
447
+ if args[0].nil?
448
+ unless !v.nil?
449
+ raise LintError, "rack.input#read(nil) returned nil on EOF"
450
+ end
451
+ end
452
+
453
+ v
454
+ end
461
455
 
462
- ## * +each+ must be called without arguments and only yield Strings.
463
- def each(*args)
464
- assert("rack.input#each called with arguments") { args.size == 0 }
465
- @input.each { |line|
466
- assert("rack.input#each didn't yield a String") {
467
- line.kind_of? String
456
+ ## * +each+ must be called without arguments and only yield Strings.
457
+ def each(*args)
458
+ raise LintError, "rack.input#each called with arguments" unless args.size == 0
459
+ @input.each { |line|
460
+ unless line.kind_of? String
461
+ raise LintError, "rack.input#each didn't yield a String"
462
+ end
463
+ yield line
468
464
  }
469
- yield line
470
- }
465
+ end
466
+
467
+ ## * +close+ must never be called on the input stream.
468
+ def close(*args)
469
+ raise LintError, "rack.input#close must not be called"
470
+ end
471
471
  end
472
472
 
473
- ## * +rewind+ must be called without arguments. It rewinds the input
474
- ## stream back to the beginning. It must not raise Errno::ESPIPE:
475
- ## that is, it may not be a pipe or a socket. Therefore, handler
476
- ## developers must buffer the input data into some rewindable object
477
- ## if the underlying input stream is not rewindable.
478
- def rewind(*args)
479
- assert("rack.input#rewind called with arguments") { args.size == 0 }
480
- assert("rack.input#rewind raised Errno::ESPIPE") {
481
- begin
482
- @input.rewind
483
- true
484
- rescue Errno::ESPIPE
485
- false
473
+ ##
474
+ ## === The Error Stream
475
+ ##
476
+ def check_error(error)
477
+ ## The error stream must respond to +puts+, +write+ and +flush+.
478
+ [:puts, :write, :flush].each { |method|
479
+ unless error.respond_to? method
480
+ raise LintError, "rack.error #{error} does not respond to ##{method}"
486
481
  end
487
482
  }
488
483
  end
489
484
 
490
- ## * +close+ must never be called on the input stream.
491
- def close(*args)
492
- assert("rack.input#close must not be called") { false }
493
- end
494
- end
485
+ class ErrorWrapper
486
+ def initialize(error)
487
+ @error = error
488
+ end
495
489
 
496
- ## === The Error Stream
497
- def check_error(error)
498
- ## The error stream must respond to +puts+, +write+ and +flush+.
499
- [:puts, :write, :flush].each { |method|
500
- assert("rack.error #{error} does not respond to ##{method}") {
501
- error.respond_to? method
502
- }
503
- }
504
- end
490
+ ## * +puts+ must be called with a single argument that responds to +to_s+.
491
+ def puts(str)
492
+ @error.puts str
493
+ end
505
494
 
506
- class ErrorWrapper
507
- include Assertion
495
+ ## * +write+ must be called with a single argument that is a String.
496
+ def write(str)
497
+ raise LintError, "rack.errors#write not called with a String" unless str.kind_of? String
498
+ @error.write str
499
+ end
508
500
 
509
- def initialize(error)
510
- @error = error
511
- end
501
+ ## * +flush+ must be called without arguments and must be called
502
+ ## in order to make the error appear for sure.
503
+ def flush
504
+ @error.flush
505
+ end
512
506
 
513
- ## * +puts+ must be called with a single argument that responds to +to_s+.
514
- def puts(str)
515
- @error.puts str
507
+ ## * +close+ must never be called on the error stream.
508
+ def close(*args)
509
+ raise LintError, "rack.errors#close must not be called"
510
+ end
516
511
  end
517
512
 
518
- ## * +write+ must be called with a single argument that is a String.
519
- def write(str)
520
- assert("rack.errors#write not called with a String") { str.kind_of? String }
521
- @error.write str
513
+ ##
514
+ ## === Hijacking
515
+ ##
516
+ ## The hijacking interfaces provides a means for an application to take
517
+ ## control of the HTTP connection. There are two distinct hijack
518
+ ## interfaces: full hijacking where the application takes over the raw
519
+ ## connection, and partial hijacking where the application takes over
520
+ ## just the response body stream. In both cases, the application is
521
+ ## responsible for closing the hijacked stream.
522
+ ##
523
+ ## Full hijacking only works with HTTP/1. Partial hijacking is functionally
524
+ ## equivalent to streaming bodies, and is still optionally supported for
525
+ ## backwards compatibility with older Rack versions.
526
+ ##
527
+ ## ==== Full Hijack
528
+ ##
529
+ ## Full hijack is used to completely take over an HTTP/1 connection. It
530
+ ## occurs before any headers are written and causes the request to
531
+ ## ignores any response generated by the application.
532
+ ##
533
+ ## It is intended to be used when applications need access to raw HTTP/1
534
+ ## connection.
535
+ ##
536
+ def check_hijack(env)
537
+ ## If +rack.hijack+ is present in +env+, it must respond to +call+
538
+ if original_hijack = env[RACK_HIJACK]
539
+ raise LintError, "rack.hijack must respond to call" unless original_hijack.respond_to?(:call)
540
+
541
+ env[RACK_HIJACK] = proc do
542
+ io = original_hijack.call
543
+
544
+ ## and return an +IO+ instance which can be used to read and write
545
+ ## to the underlying connection using HTTP/1 semantics and
546
+ ## formatting.
547
+ raise LintError, "rack.hijack must return an IO instance" unless io.is_a?(IO)
548
+
549
+ io
550
+ end
551
+ end
522
552
  end
523
553
 
524
- ## * +flush+ must be called without arguments and must be called
525
- ## in order to make the error appear for sure.
526
- def flush
527
- @error.flush
554
+ ##
555
+ ## ==== Partial Hijack
556
+ ##
557
+ ## Partial hijack is used for bi-directional streaming of the request and
558
+ ## response body. It occurs after the status and headers are written by
559
+ ## the server and causes the server to ignore the Body of the response.
560
+ ##
561
+ ## It is intended to be used when applications need bi-directional
562
+ ## streaming.
563
+ ##
564
+ def check_hijack_response(headers, env)
565
+ ## If +rack.hijack?+ is present in +env+ and truthy,
566
+ if env[RACK_IS_HIJACK]
567
+ ## an application may set the special response header +rack.hijack+
568
+ if original_hijack = headers[RACK_HIJACK]
569
+ ## to an object that responds to +call+,
570
+ unless original_hijack.respond_to?(:call)
571
+ raise LintError, 'rack.hijack header must respond to #call'
572
+ end
573
+ ## accepting a +stream+ argument.
574
+ return proc do |io|
575
+ original_hijack.call StreamWrapper.new(io)
576
+ end
577
+ end
578
+ ##
579
+ ## After the response status and headers have been sent, this hijack
580
+ ## callback will be invoked with a +stream+ argument which follows the
581
+ ## same interface as outlined in "Streaming Body". Servers must
582
+ ## ignore the +body+ part of the response tuple when the
583
+ ## +rack.hijack+ response header is present. Using an empty +Array+
584
+ ## instance is recommended.
585
+ else
586
+ ##
587
+ ## The special response header +rack.hijack+ must only be set
588
+ ## if the request +env+ has a truthy +rack.hijack?+.
589
+ if headers.key?(RACK_HIJACK)
590
+ raise LintError, 'rack.hijack header must not be present if server does not support hijacking'
591
+ end
592
+ end
593
+
594
+ nil
528
595
  end
529
596
 
530
- ## * +close+ must never be called on the error stream.
531
- def close(*args)
532
- assert("rack.errors#close must not be called") { false }
597
+ ## == The Response
598
+ ##
599
+ ## === The Status
600
+ ##
601
+ def check_status(status)
602
+ ## This is an HTTP status. It must be an Integer greater than or equal to
603
+ ## 100.
604
+ unless status.is_a?(Integer) && status >= 100
605
+ raise LintError, "Status must be an Integer >=100"
606
+ end
533
607
  end
534
- end
535
608
 
536
- class HijackWrapper
537
- include Assertion
538
- extend Forwardable
609
+ ##
610
+ ## === The Headers
611
+ ##
612
+ def check_headers(headers)
613
+ ## The headers must be a unfrozen Hash.
614
+ unless headers.kind_of?(Hash)
615
+ raise LintError, "headers object should be a hash, but isn't (got #{headers.class} as headers)"
616
+ end
617
+
618
+ if headers.frozen?
619
+ raise LintError, "headers object should not be frozen, but is"
620
+ end
539
621
 
540
- REQUIRED_METHODS = [
541
- :read, :write, :read_nonblock, :write_nonblock, :flush, :close,
542
- :close_read, :close_write, :closed?
543
- ]
622
+ headers.each do |key, value|
623
+ ## The header keys must be Strings.
624
+ unless key.kind_of? String
625
+ raise LintError, "header key must be a string, was #{key.class}"
626
+ end
544
627
 
545
- def_delegators :@io, *REQUIRED_METHODS
628
+ ## Special headers starting "rack." are for communicating with the
629
+ ## server, and must not be sent back to the client.
630
+ next if key.start_with?("rack.")
631
+
632
+ ## The header must not contain a +Status+ key.
633
+ raise LintError, "header must not contain status" if key == "status"
634
+ ## Header keys must conform to RFC7230 token specification, i.e. cannot
635
+ ## contain non-printable ASCII, DQUOTE or "(),/:;<=>?@[\]{}".
636
+ raise LintError, "invalid header name: #{key}" if key =~ /[\(\),\/:;<=>\?@\[\\\]{}[:cntrl:]]/
637
+ ## Header keys must not contain uppercase ASCII characters (A-Z).
638
+ raise LintError, "uppercase character in header name: #{key}" if key =~ /[A-Z]/
639
+
640
+ ## Header values must be either a String instance,
641
+ if value.kind_of?(String)
642
+ check_header_value(key, value)
643
+ elsif value.kind_of?(Array)
644
+ ## or an Array of String instances,
645
+ value.each{|value| check_header_value(key, value)}
646
+ else
647
+ raise LintError, "a header value must be a String or Array of Strings, but the value of '#{key}' is a #{value.class}"
648
+ end
649
+ end
650
+ end
546
651
 
547
- def initialize(io)
548
- @io = io
549
- REQUIRED_METHODS.each do |meth|
550
- assert("rack.hijack_io must respond to #{meth}") { io.respond_to? meth }
652
+ def check_header_value(key, value)
653
+ ## such that each String instance must not contain characters below 037.
654
+ if value =~ /[\000-\037]/
655
+ raise LintError, "invalid header value #{key}: #{value.inspect}"
551
656
  end
552
657
  end
553
- end
554
658
 
555
- ## === Hijacking
556
- #
557
- # AUTHORS: n.b. The trailing whitespace between paragraphs is important and
558
- # should not be removed. The whitespace creates paragraphs in the RDoc
559
- # output.
560
- #
561
- ## ==== Request (before status)
562
- def check_hijack(env)
563
- if env[RACK_IS_HIJACK]
564
- ## If rack.hijack? is true then rack.hijack must respond to #call.
565
- original_hijack = env[RACK_HIJACK]
566
- assert("rack.hijack must respond to call") { original_hijack.respond_to?(:call) }
567
- env[RACK_HIJACK] = proc do
568
- ## rack.hijack must return the io that will also be assigned (or is
569
- ## already present, in rack.hijack_io.
570
- io = original_hijack.call
571
- HijackWrapper.new(io)
572
- ##
573
- ## rack.hijack_io must respond to:
574
- ## <tt>read, write, read_nonblock, write_nonblock, flush, close,
575
- ## close_read, close_write, closed?</tt>
576
- ##
577
- ## The semantics of these IO methods must be a best effort match to
578
- ## those of a normal ruby IO or Socket object, using standard
579
- ## arguments and raising standard exceptions. Servers are encouraged
580
- ## to simply pass on real IO objects, although it is recognized that
581
- ## this approach is not directly compatible with SPDY and HTTP 2.0.
582
- ##
583
- ## IO provided in rack.hijack_io should preference the
584
- ## IO::WaitReadable and IO::WaitWritable APIs wherever supported.
585
- ##
586
- ## There is a deliberate lack of full specification around
587
- ## rack.hijack_io, as semantics will change from server to server.
588
- ## Users are encouraged to utilize this API with a knowledge of their
589
- ## server choice, and servers may extend the functionality of
590
- ## hijack_io to provide additional features to users. The purpose of
591
- ## rack.hijack is for Rack to "get out of the way", as such, Rack only
592
- ## provides the minimum of specification and support.
593
- env[RACK_HIJACK_IO] = HijackWrapper.new(env[RACK_HIJACK_IO])
594
- io
595
- end
596
- else
597
- ##
598
- ## If rack.hijack? is false, then rack.hijack should not be set.
599
- assert("rack.hijack? is false, but rack.hijack is present") { env[RACK_HIJACK].nil? }
600
- ##
601
- ## If rack.hijack? is false, then rack.hijack_io should not be set.
602
- assert("rack.hijack? is false, but rack.hijack_io is present") { env[RACK_HIJACK_IO].nil? }
659
+ ##
660
+ ## === The content-type
661
+ ##
662
+ def check_content_type(status, headers)
663
+ headers.each { |key, value|
664
+ ## There must not be a <tt>content-type</tt> header key when the +Status+ is 1xx,
665
+ ## 204, or 304.
666
+ if key == "content-type"
667
+ if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
668
+ raise LintError, "content-type header found in #{status} response, not allowed"
669
+ end
670
+ return
671
+ end
672
+ }
603
673
  end
604
- end
605
674
 
606
- ## ==== Response (after headers)
607
- ## It is also possible to hijack a response after the status and headers
608
- ## have been sent.
609
- def check_hijack_response(headers, env)
610
-
611
- # this check uses headers like a hash, but the spec only requires
612
- # headers respond to #each
613
- headers = Rack::Utils::HeaderHash[headers]
614
-
615
- ## In order to do this, an application may set the special header
616
- ## <tt>rack.hijack</tt> to an object that responds to <tt>call</tt>
617
- ## accepting an argument that conforms to the <tt>rack.hijack_io</tt>
618
- ## protocol.
619
- ##
620
- ## After the headers have been sent, and this hijack callback has been
621
- ## called, the application is now responsible for the remaining lifecycle
622
- ## of the IO. The application is also responsible for maintaining HTTP
623
- ## semantics. Of specific note, in almost all cases in the current SPEC,
624
- ## applications will have wanted to specify the header Connection:close in
625
- ## HTTP/1.1, and not Connection:keep-alive, as there is no protocol for
626
- ## returning hijacked sockets to the web server. For that purpose, use the
627
- ## body streaming API instead (progressively yielding strings via each).
628
- ##
629
- ## Servers must ignore the <tt>body</tt> part of the response tuple when
630
- ## the <tt>rack.hijack</tt> response API is in use.
631
-
632
- if env[RACK_IS_HIJACK] && headers[RACK_HIJACK]
633
- assert('rack.hijack header must respond to #call') {
634
- headers[RACK_HIJACK].respond_to? :call
675
+ ##
676
+ ## === The content-length
677
+ ##
678
+ def check_content_length(status, headers)
679
+ headers.each { |key, value|
680
+ if key == 'content-length'
681
+ ## There must not be a <tt>content-length</tt> header key when the
682
+ ## +Status+ is 1xx, 204, or 304.
683
+ if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
684
+ raise LintError, "content-length header found in #{status} response, not allowed"
685
+ end
686
+ @content_length = value
687
+ end
635
688
  }
636
- original_hijack = headers[RACK_HIJACK]
637
- proc do |io|
638
- original_hijack.call HijackWrapper.new(io)
689
+ end
690
+
691
+ def verify_content_length(size)
692
+ if @head_request
693
+ unless size == 0
694
+ raise LintError, "Response body was given for HEAD request, but should be empty"
695
+ end
696
+ elsif @content_length
697
+ unless @content_length == size.to_s
698
+ raise LintError, "content-length header was #{@content_length}, but should be #{size}"
699
+ end
639
700
  end
640
- else
701
+ end
702
+
703
+ ##
704
+ ## === The Body
705
+ ##
706
+ ## The Body is typically an +Array+ of +String+ instances, an enumerable
707
+ ## that yields +String+ instances, a +Proc+ instance, or a File-like
708
+ ## object.
709
+ ##
710
+ ## The Body must respond to +each+ or +call+. It may optionally respond
711
+ ## to +to_path+ or +to_ary+. A Body that responds to +each+ is considered
712
+ ## to be an Enumerable Body. A Body that responds to +call+ is considered
713
+ ## to be a Streaming Body.
714
+ ##
715
+ ## A Body that responds to both +each+ and +call+ must be treated as an
716
+ ## Enumerable Body, not a Streaming Body. If it responds to +each+, you
717
+ ## must call +each+ and not +call+. If the Body doesn't respond to
718
+ ## +each+, then you can assume it responds to +call+.
719
+ ##
720
+ ## The Body must either be consumed or returned. The Body is consumed by
721
+ ## optionally calling either +each+ or +call+.
722
+ ## Then, if the Body responds to +close+, it must be called to release
723
+ ## any resources associated with the generation of the body.
724
+ ## In other words, +close+ must always be called at least once; typically
725
+ ## after the web server has sent the response to the client, but also in
726
+ ## cases where the Rack application makes internal/virtual requests and
727
+ ## discards the response.
728
+ ##
729
+ def close
641
730
  ##
642
- ## The special response header <tt>rack.hijack</tt> must only be set
643
- ## if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
644
- assert('rack.hijack header must not be present if server does not support hijacking') {
645
- headers[RACK_HIJACK].nil?
646
- }
731
+ ## After calling +close+, the Body is considered closed and should not
732
+ ## be consumed again.
733
+ @closed = true
647
734
 
648
- nil
735
+ ## If the original Body is replaced by a new Body, the new Body must
736
+ ## also consume the original Body by calling +close+ if possible.
737
+ @body.close if @body.respond_to?(:close)
738
+
739
+ index = @lint.index(self)
740
+ unless @env['rack.lint'][0..index].all? {|lint| lint.instance_variable_get(:@closed)}
741
+ raise LintError, "Body has not been closed"
742
+ end
649
743
  end
650
- end
651
- ## ==== Conventions
652
- ## * Middleware should not use hijack unless it is handling the whole
653
- ## response.
654
- ## * Middleware may wrap the IO object for the response pattern.
655
- ## * Middleware should not wrap the IO object for the request pattern. The
656
- ## request pattern is intended to provide the hijacker with "raw tcp".
657
-
658
- ## == The Response
659
-
660
- ## === The Status
661
- def check_status(status)
662
- ## This is an HTTP status. When parsed as integer (+to_i+), it must be
663
- ## greater than or equal to 100.
664
- assert("Status must be >=100 seen as integer") { status.to_i >= 100 }
665
- end
666
744
 
667
- ## === The Headers
668
- def check_headers(header)
669
- ## The header must respond to +each+, and yield values of key and value.
670
- assert("headers object should respond to #each, but doesn't (got #{header.class} as headers)") {
671
- header.respond_to? :each
672
- }
673
-
674
- header.each { |key, value|
675
- ## The header keys must be Strings.
676
- assert("header key must be a string, was #{key.class}") {
677
- key.kind_of? String
678
- }
745
+ def verify_to_path
746
+ ##
747
+ ## If the Body responds to +to_path+, it must return a +String+
748
+ ## path for the local file system whose contents are identical
749
+ ## to that produced by calling +each+; this may be used by the
750
+ ## server as an alternative, possibly more efficient way to
751
+ ## transport the response. The +to_path+ method does not consume
752
+ ## the body.
753
+ if @body.respond_to?(:to_path)
754
+ unless ::File.exist? @body.to_path
755
+ raise LintError, "The file identified by body.to_path does not exist"
756
+ end
757
+ end
758
+ end
679
759
 
680
- ## Special headers starting "rack." are for communicating with the
681
- ## server, and must not be sent back to the client.
682
- next if key =~ /^rack\..+$/
683
-
684
- ## The header must not contain a +Status+ key.
685
- assert("header must not contain Status") { key.downcase != "status" }
686
- ## The header must conform to RFC7230 token specification, i.e. cannot
687
- ## contain non-printable ASCII, DQUOTE or "(),/:;<=>?@[\]{}".
688
- assert("invalid header name: #{key}") { key !~ /[\(\),\/:;<=>\?@\[\\\]{}[:cntrl:]]/ }
689
-
690
- ## The values of the header must be Strings,
691
- assert("a header value must be a String, but the value of " +
692
- "'#{key}' is a #{value.class}") { value.kind_of? String }
693
- ## consisting of lines (for multiple header values, e.g. multiple
694
- ## <tt>Set-Cookie</tt> values) separated by "\\n".
695
- value.split("\n").each { |item|
696
- ## The lines must not contain characters below 037.
697
- assert("invalid header value #{key}: #{item.inspect}") {
698
- item !~ /[\000-\037]/
699
- }
700
- }
701
- }
702
- end
760
+ ##
761
+ ## ==== Enumerable Body
762
+ ##
763
+ def each
764
+ ## The Enumerable Body must respond to +each+.
765
+ raise LintError, "Enumerable Body must respond to each" unless @body.respond_to?(:each)
703
766
 
704
- ## === The Content-Type
705
- def check_content_type(status, headers)
706
- headers.each { |key, value|
707
- ## There must not be a <tt>Content-Type</tt>, when the +Status+ is 1xx,
708
- ## 204 or 304.
709
- if key.downcase == "content-type"
710
- assert("Content-Type header found in #{status} response, not allowed") {
711
- not Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
712
- }
713
- return
714
- end
715
- }
716
- end
767
+ ## It must only be called once.
768
+ raise LintError, "Response body must only be invoked once (#{@invoked})" unless @invoked.nil?
717
769
 
718
- ## === The Content-Length
719
- def check_content_length(status, headers)
720
- headers.each { |key, value|
721
- if key.downcase == 'content-length'
722
- ## There must not be a <tt>Content-Length</tt> header when the
723
- ## +Status+ is 1xx, 204 or 304.
724
- assert("Content-Length header found in #{status} response, not allowed") {
725
- not Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
726
- }
727
- @content_length = value
770
+ ## It must not be called after being closed.
771
+ raise LintError, "Response body is already closed" if @closed
772
+
773
+ @invoked = :each
774
+
775
+ @body.each do |chunk|
776
+ ## and must only yield String values.
777
+ unless chunk.kind_of? String
778
+ raise LintError, "Body yielded non-string value #{chunk.inspect}"
779
+ end
780
+
781
+ ##
782
+ ## The Body itself should not be an instance of String, as this will
783
+ ## break in Ruby 1.9.
784
+ ##
785
+ ## Middleware must not call +each+ directly on the Body.
786
+ ## Instead, middleware can return a new Body that calls +each+ on the
787
+ ## original Body, yielding at least once per iteration.
788
+ if @lint[0] == self
789
+ @env['rack.lint.body_iteration'] += 1
790
+ else
791
+ if (@env['rack.lint.body_iteration'] -= 1) > 0
792
+ raise LintError, "New body must yield at least once per iteration of old body"
793
+ end
794
+ end
795
+
796
+ @size += chunk.bytesize
797
+ yield chunk
728
798
  end
729
- }
730
- end
731
799
 
732
- def verify_content_length(bytes)
733
- if @head_request
734
- assert("Response body was given for HEAD request, but should be empty") {
735
- bytes == 0
736
- }
737
- elsif @content_length
738
- assert("Content-Length header was #{@content_length}, but should be #{bytes}") {
739
- @content_length == bytes.to_s
740
- }
741
- end
742
- end
800
+ verify_content_length(@size)
743
801
 
744
- ## === The Body
745
- def each
746
- @closed = false
747
- bytes = 0
802
+ verify_to_path
803
+ end
748
804
 
749
- ## The Body must respond to +each+
750
- assert("Response body must respond to each") do
751
- @body.respond_to?(:each)
805
+ def respond_to?(name, *)
806
+ if name == :to_ary
807
+ @body.respond_to?(name)
808
+ else
809
+ super
810
+ end
752
811
  end
753
812
 
754
- @body.each { |part|
755
- ## and must only yield String values.
756
- assert("Body yielded non-string value #{part.inspect}") {
757
- part.kind_of? String
758
- }
759
- bytes += part.bytesize
760
- yield part
761
- }
762
- verify_content_length(bytes)
813
+ ##
814
+ ## If the Body responds to +to_ary+, it must return an +Array+ whose
815
+ ## contents are identical to that produced by calling +each+.
816
+ ## Middleware may call +to_ary+ directly on the Body and return a new
817
+ ## Body in its place. In other words, middleware can only process the
818
+ ## Body directly if it responds to +to_ary+. If the Body responds to both
819
+ ## +to_ary+ and +close+, its implementation of +to_ary+ must call
820
+ ## +close+.
821
+ def to_ary
822
+ @body.to_ary.tap do |content|
823
+ unless content == @body.enum_for.to_a
824
+ raise LintError, "#to_ary not identical to contents produced by calling #each"
825
+ end
826
+ end
827
+ ensure
828
+ close
829
+ end
763
830
 
764
831
  ##
765
- ## The Body itself should not be an instance of String, as this will
766
- ## break in Ruby 1.9.
832
+ ## ==== Streaming Body
767
833
  ##
768
- ## If the Body responds to +close+, it will be called after iteration. If
769
- ## the body is replaced by a middleware after action, the original body
770
- ## must be closed first, if it responds to close.
771
- # XXX howto: assert("Body has not been closed") { @closed }
834
+ def call(stream)
835
+ ## The Streaming Body must respond to +call+.
836
+ raise LintError, "Streaming Body must respond to call" unless @body.respond_to?(:call)
772
837
 
838
+ ## It must only be called once.
839
+ raise LintError, "Response body must only be invoked once (#{@invoked})" unless @invoked.nil?
773
840
 
774
- ##
775
- ## If the Body responds to +to_path+, it must return a String
776
- ## identifying the location of a file whose contents are identical
777
- ## to that produced by calling +each+; this may be used by the
778
- ## server as an alternative, possibly more efficient way to
779
- ## transport the response.
841
+ ## It must not be called after being closed.
842
+ raise LintError, "Response body is already closed" if @closed
780
843
 
781
- if @body.respond_to?(:to_path)
782
- assert("The file identified by body.to_path does not exist") {
783
- ::File.exist? @body.to_path
784
- }
844
+ @invoked = :call
845
+
846
+ ## It takes a +stream+ argument.
847
+ ##
848
+ ## The +stream+ argument must implement:
849
+ ## <tt>read, write, flush, close, close_read, close_write, closed?</tt>
850
+ ##
851
+ @body.call(StreamWrapper.new(stream))
785
852
  end
786
853
 
787
- ##
788
- ## The Body commonly is an Array of Strings, the application
789
- ## instance itself, or a File-like object.
790
- end
854
+ class StreamWrapper
855
+ extend Forwardable
856
+
857
+ ## The semantics of these IO methods must be a best effort match to
858
+ ## those of a normal Ruby IO or Socket object, using standard arguments
859
+ ## and raising standard exceptions. Servers are encouraged to simply
860
+ ## pass on real IO objects, although it is recognized that this approach
861
+ ## is not directly compatible with HTTP/2.
862
+ REQUIRED_METHODS = [
863
+ :read, :write, :flush, :close,
864
+ :close_read, :close_write, :closed?
865
+ ]
866
+
867
+ def_delegators :@stream, *REQUIRED_METHODS
868
+
869
+ def initialize(stream)
870
+ @stream = stream
871
+
872
+ REQUIRED_METHODS.each do |method_name|
873
+ raise LintError, "Stream must respond to #{method_name}" unless stream.respond_to?(method_name)
874
+ end
875
+ end
876
+ end
791
877
 
792
- def close
793
- @closed = true
794
- @body.close if @body.respond_to?(:close)
878
+ # :startdoc:
795
879
  end
796
-
797
- # :startdoc:
798
-
799
880
  end
800
881
  end
801
882
 
883
+ ##
802
884
  ## == Thanks
803
- ## Some parts of this specification are adopted from PEP333: Python
804
- ## Web Server Gateway Interface
805
- ## v1.0 (http://www.python.org/dev/peps/pep-0333/). I'd like to thank
806
- ## everyone involved in that effort.
885
+ ## Some parts of this specification are adopted from {PEP 333 – Python Web Server Gateway Interface v1.0}[https://peps.python.org/pep-0333/]
886
+ ## I'd like to thank everyone involved in that effort.