rack 2.0.9.3 → 3.0.0

data/README.rdoc

@@ -1,316 +0,0 @@
-= Rack, a modular Ruby webserver interface {<img src="https://secure.travis-ci.org/rack/rack.svg" alt="Build Status" />}[http://travis-ci.org/rack/rack] {<img src="https://gemnasium.com/rack/rack.svg" alt="Dependency Status" />}[https://gemnasium.com/rack/rack]
-
-Rack provides a minimal, modular, and adaptable interface for developing
-web applications in Ruby.  By wrapping HTTP requests and responses in
-the simplest way possible, it unifies and distills the API for web
-servers, web frameworks, and software in between (the so-called
-middleware) into a single method call.
-
-The exact details of this are described in the Rack specification,
-which all Rack applications should conform to.
-
-== Supported web servers
-
-The included *handlers* connect all kinds of web servers to Rack:
-* WEBrick
-* FCGI
-* CGI
-* SCGI
-* LiteSpeed
-* Thin
-
-These web servers include Rack handlers in their distributions:
-* Ebb
-* Fuzed
-* Glassfish v3
-* Phusion Passenger (which is mod_rack for Apache and for nginx)
-* Puma
-* Reel
-* Unicorn
-* unixrack
-* uWSGI
-* yahns
-
-Any valid Rack app will run the same on all these handlers, without
-changing anything.
-
-== Supported web frameworks
-
-These frameworks include Rack adapters in their distributions:
-* Camping
-* Coset
-* Espresso
-* Halcyon
-* Mack
-* Maveric
-* Merb
-* Racktools::SimpleApplication
-* Ramaze
-* Ruby on Rails
-* Rum
-* Sinatra
-* Sin
-* Vintage
-* Waves
-* Wee
-* ... and many others.
-
-== Available middleware
-
-Between the server and the framework, Rack can be customized to your
-applications needs using middleware, for example:
-* Rack::URLMap, to route to multiple applications inside the same process.
-* Rack::CommonLogger, for creating Apache-style logfiles.
-* Rack::ShowException, for catching unhandled exceptions and
-  presenting them in a nice and helpful way with clickable backtrace.
-* Rack::File, for serving static files.
-* ...many others!
-
-All these components use the same interface, which is described in
-detail in the Rack specification.  These optional components can be
-used in any way you wish.
-
-== Convenience
-
-If you want to develop outside of existing frameworks, implement your
-own ones, or develop middleware, Rack provides many helpers to create
-Rack applications quickly and without doing the same web stuff all
-over:
-* Rack::Request, which also provides query string parsing and
-  multipart handling.
-* Rack::Response, for convenient generation of HTTP replies and
-  cookie handling.
-* Rack::MockRequest and Rack::MockResponse for efficient and quick
-  testing of Rack application without real HTTP round-trips.
-
-== rack-contrib
-
-The plethora of useful middleware created the need for a project that
-collects fresh Rack middleware.  rack-contrib includes a variety of
-add-on components for Rack and it is easy to contribute new modules.
-
-* https://github.com/rack/rack-contrib
-
-== rackup
-
-rackup is a useful tool for running Rack applications, which uses the
-Rack::Builder DSL to configure middleware and build up applications
-easily.
-
-rackup automatically figures out the environment it is run in, and
-runs your application as FastCGI, CGI, or WEBrick---all from the
-same configuration.
-
-== Quick start
-
-Try the lobster!
-
-Either with the embedded WEBrick starter:
-
-    ruby -Ilib lib/rack/lobster.rb
-
-Or with rackup:
-
-    bin/rackup -Ilib example/lobster.ru
-
-By default, the lobster is found at http://localhost:9292.
-
-== Installing with RubyGems
-
-A Gem of Rack is available at rubygems.org.  You can install it with:
-
-    gem install rack
-
-I also provide a local mirror of the gems (and development snapshots)
-at my site:
-
-    gem install rack --source http://chneukirchen.org/releases/gems/
-
-== Running the tests
-
-Testing Rack requires the bacon testing framework:
-
-    bundle install --without extra # to be able to run the fast tests
-
-Or:
-
-    bundle install # this assumes that you have installed native extensions!
-
-There is a rake-based test task:
-
-    rake test       tests all the tests
-
-The testsuite has no dependencies outside of the core Ruby
-installation and bacon.
-
-To run the test suite completely, you need:
-
-  * fcgi
-  * memcache-client
-  * thin
-
-The full set of tests test FCGI access with lighttpd (on port
-9203) so you will need lighttpd installed as well as the FCGI
-libraries and the fcgi gem:
-
-Download and install lighttpd:
-
-    http://www.lighttpd.net/download
-
-Installing the FCGI libraries:
-
-    curl -O http://www.fastcgi.com/dist/fcgi-2.4.0.tar.gz
-    tar xzvf fcgi-2.4.0.tar.gz
-    cd fcgi-2.4.0
-    ./configure --prefix=/usr/local
-    make
-    sudo make install
-    cd ..
-
-Installing the Ruby fcgi gem:
-
-    gem install fcgi
-
-Furthermore, to test Memcache sessions, you need memcached (will be
-run on port 11211) and memcache-client installed.
-
-== Configuration
-
-Several parameters can be modified on Rack::Utils to configure Rack behaviour.
-
-e.g:
-
-    Rack::Utils.key_space_limit = 128
-
-=== key_space_limit
-
-The default number of bytes to allow a single parameter key to take up.
-This helps prevent a rogue client from flooding a Request.
-
-Default to 65536 characters (4 kiB in worst case).
-
-=== multipart_file_limit
-
-The maximum number of parts with a filename a request can contain.
-Accepting too many part can lead to the server running out of file handles.
-
-The default is 128, which means that a single request can't upload more than 128 files at once.
-
-Set to 0 for no limit.
-
-Can also be set via the +RACK_MULTIPART_FILE_LIMIT+ environment variable.
-
-(This is also aliased as +multipart_part_limit+ and +RACK_MULTIPART_PART_LIMIT+ for compatibility)
-
-=== multipart_total_part_limit
-
-The maximum total number of parts a request can contain of any type, including
-both file and non-file form fields.
-
-The default is 4096, which means that a single request can't contain more than
-4096 parts.
-
-Set to 0 for no limit.
-
-Can also be set via the +RACK_MULTIPART_TOTAL_PART_LIMIT+ environment variable.
-
-== History
-
-See <https://github.com/rack/rack/blob/master/HISTORY.md>.
-
-== Contact
-
-Please post bugs, suggestions and patches to
-the bug tracker at <https://github.com/rack/rack/issues>.
-
-Please post security related bugs and suggestions to the core team at
-<https://groups.google.com/group/rack-core> or rack-core@googlegroups.com. This
-list is not public. Due to wide usage of the library, it is strongly preferred
-that we manage timing in order to provide viable patches at the time of
-disclosure. Your assistance in this matter is greatly appreciated.
-
-Mailing list archives are available at
-<https://groups.google.com/group/rack-devel>.
-
-Git repository (send Git patches to the mailing list):
-* https://github.com/rack/rack
-* http://git.vuxu.org/cgi-bin/gitweb.cgi?p=rack-github.git
-
-You are also welcome to join the #rack channel on irc.freenode.net.
-
-== Thanks
-
-The Rack Core Team, consisting of
-
-* Leah Neukirchen (chneukirchen[https://github.com/chneukirchen])
-* James Tucker (raggi[https://github.com/raggi])
-* Josh Peek (josh[https://github.com/josh])
-* José Valim (josevalim[https://github.com/josevalim])
-* Michael Fellinger (manveru[https://github.com/manveru])
-* Aaron Patterson (tenderlove[https://github.com/tenderlove])
-* Santiago Pastorino (spastorino[https://github.com/spastorino])
-* Konstantin Haase (rkh[https://github.com/rkh])
-
-and the Rack Alumnis
-
-* Ryan Tomayko (rtomayko[https://github.com/rtomayko])
-* Scytrin dai Kinthra (scytrin[https://github.com/scytrin])
-
-would like to thank:
-
-* Adrian Madrid, for the LiteSpeed handler.
-* Christoffer Sawicki, for the first Rails adapter and Rack::Deflater.
-* Tim Fletcher, for the HTTP authentication code.
-* Luc Heinrich for the Cookie sessions, the static file handler and bugfixes.
-* Armin Ronacher, for the logo and racktools.
-* Alex Beregszaszi, Alexander Kahn, Anil Wadghule, Aredridel, Ben
-  Alpert, Dan Kubb, Daniel Roethlisberger, Matt Todd, Tom Robinson,
-  Phil Hagelberg, S. Brent Faulkner, Bosko Milekic, Daniel Rodríguez
-  Troitiño, Genki Takiuchi, Geoffrey Grosenbach, Julien Sanchez, Kamal
-  Fariz Mahyuddin, Masayoshi Takahashi, Patrick Aljordm, Mig, Kazuhiro
-  Nishiyama, Jon Bardin, Konstantin Haase, Larry Siden, Matias
-  Korhonen, Sam Ruby, Simon Chiang, Tim Connor, Timur Batyrshin, and
-  Zach Brock for bug fixing and other improvements.
-* Eric Wong, Hongli Lai, Jeremy Kemper for their continuous support
-  and API improvements.
-* Yehuda Katz and Carl Lerche for refactoring rackup.
-* Brian Candler, for Rack::ContentType.
-* Graham Batty, for improved handler loading.
-* Stephen Bannasch, for bug reports and documentation.
-* Gary Wright, for proposing a better Rack::Response interface.
-* Jonathan Buch, for improvements regarding Rack::Response.
-* Armin Röhrl, for tracking down bugs in the Cookie generator.
-* Alexander Kellett for testing the Gem and reviewing the announcement.
-* Marcus Rückert, for help with configuring and debugging lighttpd.
-* The WSGI team for the well-done and documented work they've done and
-  Rack builds up on.
-* All bug reporters and patch contributors not mentioned above.
-
-== Copyright
-
-Copyright (C) 2007, 2008, 2009, 2010 Christian Neukirchen <http://purl.org/net/chneukirchen>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to
-deal in the Software without restriction, including without limitation the
-rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-sell copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
-THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
-IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-== Links
-
-Rack:: <https://rack.github.io/>
-Official Rack repositories:: <https://github.com/rack>
-Rack Bug Tracking:: <https://github.com/rack/rack/issues>
-rack-devel mailing list:: <https://groups.google.com/group/rack-devel>
-Rack's Rubyforge project:: <http://rubyforge.org/projects/rack>

data/Rakefile

@@ -1,116 +0,0 @@
-# Rakefile for Rack.  -*-ruby-*-
-
-desc "Run all the tests"
-task :default => [:test]
-
-desc "Install gem dependencies"
-task :deps do
-  require 'rubygems'
-  spec = Gem::Specification.load('rack.gemspec')
-  spec.dependencies.each do |dep|
-    reqs = dep.requirements_list
-    reqs = (["-v"] * reqs.size).zip(reqs).flatten
-    # Use system over sh, because we want to ignore errors!
-    system Gem.ruby, "-S", "gem", "install", '--conservative', dep.name, *reqs
-  end
-end
-
-desc "Make an archive as .tar.gz"
-task :dist => %w[chmod ChangeLog SPEC rdoc] do
-  sh "git archive --format=tar --prefix=#{release}/ HEAD^{tree} >#{release}.tar"
-  sh "pax -waf #{release}.tar -s ':^:#{release}/:' SPEC ChangeLog doc rack.gemspec"
-  sh "gzip -f -9 #{release}.tar"
-end
-
-desc "Make an official release"
-task :officialrelease do
-  puts "Official build for #{release}..."
-  sh "rm -rf stage"
-  sh "git clone --shared . stage"
-  sh "cd stage && rake officialrelease_really"
-  sh "mv stage/#{release}.tar.gz stage/#{release}.gem ."
-end
-
-task :officialrelease_really => %w[SPEC dist gem] do
-  sh "shasum #{release}.tar.gz #{release}.gem"
-end
-
-def release
-  "rack-" + File.read('lib/rack.rb')[/RELEASE += +([\"\'])([\d][\w\.]+)\1/, 2]
-end
-
-desc "Make binaries executable"
-task :chmod do
-  Dir["bin/*"].each { |binary| File.chmod(0755, binary) }
-  Dir["test/cgi/test*"].each { |binary| File.chmod(0755, binary) }
-end
-
-desc "Generate a ChangeLog"
-task :changelog => %w[ChangeLog]
-
-file '.git/index'
-file "ChangeLog" => '.git/index' do
-  File.open("ChangeLog", "w") { |out|
-    log = `git log -z`
-    log.force_encoding(Encoding::BINARY)
-    log.split("\0").map { |chunk|
-      author = chunk[/Author: (.*)/, 1].strip
-      date = chunk[/Date: (.*)/, 1].strip
-      desc, detail = $'.strip.split("\n", 2)
-      detail ||= ""
-      detail = detail.gsub(/.*darcs-hash:.*/, '')
-      detail.rstrip!
-      out.puts "#{date}  #{author}"
-      out.puts "  * #{desc.strip}"
-      out.puts detail  unless detail.empty?
-      out.puts
-    }
-  }
-end
-
-file 'lib/rack/lint.rb'
-desc "Generate Rack Specification"
-file "SPEC" => 'lib/rack/lint.rb' do
-  File.open("SPEC", "wb") { |file|
-    IO.foreach("lib/rack/lint.rb") { |line|
-      if line =~ /## (.*)/
-        file.puts $1
-      end
-    }
-  }
-end
-
-desc "Run all the fast + platform agnostic tests"
-task :test => 'SPEC' do
-  opts     = ENV['TEST'] || ''
-  specopts = ENV['TESTOPTS']
-
-  sh "ruby -I./lib:./test -S minitest #{opts} #{specopts} test/gemloader.rb test/spec*.rb"
-end
-
-desc "Run all the tests we run on CI"
-task :ci => :test
-
-task :gem => ["SPEC"] do
-  sh "gem build rack.gemspec"
-end
-
-task :doc => :rdoc
-desc "Generate RDoc documentation"
-task :rdoc => %w[ChangeLog SPEC] do
-  sh(*%w{rdoc --line-numbers --main README.rdoc
-              --title 'Rack\ Documentation' --charset utf-8 -U -o doc} +
-              %w{README.rdoc KNOWN-ISSUES SPEC ChangeLog} +
-              `git ls-files lib/\*\*/\*.rb`.strip.split)
-  cp "contrib/rdoc.css", "doc/rdoc.css"
-end
-
-task :pushdoc => %w[rdoc] do
-  sh "rsync -avz doc/ rack.rubyforge.org:/var/www/gforge-projects/rack/doc/"
-end
-
-task :pushsite => %w[pushdoc] do
-  sh "cd site && git gc"
-  sh "rsync -avz site/ rack.rubyforge.org:/var/www/gforge-projects/rack/"
-  sh "cd site && git push"
-end

data/SPEC

@@ -1,263 +0,0 @@
-This specification aims to formalize the Rack protocol.  You
-can (and should) use Rack::Lint to enforce it.
-When you develop middleware, be sure to add a Lint before and
-after to catch all mistakes.
-= Rack applications
-A Rack application is a Ruby object (not a class) that
-responds to +call+.
-It takes exactly one argument, the *environment*
-and returns an Array of exactly three values:
-The *status*,
-the *headers*,
-and the *body*.
-== The Environment
-The environment must be an instance of Hash that includes
-CGI-like headers.  The application is free to modify the
-environment.
-The environment is required to include these variables
-(adopted from PEP333), except when they'd be empty, but see
-below.
-<tt>REQUEST_METHOD</tt>:: The HTTP request method, such as
-                          "GET" or "POST". This cannot ever
-                          be an empty string, and so is
-                          always required.
-<tt>SCRIPT_NAME</tt>:: The initial portion of the request
-                       URL's "path" that corresponds to the
-                       application object, so that the
-                       application knows its virtual
-                       "location". This may be an empty
-                       string, if the application corresponds
-                       to the "root" of the server.
-<tt>PATH_INFO</tt>:: The remainder of the request URL's
-                     "path", designating the virtual
-                     "location" of the request's target
-                     within the application. This may be an
-                     empty string, if the request URL targets
-                     the application root and does not have a
-                     trailing slash. This value may be
-                     percent-encoded when originating from
-                     a URL.
-<tt>QUERY_STRING</tt>:: The portion of the request URL that
-                        follows the <tt>?</tt>, if any. May be
-                        empty, but is always required!
-<tt>SERVER_NAME</tt>, <tt>SERVER_PORT</tt>::
-                       When combined with <tt>SCRIPT_NAME</tt> and
-                       <tt>PATH_INFO</tt>, these variables can be
-                       used to complete the URL. Note, however,
-                       that <tt>HTTP_HOST</tt>, if present,
-                       should be used in preference to
-                       <tt>SERVER_NAME</tt> for reconstructing
-                       the request URL.
-                       <tt>SERVER_NAME</tt> and <tt>SERVER_PORT</tt>
-                       can never be empty strings, and so
-                       are always required.
-<tt>HTTP_</tt> Variables:: Variables corresponding to the
-                           client-supplied HTTP request
-                           headers (i.e., variables whose
-                           names begin with <tt>HTTP_</tt>). The
-                           presence or absence of these
-                           variables should correspond with
-                           the presence or absence of the
-                           appropriate HTTP header in the
-                           request. See
-                           {https://tools.ietf.org/html/rfc3875#section-4.1.18
-                           RFC3875 section 4.1.18} for
-                           specific behavior.
-In addition to this, the Rack environment must include these
-Rack-specific variables:
-<tt>rack.version</tt>:: The Array representing this version of Rack
-                        See Rack::VERSION, that corresponds to
-                        the version of this SPEC.
-<tt>rack.url_scheme</tt>:: +http+ or +https+, depending on the
-                           request URL.
-<tt>rack.input</tt>:: See below, the input stream.
-<tt>rack.errors</tt>:: See below, the error stream.
-<tt>rack.multithread</tt>:: true if the application object may be
-                            simultaneously invoked by another thread
-                            in the same process, false otherwise.
-<tt>rack.multiprocess</tt>:: true if an equivalent application object
-                             may be simultaneously invoked by another
-                             process, false otherwise.
-<tt>rack.run_once</tt>:: true if the server expects
-                         (but does not guarantee!) that the
-                         application will only be invoked this one
-                         time during the life of its containing
-                         process. Normally, this will only be true
-                         for a server based on CGI
-                         (or something similar).
-<tt>rack.hijack?</tt>:: present and true if the server supports
-                        connection hijacking. See below, hijacking.
-<tt>rack.hijack</tt>:: an object responding to #call that must be
-                       called at least once before using
-                       rack.hijack_io.
-                       It is recommended #call return rack.hijack_io
-                       as well as setting it in env if necessary.
-<tt>rack.hijack_io</tt>:: if rack.hijack? is true, and rack.hijack
-                          has received #call, this will contain
-                          an object resembling an IO. See hijacking.
-Additional environment specifications have approved to
-standardized middleware APIs.  None of these are required to
-be implemented by the server.
-<tt>rack.session</tt>:: A hash like interface for storing request session data.
-                        The store must implement:
-                         store(key, value)         (aliased as []=);
-                         fetch(key, default = nil) (aliased as []);
-                         delete(key);
-                         clear;
-<tt>rack.logger</tt>:: A common object interface for logging messages.
-                       The object must implement:
-                        info(message, &block)
-                        debug(message, &block)
-                        warn(message, &block)
-                        error(message, &block)
-                        fatal(message, &block)
-<tt>rack.multipart.buffer_size</tt>:: An Integer hint to the multipart parser as to what chunk size to use for reads and writes.
-<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.
-The server or the application can store their own data in the
-environment, too.  The keys must contain at least one dot,
-and should be prefixed uniquely.  The prefix <tt>rack.</tt>
-is reserved for use with the Rack core distribution and other
-accepted specifications and must not be used otherwise.
-The environment must not contain the keys
-<tt>HTTP_CONTENT_TYPE</tt> or <tt>HTTP_CONTENT_LENGTH</tt>
-(use the versions without <tt>HTTP_</tt>).
-The CGI keys (named without a period) must have String values.
-There are the following restrictions:
-* <tt>rack.version</tt> must be an array of Integers.
-* <tt>rack.url_scheme</tt> must either be +http+ or +https+.
-* There must be a valid input stream in <tt>rack.input</tt>.
-* There must be a valid error stream in <tt>rack.errors</tt>.
-* There may be a valid hijack stream in <tt>rack.hijack_io</tt>
-* The <tt>REQUEST_METHOD</tt> must be a valid token.
-* The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
-* The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
-* The <tt>CONTENT_LENGTH</tt>, if given, must consist of digits only.
-* One of <tt>SCRIPT_NAME</tt> or <tt>PATH_INFO</tt> must be
-  set.  <tt>PATH_INFO</tt> should be <tt>/</tt> if
-  <tt>SCRIPT_NAME</tt> is empty.
-  <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
-=== The Input Stream
-The input stream is an IO-like object which contains the raw HTTP
-POST data.
-When applicable, its external encoding must be "ASCII-8BIT" and it
-must be opened in binary mode, for Ruby 1.9 compatibility.
-The input stream must respond to +gets+, +each+, +read+ and +rewind+.
-* +gets+ must be called without arguments and return a string,
-  or +nil+ on EOF.
-* +read+ behaves like IO#read.
-  Its signature is <tt>read([length, [buffer]])</tt>.
-  If given, +length+ must be a non-negative Integer (>= 0) or +nil+,
-  and +buffer+ must be a String and may not be nil.
-  If +length+ is given and not nil, then this method reads at most
-  +length+ bytes from the input stream.
-  If +length+ is not given or nil, then this method reads
-  all data until EOF.
-  When EOF is reached, this method returns nil if +length+ is given
-  and not nil, or "" if +length+ is not given or is nil.
-  If +buffer+ is given, then the read data will be placed
-  into +buffer+ instead of a newly created String object.
-* +each+ must be called without arguments and only yield Strings.
-* +rewind+ must be called without arguments. It rewinds the input
-  stream back to the beginning. It must not raise Errno::ESPIPE:
-  that is, it may not be a pipe or a socket. Therefore, handler
-  developers must buffer the input data into some rewindable object
-  if the underlying input stream is not rewindable.
-* +close+ must never be called on the input stream.
-=== The Error Stream
-The error stream must respond to +puts+, +write+ and +flush+.
-* +puts+ must be called with a single argument that responds to +to_s+.
-* +write+ must be called with a single argument that is a String.
-* +flush+ must be called without arguments and must be called
-  in order to make the error appear for sure.
-* +close+ must never be called on the error stream.
-=== Hijacking
-==== Request (before status)
-If rack.hijack? is true then rack.hijack must respond to #call.
-rack.hijack must return the io that will also be assigned (or is
-already present, in rack.hijack_io.
-rack.hijack_io must respond to:
-<tt>read, write, read_nonblock, write_nonblock, flush, close,
-close_read, close_write, closed?</tt>
-The semantics of these IO methods must be a best effort match to
-those of a normal ruby IO or Socket object, using standard
-arguments and raising standard exceptions. Servers are encouraged
-to simply pass on real IO objects, although it is recognized that
-this approach is not directly compatible with SPDY and HTTP 2.0.
-IO provided in rack.hijack_io should preference the
-IO::WaitReadable and IO::WaitWritable APIs wherever supported.
-There is a deliberate lack of full specification around
-rack.hijack_io, as semantics will change from server to server.
-Users are encouraged to utilize this API with a knowledge of their
-server choice, and servers may extend the functionality of
-hijack_io to provide additional features to users. The purpose of
-rack.hijack is for Rack to "get out of the way", as such, Rack only
-provides the minimum of specification and support.
-If rack.hijack? is false, then rack.hijack should not be set.
-If rack.hijack? is false, then rack.hijack_io should not be set.
-==== Response (after headers)
-It is also possible to hijack a response after the status and headers
-have been sent.
-In order to do this, an application may set the special header
-<tt>rack.hijack</tt> to an object that responds to <tt>call</tt>
-accepting an argument that conforms to the <tt>rack.hijack_io</tt>
-protocol.
-After the headers have been sent, and this hijack callback has been
-called, the application is now responsible for the remaining lifecycle
-of the IO. The application is also responsible for maintaining HTTP
-semantics. Of specific note, in almost all cases in the current SPEC,
-applications will have wanted to specify the header Connection:close in
-HTTP/1.1, and not Connection:keep-alive, as there is no protocol for
-returning hijacked sockets to the web server. For that purpose, use the
-body streaming API instead (progressively yielding strings via each).
-Servers must ignore the <tt>body</tt> part of the response tuple when
-the <tt>rack.hijack</tt> response API is in use.
-The special response header <tt>rack.hijack</tt> must only be set
-if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
-==== Conventions
-* Middleware should not use hijack unless it is handling the whole
-  response.
-* Middleware may wrap the IO object for the response pattern.
-* Middleware should not wrap the IO object for the request pattern. The
-  request pattern is intended to provide the hijacker with "raw tcp".
-== The Response
-=== The Status
-This is an HTTP status. When parsed as integer (+to_i+), it must be
-greater than or equal to 100.
-=== The Headers
-The header must respond to +each+, and yield values of key and value.
-Special headers starting "rack." are for communicating with the
-server, and must not be sent back to the client.
-The header keys must be Strings.
-The header must not contain a +Status+ key.
-The header must conform to RFC7230 token specification, i.e. cannot
-contain non-printable ASCII, DQUOTE or "(),/:;<=>?@[\]{}".
-The values of the header must be Strings,
-consisting of lines (for multiple header values, e.g. multiple
-<tt>Set-Cookie</tt> values) separated by "\\n".
-The lines must not contain characters below 037.
-=== The Content-Type
-There must not be a <tt>Content-Type</tt>, when the +Status+ is 1xx,
-204 or 304.
-=== The Content-Length
-There must not be a <tt>Content-Length</tt> header when the
-+Status+ is 1xx, 204 or 304.
-=== The Body
-The Body must respond to +each+
-and must only yield String values.
-The Body itself should not be an instance of String, as this will
-break in Ruby 1.9.
-If the Body responds to +close+, it will be called after iteration. If
-the body is replaced by a middleware after action, the original body
-must be closed first, if it responds to close.
-If the Body responds to +to_path+, it must return a String
-identifying the location of a file whose contents are identical
-to that produced by calling +each+; this may be used by the
-server as an alternative, possibly more efficient way to
-transport the response.
-The Body commonly is an Array of Strings, the application
-instance itself, or a File-like object.
-== Thanks
-Some parts of this specification are adopted from PEP333: Python
-Web Server Gateway Interface
-v1.0 (http://www.python.org/dev/peps/pep-0333/). I'd like to thank
-everyone involved in that effort.