rack 2.1.3 → 2.2.1

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 (61) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +613 -1
  3. data/CONTRIBUTING.md +136 -0
  4. data/README.rdoc +83 -39
  5. data/Rakefile +14 -7
  6. data/{SPEC → SPEC.rdoc} +26 -1
  7. data/lib/rack.rb +7 -16
  8. data/lib/rack/auth/abstract/request.rb +0 -2
  9. data/lib/rack/auth/basic.rb +3 -3
  10. data/lib/rack/auth/digest/md5.rb +4 -4
  11. data/lib/rack/auth/digest/request.rb +3 -3
  12. data/lib/rack/body_proxy.rb +13 -9
  13. data/lib/rack/builder.rb +77 -8
  14. data/lib/rack/cascade.rb +23 -8
  15. data/lib/rack/chunked.rb +48 -23
  16. data/lib/rack/common_logger.rb +25 -18
  17. data/lib/rack/conditional_get.rb +18 -16
  18. data/lib/rack/content_length.rb +6 -7
  19. data/lib/rack/content_type.rb +3 -4
  20. data/lib/rack/deflater.rb +45 -35
  21. data/lib/rack/directory.rb +77 -59
  22. data/lib/rack/etag.rb +2 -3
  23. data/lib/rack/events.rb +15 -18
  24. data/lib/rack/file.rb +1 -1
  25. data/lib/rack/files.rb +96 -56
  26. data/lib/rack/handler/cgi.rb +1 -4
  27. data/lib/rack/handler/fastcgi.rb +1 -3
  28. data/lib/rack/handler/lsws.rb +1 -3
  29. data/lib/rack/handler/scgi.rb +1 -3
  30. data/lib/rack/handler/thin.rb +15 -11
  31. data/lib/rack/handler/webrick.rb +12 -5
  32. data/lib/rack/head.rb +0 -2
  33. data/lib/rack/lint.rb +57 -14
  34. data/lib/rack/lobster.rb +3 -5
  35. data/lib/rack/lock.rb +0 -1
  36. data/lib/rack/mock.rb +22 -4
  37. data/lib/rack/multipart.rb +1 -1
  38. data/lib/rack/multipart/generator.rb +11 -6
  39. data/lib/rack/multipart/parser.rb +7 -15
  40. data/lib/rack/multipart/uploaded_file.rb +13 -7
  41. data/lib/rack/query_parser.rb +7 -8
  42. data/lib/rack/recursive.rb +1 -1
  43. data/lib/rack/reloader.rb +1 -3
  44. data/lib/rack/request.rb +182 -76
  45. data/lib/rack/response.rb +62 -19
  46. data/lib/rack/rewindable_input.rb +0 -1
  47. data/lib/rack/runtime.rb +3 -3
  48. data/lib/rack/sendfile.rb +0 -3
  49. data/lib/rack/server.rb +9 -8
  50. data/lib/rack/session/abstract/id.rb +20 -18
  51. data/lib/rack/session/cookie.rb +2 -3
  52. data/lib/rack/session/pool.rb +1 -1
  53. data/lib/rack/show_exceptions.rb +2 -4
  54. data/lib/rack/show_status.rb +1 -3
  55. data/lib/rack/static.rb +13 -6
  56. data/lib/rack/tempfile_reaper.rb +0 -2
  57. data/lib/rack/urlmap.rb +1 -4
  58. data/lib/rack/utils.rb +58 -54
  59. data/lib/rack/version.rb +29 -0
  60. data/rack.gemspec +31 -29
  61. metadata +11 -12
@@ -0,0 +1,136 @@
1
+ Contributing to Rack
2
+ =====================
3
+
4
+ Rack is work of [hundreds of contributors](https://github.com/rack/rack/graphs/contributors). You're encouraged to submit [pull requests](https://github.com/rack/rack/pulls), [propose features and discuss issues](https://github.com/rack/rack/issues). When in doubt, post to the [rack-devel](http://groups.google.com/group/rack-devel) mailing list.
5
+
6
+ #### Fork the Project
7
+
8
+ Fork the [project on Github](https://github.com/rack/rack) and check out your copy.
9
+
10
+ ```
11
+ git clone https://github.com/contributor/rack.git
12
+ cd rack
13
+ git remote add upstream https://github.com/rack/rack.git
14
+ ```
15
+
16
+ #### Create a Topic Branch
17
+
18
+ Make sure your fork is up-to-date and create a topic branch for your feature or bug fix.
19
+
20
+ ```
21
+ git checkout master
22
+ git pull upstream master
23
+ git checkout -b my-feature-branch
24
+ ```
25
+
26
+ #### Bundle Install and Quick Test
27
+
28
+ Ensure that you can build the project and run quick tests.
29
+
30
+ ```
31
+ bundle install --without extra
32
+ bundle exec rake test
33
+ ```
34
+
35
+ #### Running All Tests
36
+
37
+ Install all dependencies.
38
+
39
+ ```
40
+ bundle install
41
+ ```
42
+
43
+ Run all tests.
44
+
45
+ ```
46
+ rake test
47
+ ```
48
+
49
+ The test suite has no dependencies outside of the core Ruby installation and bacon.
50
+
51
+ Some tests will be skipped if a dependency is not found.
52
+
53
+ To run the test suite completely, you need:
54
+
55
+ * fcgi
56
+ * dalli
57
+ * thin
58
+
59
+ To test Memcache sessions, you need memcached (will be run on port 11211) and dalli installed.
60
+
61
+ #### Write Tests
62
+
63
+ Try to write a test that reproduces the problem you're trying to fix or describes a feature that you want to build.
64
+
65
+ We definitely appreciate pull requests that highlight or reproduce a problem, even without a fix.
66
+
67
+ #### Write Code
68
+
69
+ Implement your feature or bug fix.
70
+
71
+ Make sure that `bundle exec rake fulltest` completes without errors.
72
+
73
+ #### Write Documentation
74
+
75
+ Document any external behavior in the [README](README.rdoc).
76
+
77
+ #### Update Changelog
78
+
79
+ Add a line to [CHANGELOG](CHANGELOG.md).
80
+
81
+ #### Commit Changes
82
+
83
+ Make sure git knows your name and email address:
84
+
85
+ ```
86
+ git config --global user.name "Your Name"
87
+ git config --global user.email "contributor@example.com"
88
+ ```
89
+
90
+ Writing good commit logs is important. A commit log should describe what changed and why.
91
+
92
+ ```
93
+ git add ...
94
+ git commit
95
+ ```
96
+
97
+ #### Push
98
+
99
+ ```
100
+ git push origin my-feature-branch
101
+ ```
102
+
103
+ #### Make a Pull Request
104
+
105
+ Go to https://github.com/contributor/rack and select your feature branch. Click the 'Pull Request' button and fill out the form. Pull requests are usually reviewed within a few days.
106
+
107
+ #### Rebase
108
+
109
+ If you've been working on a change for a while, rebase with upstream/master.
110
+
111
+ ```
112
+ git fetch upstream
113
+ git rebase upstream/master
114
+ git push origin my-feature-branch -f
115
+ ```
116
+
117
+ #### Make Required Changes
118
+
119
+ Amend your previous commit and force push the changes.
120
+
121
+ ```
122
+ git commit --amend
123
+ git push origin my-feature-branch -f
124
+ ```
125
+
126
+ #### Check on Your Pull Request
127
+
128
+ Go back to your pull request after a few minutes and see whether it passed muster with Travis-CI. Everything should look green, otherwise fix issues and amend your commit as described above.
129
+
130
+ #### Be Patient
131
+
132
+ It's likely that your change will not be merged and that the nitpicky maintainers will ask you to do more, or fix seemingly benign problems. Hang on there!
133
+
134
+ #### Thank You
135
+
136
+ Please do know that we really appreciate and value your time and work. We love you, really.
@@ -5,6 +5,7 @@
5
5
  {<img src="https://circleci.com/gh/rack/rack.svg?style=svg" alt="CircleCI" />}[https://circleci.com/gh/rack/rack]
6
6
  {<img src="https://badge.fury.io/rb/rack.svg" alt="Gem Version" />}[http://badge.fury.io/rb/rack]
7
7
  {<img src="https://api.dependabot.com/badges/compatibility_score?dependency-name=rack&package-manager=bundler&version-scheme=semver" alt="SemVer Stability" />}[https://dependabot.com/compatibility-score.html?dependency-name=rack&package-manager=bundler&version-scheme=semver]
8
+ {<img src="http://inch-ci.org/github/rack/rack.svg?branch=master" alt="Inline docs" />}[http://inch-ci.org/github/rack/rack]
8
9
 
9
10
  \Rack provides a minimal, modular, and adaptable interface for developing
10
11
  web applications in Ruby. By wrapping HTTP requests and responses in
@@ -30,10 +31,11 @@ These web servers include \Rack handlers in their distributions:
30
31
 
31
32
  * Agoo[https://github.com/ohler55/agoo]
32
33
  * Falcon[https://github.com/socketry/falcon]
34
+ * Iodine[https://github.com/boazsegev/iodine]
33
35
  * {NGINX Unit}[https://unit.nginx.org/]
34
36
  * {Phusion Passenger}[https://www.phusionpassenger.com/] (which is mod_rack for Apache and for nginx)
35
37
  * Puma[https://puma.io/]
36
- * Unicorn[https://bogomips.org/unicorn/]
38
+ * Unicorn[https://yhbt.net/unicorn/]
37
39
  * uWSGI[https://uwsgi-docs.readthedocs.io/en/latest/]
38
40
 
39
41
  Any valid \Rack app will run the same on all these handlers, without
@@ -41,13 +43,12 @@ changing anything.
41
43
 
42
44
  == Supported web frameworks
43
45
 
44
- These frameworks include \Rack adapters in their distributions:
46
+ These frameworks and many others support the \Rack API:
45
47
 
46
48
  * Camping[http://www.ruby-camping.com/]
47
49
  * Coset[http://leahneukirchen.org/repos/coset/]
48
50
  * Hanami[https://hanamirb.org/]
49
51
  * Padrino[http://padrinorb.com/]
50
- * Racktools::SimpleApplication
51
52
  * Ramaze[http://ramaze.net/]
52
53
  * Roda[https://github.com/jeremyevans/roda]
53
54
  * {Ruby on Rails}[https://rubyonrails.org/]
@@ -55,19 +56,45 @@ These frameworks include \Rack adapters in their distributions:
55
56
  * Sinatra[http://sinatrarb.com/]
56
57
  * Utopia[https://github.com/socketry/utopia]
57
58
  * WABuR[https://github.com/ohler55/wabur]
58
- * ... and many others.
59
59
 
60
- == Available middleware
60
+ == Available middleware shipped with \Rack
61
61
 
62
62
  Between the server and the framework, \Rack can be customized to your
63
- applications needs using middleware, for example:
63
+ applications needs using middleware. \Rack itself ships with the following
64
+ middleware:
64
65
 
65
- * Rack::URLMap, to route to multiple applications inside the same process.
66
+ * Rack::Chunked, for streaming responses using chunked encoding.
66
67
  * Rack::CommonLogger, for creating Apache-style logfiles.
68
+ * Rack::ConditionalGet, for returning not modified responses when the response
69
+ has not changed.
70
+ * Rack::Config, for modifying the environment before processing the request.
71
+ * Rack::ContentLength, for setting Content-Length header based on body size.
72
+ * Rack::ContentType, for setting default Content-Type header for responses.
73
+ * Rack::Deflater, for compressing responses with gzip.
74
+ * Rack::ETag, for setting ETag header on string bodies.
75
+ * Rack::Events, for providing easy hooks when a request is received
76
+ and when the response is sent.
77
+ * Rack::Files, for serving static files.
78
+ * Rack::Head, for returning an empty body for HEAD requests.
79
+ * Rack::Lint, for checking conformance to the \Rack API.
80
+ * Rack::Lock, for serializing requests using a mutex.
81
+ * Rack::Logger, for setting a logger to handle logging errors.
82
+ * Rack::MethodOverride, for modifying the request method based on a submitted
83
+ parameter.
84
+ * Rack::Recursive, for including data from other paths in the application,
85
+ and for performing internal redirects.
86
+ * Rack::Reloader, for reloading files if they have been modified.
87
+ * Rack::Runtime, for including a response header with the time taken to
88
+ process the request.
89
+ * Rack::Sendfile, for working with web servers that can use optimized
90
+ file serving for file system paths.
67
91
  * Rack::ShowException, for catching unhandled exceptions and
68
92
  presenting them in a nice and helpful way with clickable backtrace.
69
- * Rack::Files, for serving static files.
70
- * ...many others!
93
+ * Rack::ShowStatus, for using nice error pages for empty client error
94
+ responses.
95
+ * Rack::Static, for more configurable serving of static files.
96
+ * Rack::TempfileReaper, for removing temporary files creating during a
97
+ request.
71
98
 
72
99
  All these components use the same interface, which is described in
73
100
  detail in the \Rack specification. These optional components can be
@@ -86,6 +113,15 @@ over:
86
113
  cookie handling.
87
114
  * Rack::MockRequest and Rack::MockResponse for efficient and quick
88
115
  testing of \Rack application without real HTTP round-trips.
116
+ * Rack::Cascade, for trying additional \Rack applications if an
117
+ application returns a not found or method not supported response.
118
+ * Rack::Directory, for serving files under a given directory, with
119
+ directory indexes.
120
+ * Rack::MediaType, for parsing Content-Type headers.
121
+ * Rack::Mime, for determining Content-Type based on file extension.
122
+ * Rack::RewindableInput, for making any IO object rewindable, using
123
+ a temporary file buffer.
124
+ * Rack::URLMap, to route to multiple applications inside the same process.
89
125
 
90
126
  == rack-contrib
91
127
 
@@ -125,46 +161,46 @@ A Gem of \Rack is available at {rubygems.org}[https://rubygems.org/gems/rack]. Y
125
161
 
126
162
  gem install rack
127
163
 
128
- == Running the tests
164
+ == Usage
129
165
 
130
- Testing \Rack requires the bacon testing framework:
166
+ You should require the library:
131
167
 
132
- bundle install --without extra # to be able to run the fast tests
168
+ require 'rack'
133
169
 
134
- Or:
170
+ \Rack uses autoload to automatically load other files \Rack ships with on demand,
171
+ so you should not need require paths under +rack+. If you require paths under
172
+ +rack+ without requiring +rack+ itself, things may not work correctly.
135
173
 
136
- bundle install # this assumes that you have installed native extensions!
174
+ == Configuration
137
175
 
138
- There is a rake-based test task:
176
+ Several parameters can be modified on Rack::Utils to configure \Rack behaviour.
139
177
 
140
- rake test # tests all the tests
178
+ e.g:
141
179
 
142
- The testsuite has no dependencies outside of the core Ruby
143
- installation and bacon.
180
+ Rack::Utils.key_space_limit = 128
144
181
 
145
- To run the test suite completely, you need:
182
+ === key_space_limit
146
183
 
147
- * fcgi
148
- * dalli
149
- * thin
184
+ The default number of bytes to allow all parameters keys in a given parameter hash to take up.
185
+ Does not affect nested parameter hashes, so doesn't actually prevent an attacker from using
186
+ more than this many bytes for parameter keys.
150
187
 
151
- To test Memcache sessions, you need memcached (will be
152
- run on port 11211) and dalli installed.
188
+ Defaults to 65536 characters.
153
189
 
154
- == Configuration
190
+ === param_depth_limit
155
191
 
156
- Several parameters can be modified on Rack::Utils to configure \Rack behaviour.
192
+ The maximum amount of nesting allowed in parameters.
193
+ For example, if set to 3, this query string would be allowed:
157
194
 
158
- e.g:
195
+ ?a[b][c]=d
159
196
 
160
- Rack::Utils.key_space_limit = 128
197
+ but this query string would not be allowed:
161
198
 
162
- === key_space_limit
199
+ ?a[b][c][d]=e
163
200
 
164
- The default number of bytes to allow a single parameter key to take up.
165
- This helps prevent a rogue client from flooding a Request.
201
+ Limiting the depth prevents a possible stack overflow when parsing parameters.
166
202
 
167
- Default to 65536 characters (4 kiB in worst case).
203
+ Defaults to 100.
168
204
 
169
205
  === multipart_part_limit
170
206
 
@@ -181,6 +217,10 @@ Can also be set via the +RACK_MULTIPART_PART_LIMIT+ environment variable.
181
217
 
182
218
  See {CHANGELOG.md}[https://github.com/rack/rack/blob/master/CHANGELOG.md].
183
219
 
220
+ == Contributing
221
+
222
+ See {CONTRIBUTING.md}[https://github.com/rack/rack/blob/master/CONTRIBUTING.md].
223
+
184
224
  == Contact
185
225
 
186
226
  Please post bugs, suggestions and patches to
@@ -198,7 +238,6 @@ Mailing list archives are available at
198
238
  Git repository (send Git patches to the mailing list):
199
239
 
200
240
  * https://github.com/rack/rack
201
- * http://git.vuxu.org/cgi-bin/gitweb.cgi?p=rack-github.git
202
241
 
203
242
  You are also welcome to join the #rack channel on irc.freenode.net.
204
243
 
@@ -206,20 +245,25 @@ You are also welcome to join the #rack channel on irc.freenode.net.
206
245
 
207
246
  The \Rack Core Team, consisting of
208
247
 
248
+ * Aaron Patterson (tenderlove[https://github.com/tenderlove])
249
+ * Samuel Williams (ioquatix[https://github.com/ioquatix])
250
+ * Jeremy Evans (jeremyevans[https://github.com/jeremyevans])
251
+ * Eileen Uchitelle (eileencodes[https://github.com/eileencodes])
252
+ * Matthew Draper (matthewd[https://github.com/matthewd])
253
+ * Rafael França (rafaelfranca[https://github.com/rafaelfranca])
254
+
255
+ and the \Rack Alumni
256
+
257
+ * Ryan Tomayko (rtomayko[https://github.com/rtomayko])
258
+ * Scytrin dai Kinthra (scytrin[https://github.com/scytrin])
209
259
  * Leah Neukirchen (leahneukirchen[https://github.com/leahneukirchen])
210
260
  * James Tucker (raggi[https://github.com/raggi])
211
261
  * Josh Peek (josh[https://github.com/josh])
212
262
  * José Valim (josevalim[https://github.com/josevalim])
213
263
  * Michael Fellinger (manveru[https://github.com/manveru])
214
- * Aaron Patterson (tenderlove[https://github.com/tenderlove])
215
264
  * Santiago Pastorino (spastorino[https://github.com/spastorino])
216
265
  * Konstantin Haase (rkh[https://github.com/rkh])
217
266
 
218
- and the \Rack Alumnis
219
-
220
- * Ryan Tomayko (rtomayko[https://github.com/rtomayko])
221
- * Scytrin dai Kinthra (scytrin[https://github.com/scytrin])
222
-
223
267
  would like to thank:
224
268
 
225
269
  * Adrian Madrid, for the LiteSpeed handler.
data/Rakefile CHANGED
@@ -1,5 +1,6 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "bundler/gem_tasks"
3
4
  require "rake/testtask"
4
5
 
5
6
  desc "Run all the tests"
@@ -20,7 +21,7 @@ end
20
21
  desc "Make an archive as .tar.gz"
21
22
  task dist: %w[chmod changelog spec rdoc] do
22
23
  sh "git archive --format=tar --prefix=#{release}/ HEAD^{tree} >#{release}.tar"
23
- sh "pax -waf #{release}.tar -s ':^:#{release}/:' SPEC ChangeLog doc rack.gemspec"
24
+ sh "pax -waf #{release}.tar -s ':^:#{release}/:' SPEC.rdoc ChangeLog doc rack.gemspec"
24
25
  sh "gzip -f -9 #{release}.tar"
25
26
  end
26
27
 
@@ -38,7 +39,7 @@ task officialrelease_really: %w[spec dist gem] do
38
39
  end
39
40
 
40
41
  def release
41
- "rack-" + File.read('lib/rack.rb')[/RELEASE += +([\"\'])([\d][\w\.]+)\1/, 2]
42
+ "rack-" + File.read('lib/rack/version.rb')[/RELEASE += +([\"\'])([\d][\w\.]+)\1/, 2]
42
43
  end
43
44
 
44
45
  desc "Make binaries executable"
@@ -71,13 +72,13 @@ file "ChangeLog" => '.git/index' do
71
72
  end
72
73
 
73
74
  desc "Generate Rack Specification"
74
- task spec: "SPEC"
75
+ task spec: "SPEC.rdoc"
75
76
 
76
77
  file 'lib/rack/lint.rb'
77
- file "SPEC" => 'lib/rack/lint.rb' do
78
- File.open("SPEC", "wb") { |file|
78
+ file "SPEC.rdoc" => 'lib/rack/lint.rb' do
79
+ File.open("SPEC.rdoc", "wb") { |file|
79
80
  IO.foreach("lib/rack/lint.rb") { |line|
80
- if line =~ /## (.*)/
81
+ if line =~ /^\s*## ?(.*)/
81
82
  file.puts $1
82
83
  end
83
84
  }
@@ -91,6 +92,12 @@ Rake::TestTask.new("test:regular") do |t|
91
92
  t.verbose = true
92
93
  end
93
94
 
95
+ desc "Run tests with coverage"
96
+ task "test_cov" do
97
+ ENV['COVERAGE'] = '1'
98
+ Rake::Task['test:regular'].invoke
99
+ end
100
+
94
101
  desc "Run all the fast + platform agnostic tests"
95
102
  task test: %w[spec test:regular]
96
103
 
@@ -107,7 +114,7 @@ desc "Generate RDoc documentation"
107
114
  task rdoc: %w[changelog spec] do
108
115
  sh(*%w{rdoc --line-numbers --main README.rdoc
109
116
  --title 'Rack\ Documentation' --charset utf-8 -U -o doc} +
110
- %w{README.rdoc KNOWN-ISSUES SPEC ChangeLog} +
117
+ %w{README.rdoc KNOWN-ISSUES SPEC.rdoc ChangeLog} +
111
118
  `git ls-files lib/\*\*/\*.rb`.strip.split)
112
119
  cp "contrib/rdoc.css", "doc/rdoc.css"
113
120
  end
@@ -1,5 +1,6 @@
1
1
  This specification aims to formalize the Rack protocol. You
2
2
  can (and should) use Rack::Lint to enforce it.
3
+
3
4
  When you develop middleware, be sure to add a Lint before and
4
5
  after to catch all mistakes.
5
6
  = Rack applications
@@ -11,9 +12,10 @@ The *status*,
11
12
  the *headers*,
12
13
  and the *body*.
13
14
  == The Environment
14
- The environment must be an instance of Hash that includes
15
+ The environment must be an unfrozen instance of Hash that includes
15
16
  CGI-like headers. The application is free to modify the
16
17
  environment.
18
+
17
19
  The environment is required to include these variables
18
20
  (adopted from PEP333), except when they'd be empty, but see
19
21
  below.
@@ -104,6 +106,7 @@ be implemented by the server.
104
106
  fetch(key, default = nil) (aliased as []);
105
107
  delete(key);
106
108
  clear;
109
+ to_hash (returning unfrozen Hash instance);
107
110
  <tt>rack.logger</tt>:: A common object interface for logging messages.
108
111
  The object must implement:
109
112
  info(message, &block)
@@ -118,10 +121,13 @@ environment, too. The keys must contain at least one dot,
118
121
  and should be prefixed uniquely. The prefix <tt>rack.</tt>
119
122
  is reserved for use with the Rack core distribution and other
120
123
  accepted specifications and must not be used otherwise.
124
+
121
125
  The environment must not contain the keys
122
126
  <tt>HTTP_CONTENT_TYPE</tt> or <tt>HTTP_CONTENT_LENGTH</tt>
123
127
  (use the versions without <tt>HTTP_</tt>).
124
128
  The CGI keys (named without a period) must have String values.
129
+ If the string values for CGI keys contain non-ASCII characters,
130
+ they should use ASCII-8BIT encoding.
125
131
  There are the following restrictions:
126
132
  * <tt>rack.version</tt> must be an array of Integers.
127
133
  * <tt>rack.url_scheme</tt> must either be +http+ or +https+.
@@ -137,6 +143,7 @@ There are the following restrictions:
137
143
  <tt>SCRIPT_NAME</tt> is empty.
138
144
  <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
139
145
  === The Input Stream
146
+
140
147
  The input stream is an IO-like object which contains the raw HTTP
141
148
  POST data.
142
149
  When applicable, its external encoding must be "ASCII-8BIT" and it
@@ -146,14 +153,19 @@ The input stream must respond to +gets+, +each+, +read+ and +rewind+.
146
153
  or +nil+ on EOF.
147
154
  * +read+ behaves like IO#read.
148
155
  Its signature is <tt>read([length, [buffer]])</tt>.
156
+
149
157
  If given, +length+ must be a non-negative Integer (>= 0) or +nil+,
150
158
  and +buffer+ must be a String and may not be nil.
159
+
151
160
  If +length+ is given and not nil, then this method reads at most
152
161
  +length+ bytes from the input stream.
162
+
153
163
  If +length+ is not given or nil, then this method reads
154
164
  all data until EOF.
165
+
155
166
  When EOF is reached, this method returns nil if +length+ is given
156
167
  and not nil, or "" if +length+ is not given or is nil.
168
+
157
169
  If +buffer+ is given, then the read data will be placed
158
170
  into +buffer+ instead of a newly created String object.
159
171
  * +each+ must be called without arguments and only yield Strings.
@@ -175,16 +187,20 @@ The error stream must respond to +puts+, +write+ and +flush+.
175
187
  If rack.hijack? is true then rack.hijack must respond to #call.
176
188
  rack.hijack must return the io that will also be assigned (or is
177
189
  already present, in rack.hijack_io.
190
+
178
191
  rack.hijack_io must respond to:
179
192
  <tt>read, write, read_nonblock, write_nonblock, flush, close,
180
193
  close_read, close_write, closed?</tt>
194
+
181
195
  The semantics of these IO methods must be a best effort match to
182
196
  those of a normal ruby IO or Socket object, using standard
183
197
  arguments and raising standard exceptions. Servers are encouraged
184
198
  to simply pass on real IO objects, although it is recognized that
185
199
  this approach is not directly compatible with SPDY and HTTP 2.0.
200
+
186
201
  IO provided in rack.hijack_io should preference the
187
202
  IO::WaitReadable and IO::WaitWritable APIs wherever supported.
203
+
188
204
  There is a deliberate lack of full specification around
189
205
  rack.hijack_io, as semantics will change from server to server.
190
206
  Users are encouraged to utilize this API with a knowledge of their
@@ -192,7 +208,9 @@ server choice, and servers may extend the functionality of
192
208
  hijack_io to provide additional features to users. The purpose of
193
209
  rack.hijack is for Rack to "get out of the way", as such, Rack only
194
210
  provides the minimum of specification and support.
211
+
195
212
  If rack.hijack? is false, then rack.hijack should not be set.
213
+
196
214
  If rack.hijack? is false, then rack.hijack_io should not be set.
197
215
  ==== Response (after headers)
198
216
  It is also possible to hijack a response after the status and headers
@@ -201,6 +219,7 @@ In order to do this, an application may set the special header
201
219
  <tt>rack.hijack</tt> to an object that responds to <tt>call</tt>
202
220
  accepting an argument that conforms to the <tt>rack.hijack_io</tt>
203
221
  protocol.
222
+
204
223
  After the headers have been sent, and this hijack callback has been
205
224
  called, the application is now responsible for the remaining lifecycle
206
225
  of the IO. The application is also responsible for maintaining HTTP
@@ -209,8 +228,10 @@ applications will have wanted to specify the header Connection:close in
209
228
  HTTP/1.1, and not Connection:keep-alive, as there is no protocol for
210
229
  returning hijacked sockets to the web server. For that purpose, use the
211
230
  body streaming API instead (progressively yielding strings via each).
231
+
212
232
  Servers must ignore the <tt>body</tt> part of the response tuple when
213
233
  the <tt>rack.hijack</tt> response API is in use.
234
+
214
235
  The special response header <tt>rack.hijack</tt> must only be set
215
236
  if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
216
237
  ==== Conventions
@@ -244,16 +265,20 @@ There must not be a Content-Length header when the
244
265
  === The Body
245
266
  The Body must respond to +each+
246
267
  and must only yield String values.
268
+
247
269
  The Body itself should not be an instance of String, as this will
248
270
  break in Ruby 1.9.
271
+
249
272
  If the Body responds to +close+, it will be called after iteration. If
250
273
  the body is replaced by a middleware after action, the original body
251
274
  must be closed first, if it responds to close.
275
+
252
276
  If the Body responds to +to_path+, it must return a String
253
277
  identifying the location of a file whose contents are identical
254
278
  to that produced by calling +each+; this may be used by the
255
279
  server as an alternative, possibly more efficient way to
256
280
  transport the response.
281
+
257
282
  The Body commonly is an Array of Strings, the application
258
283
  instance itself, or a File-like object.
259
284
  == Thanks