rack 2.2.3.1 → 3.0.0.rc1

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 (86) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +174 -69
  3. data/CONTRIBUTING.md +53 -47
  4. data/MIT-LICENSE +1 -1
  5. data/README.md +293 -0
  6. data/SPEC.rdoc +183 -131
  7. data/lib/rack/auth/abstract/handler.rb +3 -1
  8. data/lib/rack/auth/abstract/request.rb +3 -1
  9. data/lib/rack/auth/digest/md5.rb +1 -131
  10. data/lib/rack/auth/digest/nonce.rb +1 -54
  11. data/lib/rack/auth/digest/params.rb +1 -54
  12. data/lib/rack/auth/digest/request.rb +1 -43
  13. data/lib/rack/auth/digest.rb +256 -0
  14. data/lib/rack/body_proxy.rb +3 -1
  15. data/lib/rack/builder.rb +60 -42
  16. data/lib/rack/cascade.rb +2 -0
  17. data/lib/rack/chunked.rb +16 -13
  18. data/lib/rack/common_logger.rb +23 -18
  19. data/lib/rack/conditional_get.rb +18 -15
  20. data/lib/rack/constants.rb +63 -0
  21. data/lib/rack/content_length.rb +12 -16
  22. data/lib/rack/content_type.rb +8 -5
  23. data/lib/rack/deflater.rb +40 -26
  24. data/lib/rack/directory.rb +9 -3
  25. data/lib/rack/etag.rb +14 -21
  26. data/lib/rack/events.rb +4 -0
  27. data/lib/rack/file.rb +2 -0
  28. data/lib/rack/files.rb +15 -17
  29. data/lib/rack/head.rb +9 -8
  30. data/lib/rack/headers.rb +154 -0
  31. data/lib/rack/lint.rb +779 -684
  32. data/lib/rack/lock.rb +2 -5
  33. data/lib/rack/logger.rb +2 -0
  34. data/lib/rack/media_type.rb +1 -1
  35. data/lib/rack/method_override.rb +4 -0
  36. data/lib/rack/mime.rb +8 -0
  37. data/lib/rack/mock.rb +1 -271
  38. data/lib/rack/mock_request.rb +166 -0
  39. data/lib/rack/mock_response.rb +126 -0
  40. data/lib/rack/multipart/generator.rb +7 -5
  41. data/lib/rack/multipart/parser.rb +118 -61
  42. data/lib/rack/multipart/uploaded_file.rb +4 -0
  43. data/lib/rack/multipart.rb +20 -40
  44. data/lib/rack/null_logger.rb +9 -0
  45. data/lib/rack/query_parser.rb +80 -44
  46. data/lib/rack/recursive.rb +2 -0
  47. data/lib/rack/reloader.rb +0 -2
  48. data/lib/rack/request.rb +187 -89
  49. data/lib/rack/response.rb +131 -61
  50. data/lib/rack/rewindable_input.rb +24 -5
  51. data/lib/rack/runtime.rb +7 -6
  52. data/lib/rack/sendfile.rb +30 -25
  53. data/lib/rack/show_exceptions.rb +15 -2
  54. data/lib/rack/show_status.rb +17 -7
  55. data/lib/rack/static.rb +8 -8
  56. data/lib/rack/tempfile_reaper.rb +15 -4
  57. data/lib/rack/urlmap.rb +3 -1
  58. data/lib/rack/utils.rb +199 -170
  59. data/lib/rack/version.rb +9 -4
  60. data/lib/rack.rb +5 -76
  61. metadata +16 -36
  62. data/README.rdoc +0 -306
  63. data/Rakefile +0 -130
  64. data/bin/rackup +0 -5
  65. data/contrib/rack.png +0 -0
  66. data/contrib/rack.svg +0 -150
  67. data/contrib/rack_logo.svg +0 -164
  68. data/contrib/rdoc.css +0 -412
  69. data/example/lobster.ru +0 -6
  70. data/example/protectedlobster.rb +0 -16
  71. data/example/protectedlobster.ru +0 -10
  72. data/lib/rack/core_ext/regexp.rb +0 -14
  73. data/lib/rack/handler/cgi.rb +0 -59
  74. data/lib/rack/handler/fastcgi.rb +0 -100
  75. data/lib/rack/handler/lsws.rb +0 -61
  76. data/lib/rack/handler/scgi.rb +0 -71
  77. data/lib/rack/handler/thin.rb +0 -36
  78. data/lib/rack/handler/webrick.rb +0 -129
  79. data/lib/rack/handler.rb +0 -104
  80. data/lib/rack/lobster.rb +0 -70
  81. data/lib/rack/server.rb +0 -466
  82. data/lib/rack/session/abstract/id.rb +0 -523
  83. data/lib/rack/session/cookie.rb +0 -203
  84. data/lib/rack/session/memcache.rb +0 -10
  85. data/lib/rack/session/pool.rb +0 -85
  86. data/rack.gemspec +0 -46
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,890 @@ 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 #{ary.inspect} is not an Array , but #{ary.class}") {
52
- ary.kind_of? Array
53
- }
54
- assert("response array #{ary.inspect} 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
233
+
234
+ ## error(message, &block)
235
+ unless logger.respond_to?(:error)
236
+ raise LintError, "logger #{logger.inspect} must respond to error"
237
+ end
258
238
 
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
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
366
+
367
+ ## <tt>rack.response_finished</tt>:: An array of callables run by the server after the response has been
368
+ ## processed. This would typically be invoked after sending the response to the client, but it could also be
369
+ ## invoked if an error occurs while generating the response or sending the response; in that case, the error
370
+ ## argument will be a subclass of +Exception+.
371
+ ## The callables are invoked with +env, status, headers, error+ arguments and should not raise any
372
+ ## exceptions. They should be invoked in reverse order of registration.
373
+ if callables = env[RACK_RESPONSE_FINISHED]
374
+ raise LintError, "rack.response_finished must be an array of callable objects" unless callables.is_a?(Array)
375
+
376
+ callables.each do |callable|
377
+ raise LintError, "rack.response_finished values must respond to call(env, status, headers, error)" unless callable.respond_to?(:call)
378
+ end
379
+ end
411
380
  end
412
381
 
413
- ## * +read+ behaves like IO#read.
414
- ## Its signature is <tt>read([length, [buffer]])</tt>.
415
382
  ##
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.
383
+ ## === The Input Stream
418
384
  ##
419
- ## If +length+ is given and not nil, then this method reads at most
420
- ## +length+ bytes from the input stream.
421
- ##
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
- }
385
+ ## The input stream is an IO-like object which contains the raw HTTP
386
+ ## POST data.
387
+ def check_input(input)
388
+ ## When applicable, its external encoding must be "ASCII-8BIT" and it
389
+ ## must be opened in binary mode, for Ruby 1.9 compatibility.
390
+ if input.respond_to?(:external_encoding) && input.external_encoding != Encoding::ASCII_8BIT
391
+ raise LintError, "rack.input #{input} does not have ASCII-8BIT as its external encoding"
441
392
  end
442
- if args.size >= 2
443
- assert("rack.input#read called with non-String buffer") {
444
- args[1].kind_of?(String)
445
- }
393
+ if input.respond_to?(:binmode?) && !input.binmode?
394
+ raise LintError, "rack.input #{input} is not opened in binary mode"
446
395
  end
447
396
 
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
397
+ ## The input stream must respond to +gets+, +each+, and +read+.
398
+ [:gets, :each, :read].each { |method|
399
+ unless input.respond_to? method
400
+ raise LintError, "rack.input #{input} does not respond to ##{method}"
401
+ end
452
402
  }
453
- if args[0].nil?
454
- assert("rack.input#read(nil) returned nil on EOF") {
455
- !v.nil?
456
- }
403
+ end
404
+
405
+ class InputWrapper
406
+ def initialize(input)
407
+ @input = input
457
408
  end
458
409
 
459
- v
460
- end
410
+ ## * +gets+ must be called without arguments and return a string,
411
+ ## or +nil+ on EOF.
412
+ def gets(*args)
413
+ raise LintError, "rack.input#gets called with arguments" unless args.size == 0
414
+ v = @input.gets
415
+ unless v.nil? or v.kind_of? String
416
+ raise LintError, "rack.input#gets didn't return a String"
417
+ end
418
+ v
419
+ end
420
+
421
+ ## * +read+ behaves like IO#read.
422
+ ## Its signature is <tt>read([length, [buffer]])</tt>.
423
+ ##
424
+ ## If given, +length+ must be a non-negative Integer (>= 0) or +nil+,
425
+ ## and +buffer+ must be a String and may not be nil.
426
+ ##
427
+ ## If +length+ is given and not nil, then this method reads at most
428
+ ## +length+ bytes from the input stream.
429
+ ##
430
+ ## If +length+ is not given or nil, then this method reads
431
+ ## all data until EOF.
432
+ ##
433
+ ## When EOF is reached, this method returns nil if +length+ is given
434
+ ## and not nil, or "" if +length+ is not given or is nil.
435
+ ##
436
+ ## If +buffer+ is given, then the read data will be placed
437
+ ## into +buffer+ instead of a newly created String object.
438
+ def read(*args)
439
+ unless args.size <= 2
440
+ raise LintError, "rack.input#read called with too many arguments"
441
+ end
442
+ if args.size >= 1
443
+ unless args.first.kind_of?(Integer) || args.first.nil?
444
+ raise LintError, "rack.input#read called with non-integer and non-nil length"
445
+ end
446
+ unless args.first.nil? || args.first >= 0
447
+ raise LintError, "rack.input#read called with a negative length"
448
+ end
449
+ end
450
+ if args.size >= 2
451
+ unless args[1].kind_of?(String)
452
+ raise LintError, "rack.input#read called with non-String buffer"
453
+ end
454
+ end
455
+
456
+ v = @input.read(*args)
457
+
458
+ unless v.nil? or v.kind_of? String
459
+ raise LintError, "rack.input#read didn't return nil or a String"
460
+ end
461
+ if args[0].nil?
462
+ unless !v.nil?
463
+ raise LintError, "rack.input#read(nil) returned nil on EOF"
464
+ end
465
+ end
461
466
 
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
467
+ v
468
+ end
469
+
470
+ ## * +each+ must be called without arguments and only yield Strings.
471
+ def each(*args)
472
+ raise LintError, "rack.input#each called with arguments" unless args.size == 0
473
+ @input.each { |line|
474
+ unless line.kind_of? String
475
+ raise LintError, "rack.input#each didn't yield a String"
476
+ end
477
+ yield line
468
478
  }
469
- yield line
470
- }
479
+ end
480
+
481
+ ## * +close+ can be called on the input stream to indicate that the
482
+ ## any remaining input is not needed.
483
+ def close(*args)
484
+ @input.close(*args)
485
+ end
471
486
  end
472
487
 
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
488
+ ##
489
+ ## === The Error Stream
490
+ ##
491
+ def check_error(error)
492
+ ## The error stream must respond to +puts+, +write+ and +flush+.
493
+ [:puts, :write, :flush].each { |method|
494
+ unless error.respond_to? method
495
+ raise LintError, "rack.error #{error} does not respond to ##{method}"
486
496
  end
487
497
  }
488
498
  end
489
499
 
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
500
+ class ErrorWrapper
501
+ def initialize(error)
502
+ @error = error
503
+ end
495
504
 
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
505
+ ## * +puts+ must be called with a single argument that responds to +to_s+.
506
+ def puts(str)
507
+ @error.puts str
508
+ end
505
509
 
506
- class ErrorWrapper
507
- include Assertion
510
+ ## * +write+ must be called with a single argument that is a String.
511
+ def write(str)
512
+ raise LintError, "rack.errors#write not called with a String" unless str.kind_of? String
513
+ @error.write str
514
+ end
508
515
 
509
- def initialize(error)
510
- @error = error
511
- end
516
+ ## * +flush+ must be called without arguments and must be called
517
+ ## in order to make the error appear for sure.
518
+ def flush
519
+ @error.flush
520
+ end
512
521
 
513
- ## * +puts+ must be called with a single argument that responds to +to_s+.
514
- def puts(str)
515
- @error.puts str
522
+ ## * +close+ must never be called on the error stream.
523
+ def close(*args)
524
+ raise LintError, "rack.errors#close must not be called"
525
+ end
516
526
  end
517
527
 
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
528
+ ##
529
+ ## === Hijacking
530
+ ##
531
+ ## The hijacking interfaces provides a means for an application to take
532
+ ## control of the HTTP connection. There are two distinct hijack
533
+ ## interfaces: full hijacking where the application takes over the raw
534
+ ## connection, and partial hijacking where the application takes over
535
+ ## just the response body stream. In both cases, the application is
536
+ ## responsible for closing the hijacked stream.
537
+ ##
538
+ ## Full hijacking only works with HTTP/1. Partial hijacking is functionally
539
+ ## equivalent to streaming bodies, and is still optionally supported for
540
+ ## backwards compatibility with older Rack versions.
541
+ ##
542
+ ## ==== Full Hijack
543
+ ##
544
+ ## Full hijack is used to completely take over an HTTP/1 connection. It
545
+ ## occurs before any headers are written and causes the request to
546
+ ## ignores any response generated by the application.
547
+ ##
548
+ ## It is intended to be used when applications need access to raw HTTP/1
549
+ ## connection.
550
+ ##
551
+ def check_hijack(env)
552
+ ## If +rack.hijack+ is present in +env+, it must respond to +call+
553
+ if original_hijack = env[RACK_HIJACK]
554
+ raise LintError, "rack.hijack must respond to call" unless original_hijack.respond_to?(:call)
555
+
556
+ env[RACK_HIJACK] = proc do
557
+ io = original_hijack.call
558
+
559
+ ## and return an +IO+ instance which can be used to read and write
560
+ ## to the underlying connection using HTTP/1 semantics and
561
+ ## formatting.
562
+ raise LintError, "rack.hijack must return an IO instance" unless io.is_a?(IO)
563
+
564
+ io
565
+ end
566
+ end
522
567
  end
523
568
 
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
569
+ ##
570
+ ## ==== Partial Hijack
571
+ ##
572
+ ## Partial hijack is used for bi-directional streaming of the request and
573
+ ## response body. It occurs after the status and headers are written by
574
+ ## the server and causes the server to ignore the Body of the response.
575
+ ##
576
+ ## It is intended to be used when applications need bi-directional
577
+ ## streaming.
578
+ ##
579
+ def check_hijack_response(headers, env)
580
+ ## If +rack.hijack?+ is present in +env+ and truthy,
581
+ if env[RACK_IS_HIJACK]
582
+ ## an application may set the special response header +rack.hijack+
583
+ if original_hijack = headers[RACK_HIJACK]
584
+ ## to an object that responds to +call+,
585
+ unless original_hijack.respond_to?(:call)
586
+ raise LintError, 'rack.hijack header must respond to #call'
587
+ end
588
+ ## accepting a +stream+ argument.
589
+ return proc do |io|
590
+ original_hijack.call StreamWrapper.new(io)
591
+ end
592
+ end
593
+ ##
594
+ ## After the response status and headers have been sent, this hijack
595
+ ## callback will be invoked with a +stream+ argument which follows the
596
+ ## same interface as outlined in "Streaming Body". Servers must
597
+ ## ignore the +body+ part of the response tuple when the
598
+ ## +rack.hijack+ response header is present. Using an empty +Array+
599
+ ## instance is recommended.
600
+ else
601
+ ##
602
+ ## The special response header +rack.hijack+ must only be set
603
+ ## if the request +env+ has a truthy +rack.hijack?+.
604
+ if headers.key?(RACK_HIJACK)
605
+ raise LintError, 'rack.hijack header must not be present if server does not support hijacking'
606
+ end
607
+ end
608
+
609
+ nil
528
610
  end
529
611
 
530
- ## * +close+ must never be called on the error stream.
531
- def close(*args)
532
- assert("rack.errors#close must not be called") { false }
612
+ ## == The Response
613
+ ##
614
+ ## === The Status
615
+ ##
616
+ def check_status(status)
617
+ ## This is an HTTP status. It must be an Integer greater than or equal to
618
+ ## 100.
619
+ unless status.is_a?(Integer) && status >= 100
620
+ raise LintError, "Status must be an Integer >=100"
621
+ end
533
622
  end
534
- end
535
623
 
536
- class HijackWrapper
537
- include Assertion
538
- extend Forwardable
624
+ ##
625
+ ## === The Headers
626
+ ##
627
+ def check_headers(headers)
628
+ ## The headers must be a unfrozen Hash.
629
+ unless headers.kind_of?(Hash)
630
+ raise LintError, "headers object should be a hash, but isn't (got #{headers.class} as headers)"
631
+ end
632
+
633
+ if headers.frozen?
634
+ raise LintError, "headers object should not be frozen, but is"
635
+ end
539
636
 
540
- REQUIRED_METHODS = [
541
- :read, :write, :read_nonblock, :write_nonblock, :flush, :close,
542
- :close_read, :close_write, :closed?
543
- ]
637
+ headers.each do |key, value|
638
+ ## The header keys must be Strings.
639
+ unless key.kind_of? String
640
+ raise LintError, "header key must be a string, was #{key.class}"
641
+ end
544
642
 
545
- def_delegators :@io, *REQUIRED_METHODS
643
+ ## Special headers starting "rack." are for communicating with the
644
+ ## server, and must not be sent back to the client.
645
+ next if key.start_with?("rack.")
646
+
647
+ ## The header must not contain a +Status+ key.
648
+ raise LintError, "header must not contain status" if key == "status"
649
+ ## Header keys must conform to RFC7230 token specification, i.e. cannot
650
+ ## contain non-printable ASCII, DQUOTE or "(),/:;<=>?@[\]{}".
651
+ raise LintError, "invalid header name: #{key}" if key =~ /[\(\),\/:;<=>\?@\[\\\]{}[:cntrl:]]/
652
+ ## Header keys must not contain uppercase ASCII characters (A-Z).
653
+ raise LintError, "uppercase character in header name: #{key}" if key =~ /[A-Z]/
654
+
655
+ ## Header values must be either a String instance,
656
+ if value.kind_of?(String)
657
+ check_header_value(key, value)
658
+ elsif value.kind_of?(Array)
659
+ ## or an Array of String instances,
660
+ value.each{|value| check_header_value(key, value)}
661
+ else
662
+ raise LintError, "a header value must be a String or Array of Strings, but the value of '#{key}' is a #{value.class}"
663
+ end
664
+ end
665
+ end
546
666
 
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 }
667
+ def check_header_value(key, value)
668
+ ## such that each String instance must not contain characters below 037.
669
+ if value =~ /[\000-\037]/
670
+ raise LintError, "invalid header value #{key}: #{value.inspect}"
551
671
  end
552
672
  end
553
- end
554
673
 
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? }
674
+ ##
675
+ ## === The content-type
676
+ ##
677
+ def check_content_type(status, headers)
678
+ headers.each { |key, value|
679
+ ## There must not be a <tt>content-type</tt> header key when the +Status+ is 1xx,
680
+ ## 204, or 304.
681
+ if key == "content-type"
682
+ if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
683
+ raise LintError, "content-type header found in #{status} response, not allowed"
684
+ end
685
+ return
686
+ end
687
+ }
603
688
  end
604
- end
605
689
 
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
690
+ ##
691
+ ## === The content-length
692
+ ##
693
+ def check_content_length(status, headers)
694
+ headers.each { |key, value|
695
+ if key == 'content-length'
696
+ ## There must not be a <tt>content-length</tt> header key when the
697
+ ## +Status+ is 1xx, 204, or 304.
698
+ if Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
699
+ raise LintError, "content-length header found in #{status} response, not allowed"
700
+ end
701
+ @content_length = value
702
+ end
635
703
  }
636
- original_hijack = headers[RACK_HIJACK]
637
- proc do |io|
638
- original_hijack.call HijackWrapper.new(io)
704
+ end
705
+
706
+ def verify_content_length(size)
707
+ if @head_request
708
+ unless size == 0
709
+ raise LintError, "Response body was given for HEAD request, but should be empty"
710
+ end
711
+ elsif @content_length
712
+ unless @content_length == size.to_s
713
+ raise LintError, "content-length header was #{@content_length}, but should be #{size}"
714
+ end
639
715
  end
640
- else
716
+ end
717
+
718
+ ##
719
+ ## === The Body
720
+ ##
721
+ ## The Body is typically an +Array+ of +String+ instances, an enumerable
722
+ ## that yields +String+ instances, a +Proc+ instance, or a File-like
723
+ ## object.
724
+ ##
725
+ ## The Body must respond to +each+ or +call+. It may optionally respond
726
+ ## to +to_path+ or +to_ary+. A Body that responds to +each+ is considered
727
+ ## to be an Enumerable Body. A Body that responds to +call+ is considered
728
+ ## to be a Streaming Body.
729
+ ##
730
+ ## A Body that responds to both +each+ and +call+ must be treated as an
731
+ ## Enumerable Body, not a Streaming Body. If it responds to +each+, you
732
+ ## must call +each+ and not +call+. If the Body doesn't respond to
733
+ ## +each+, then you can assume it responds to +call+.
734
+ ##
735
+ ## The Body must either be consumed or returned. The Body is consumed by
736
+ ## optionally calling either +each+ or +call+.
737
+ ## Then, if the Body responds to +close+, it must be called to release
738
+ ## any resources associated with the generation of the body.
739
+ ## In other words, +close+ must always be called at least once; typically
740
+ ## after the web server has sent the response to the client, but also in
741
+ ## cases where the Rack application makes internal/virtual requests and
742
+ ## discards the response.
743
+ ##
744
+ def close
641
745
  ##
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
- }
746
+ ## After calling +close+, the Body is considered closed and should not
747
+ ## be consumed again.
748
+ @closed = true
647
749
 
648
- nil
750
+ ## If the original Body is replaced by a new Body, the new Body must
751
+ ## also consume the original Body by calling +close+ if possible.
752
+ @body.close if @body.respond_to?(:close)
753
+
754
+ index = @lint.index(self)
755
+ unless @env['rack.lint'][0..index].all? {|lint| lint.instance_variable_get(:@closed)}
756
+ raise LintError, "Body has not been closed"
757
+ end
649
758
  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
759
 
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
- }
760
+ def verify_to_path
761
+ ##
762
+ ## If the Body responds to +to_path+, it must return a +String+
763
+ ## path for the local file system whose contents are identical
764
+ ## to that produced by calling +each+; this may be used by the
765
+ ## server as an alternative, possibly more efficient way to
766
+ ## transport the response. The +to_path+ method does not consume
767
+ ## the body.
768
+ if @body.respond_to?(:to_path)
769
+ unless ::File.exist? @body.to_path
770
+ raise LintError, "The file identified by body.to_path does not exist"
771
+ end
772
+ end
773
+ end
679
774
 
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
775
+ ##
776
+ ## ==== Enumerable Body
777
+ ##
778
+ def each
779
+ ## The Enumerable Body must respond to +each+.
780
+ raise LintError, "Enumerable Body must respond to each" unless @body.respond_to?(:each)
703
781
 
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
782
+ ## It must only be called once.
783
+ raise LintError, "Response body must only be invoked once (#{@invoked})" unless @invoked.nil?
717
784
 
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
785
+ ## It must not be called after being closed.
786
+ raise LintError, "Response body is already closed" if @closed
787
+
788
+ @invoked = :each
789
+
790
+ @body.each do |chunk|
791
+ ## and must only yield String values.
792
+ unless chunk.kind_of? String
793
+ raise LintError, "Body yielded non-string value #{chunk.inspect}"
794
+ end
795
+
796
+ ##
797
+ ## The Body itself should not be an instance of String, as this will
798
+ ## break in Ruby 1.9.
799
+ ##
800
+ ## Middleware must not call +each+ directly on the Body.
801
+ ## Instead, middleware can return a new Body that calls +each+ on the
802
+ ## original Body, yielding at least once per iteration.
803
+ if @lint[0] == self
804
+ @env['rack.lint.body_iteration'] += 1
805
+ else
806
+ if (@env['rack.lint.body_iteration'] -= 1) > 0
807
+ raise LintError, "New body must yield at least once per iteration of old body"
808
+ end
809
+ end
810
+
811
+ @size += chunk.bytesize
812
+ yield chunk
728
813
  end
729
- }
730
- end
731
814
 
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
815
+ verify_content_length(@size)
743
816
 
744
- ## === The Body
745
- def each
746
- @closed = false
747
- bytes = 0
817
+ verify_to_path
818
+ end
748
819
 
749
- ## The Body must respond to +each+
750
- assert("Response body must respond to each") do
751
- @body.respond_to?(:each)
820
+ def respond_to?(name, *)
821
+ if name == :to_ary
822
+ @body.respond_to?(name)
823
+ else
824
+ super
825
+ end
752
826
  end
753
827
 
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)
828
+ ##
829
+ ## If the Body responds to +to_ary+, it must return an +Array+ whose
830
+ ## contents are identical to that produced by calling +each+.
831
+ ## Middleware may call +to_ary+ directly on the Body and return a new
832
+ ## Body in its place. In other words, middleware can only process the
833
+ ## Body directly if it responds to +to_ary+. If the Body responds to both
834
+ ## +to_ary+ and +close+, its implementation of +to_ary+ must call
835
+ ## +close+.
836
+ def to_ary
837
+ @body.to_ary.tap do |content|
838
+ unless content == @body.enum_for.to_a
839
+ raise LintError, "#to_ary not identical to contents produced by calling #each"
840
+ end
841
+ end
842
+ ensure
843
+ close
844
+ end
763
845
 
764
846
  ##
765
- ## The Body itself should not be an instance of String, as this will
766
- ## break in Ruby 1.9.
847
+ ## ==== Streaming Body
767
848
  ##
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 }
849
+ def call(stream)
850
+ ## The Streaming Body must respond to +call+.
851
+ raise LintError, "Streaming Body must respond to call" unless @body.respond_to?(:call)
772
852
 
853
+ ## It must only be called once.
854
+ raise LintError, "Response body must only be invoked once (#{@invoked})" unless @invoked.nil?
773
855
 
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.
856
+ ## It must not be called after being closed.
857
+ raise LintError, "Response body is already closed" if @closed
780
858
 
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
- }
859
+ @invoked = :call
860
+
861
+ ## It takes a +stream+ argument.
862
+ ##
863
+ ## The +stream+ argument must implement:
864
+ ## <tt>read, write, <<, flush, close, close_read, close_write, closed?</tt>
865
+ ##
866
+ @body.call(StreamWrapper.new(stream))
785
867
  end
786
868
 
787
- ##
788
- ## The Body commonly is an Array of Strings, the application
789
- ## instance itself, or a File-like object.
790
- end
869
+ class StreamWrapper
870
+ extend Forwardable
871
+
872
+ ## The semantics of these IO methods must be a best effort match to
873
+ ## those of a normal Ruby IO or Socket object, using standard arguments
874
+ ## and raising standard exceptions. Servers are encouraged to simply
875
+ ## pass on real IO objects, although it is recognized that this approach
876
+ ## is not directly compatible with HTTP/2.
877
+ REQUIRED_METHODS = [
878
+ :read, :write, :<<, :flush, :close,
879
+ :close_read, :close_write, :closed?
880
+ ]
881
+
882
+ def_delegators :@stream, *REQUIRED_METHODS
883
+
884
+ def initialize(stream)
885
+ @stream = stream
886
+
887
+ REQUIRED_METHODS.each do |method_name|
888
+ raise LintError, "Stream must respond to #{method_name}" unless stream.respond_to?(method_name)
889
+ end
890
+ end
891
+ end
791
892
 
792
- def close
793
- @closed = true
794
- @body.close if @body.respond_to?(:close)
893
+ # :startdoc:
795
894
  end
796
-
797
- # :startdoc:
798
-
799
895
  end
800
896
  end
801
897
 
898
+ ##
802
899
  ## == 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.
900
+ ## Some parts of this specification are adopted from {PEP 333 – Python Web Server Gateway Interface v1.0}[https://peps.python.org/pep-0333/]
901
+ ## I'd like to thank everyone involved in that effort.