tdiary 5.2.2 → 5.2.3

data/vendor/bundle/ruby/3.1.0/gems/rack-2.2.4/lib/rack/lint.rb

@@ -0,0 +1,806 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+
+module Rack
+  # Rack::Lint validates your application and the requests and
+  # responses according to the Rack spec.
+
+  class Lint
+    def initialize(app)
+      @app = app
+      @content_length = nil
+    end
+
+    # :stopdoc:
+
+    class LintError < RuntimeError; end
+    module Assertion
+      def assert(message)
+        unless yield
+          raise LintError, message
+        end
+      end
+    end
+    include Assertion
+
+    ## 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+.
+    def call(env = nil)
+      dup._call(env)
+    end
+
+    def _call(env)
+      ## It takes exactly one argument, the *environment*
+      assert("No env given") { env }
+      check_env env
+
+      env[RACK_INPUT] = InputWrapper.new(env[RACK_INPUT])
+      env[RACK_ERRORS] = ErrorWrapper.new(env[RACK_ERRORS])
+
+      ## and returns an Array of exactly three values:
+      ary = @app.call(env)
+      assert("response is not an Array, but #{ary.class}") {
+        ary.kind_of? Array
+      }
+      assert("response array has #{ary.size} elements instead of 3") {
+        ary.size == 3
+      }
+
+      status, headers, @body = ary
+      ## The *status*,
+      check_status status
+      ## the *headers*,
+      check_headers headers
+
+      hijack_proc = check_hijack_response headers, env
+      if hijack_proc && headers.is_a?(Hash)
+        headers[RACK_HIJACK] = hijack_proc
+      end
+
+      ## and the *body*.
+      check_content_type status, headers
+      check_content_length status, headers
+      @head_request = env[REQUEST_METHOD] == HEAD
+      [status, headers, self]
+    end
+
+    ## == The Environment
+    def check_env(env)
+      ## The environment must be an unfrozen instance of Hash that includes
+      ## CGI-like headers.  The application is free to modify the
+      ## environment.
+      assert("env #{env.inspect} is not a Hash, but #{env.class}") {
+        env.kind_of? Hash
+      }
+      assert("env should not be frozen, but is") {
+        !env.frozen?
+      }
+
+      ##
+      ## 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>:: 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> can never be an empty
+      ##                        string, and so is always required.
+
+      ## <tt>SERVER_PORT</tt>:: An optional +Integer+ which is the port the
+      ##                        server is running on. Should be specified if
+      ##                        the server is running on a non-standard port.
+
+      ## <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
+      ##                            {RFC3875 section 4.1.18}[https://tools.ietf.org/html/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:
+      if session = env[RACK_SESSION]
+        ##                         store(key, value)         (aliased as []=);
+        assert("session #{session.inspect} must respond to store and []=") {
+          session.respond_to?(:store) && session.respond_to?(:[]=)
+        }
+
+        ##                         fetch(key, default = nil) (aliased as []);
+        assert("session #{session.inspect} must respond to fetch and []") {
+          session.respond_to?(:fetch) && session.respond_to?(:[])
+        }
+
+        ##                         delete(key);
+        assert("session #{session.inspect} must respond to delete") {
+          session.respond_to?(:delete)
+        }
+
+        ##                         clear;
+        assert("session #{session.inspect} must respond to clear") {
+          session.respond_to?(:clear)
+        }
+
+        ##                         to_hash (returning unfrozen Hash instance);
+        assert("session #{session.inspect} must respond to to_hash and return unfrozen Hash instance") {
+          session.respond_to?(:to_hash) && session.to_hash.kind_of?(Hash) && !session.to_hash.frozen?
+        }
+      end
+
+      ## <tt>rack.logger</tt>:: A common object interface for logging messages.
+      ##                        The object must implement:
+      if logger = env[RACK_LOGGER]
+        ##                         info(message, &block)
+        assert("logger #{logger.inspect} must respond to info") {
+          logger.respond_to?(:info)
+        }
+
+        ##                         debug(message, &block)
+        assert("logger #{logger.inspect} must respond to debug") {
+          logger.respond_to?(:debug)
+        }
+
+        ##                         warn(message, &block)
+        assert("logger #{logger.inspect} must respond to warn") {
+          logger.respond_to?(:warn)
+        }
+
+        ##                         error(message, &block)
+        assert("logger #{logger.inspect} must respond to error") {
+          logger.respond_to?(:error)
+        }
+
+        ##                         fatal(message, &block)
+        assert("logger #{logger.inspect} must respond to fatal") {
+          logger.respond_to?(:fatal)
+        }
+      end
+
+      ## <tt>rack.multipart.buffer_size</tt>:: An Integer hint to the multipart parser as to what chunk size to use for reads and writes.
+      if bufsize = env[RACK_MULTIPART_BUFFER_SIZE]
+        assert("rack.multipart.buffer_size must be an Integer > 0 if specified") {
+          bufsize.is_a?(Integer) && bufsize > 0
+        }
+      end
+
+      ## <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.
+      if tempfile_factory = env[RACK_MULTIPART_TEMPFILE_FACTORY]
+        assert("rack.multipart.tempfile_factory must respond to #call") { tempfile_factory.respond_to?(:call) }
+        env[RACK_MULTIPART_TEMPFILE_FACTORY] = lambda do |filename, content_type|
+          io = tempfile_factory.call(filename, content_type)
+          assert("rack.multipart.tempfile_factory return value must respond to #<<") { io.respond_to?(:<<) }
+          io
+        end
+      end
+
+      ## 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.
+      ##
+
+      %w[REQUEST_METHOD SERVER_NAME QUERY_STRING
+         rack.version rack.input rack.errors
+         rack.multithread rack.multiprocess rack.run_once].each { |header|
+        assert("env missing required key #{header}") { env.include? header }
+      }
+
+      ## The <tt>SERVER_PORT</tt> must be an Integer if set.
+      assert("env[SERVER_PORT] is not an Integer") do
+        server_port = env["SERVER_PORT"]
+        server_port.nil? || (Integer(server_port) rescue false)
+      end
+
+      ## The <tt>SERVER_NAME</tt> must be a valid authority as defined by RFC7540.
+      assert("#{env[SERVER_NAME]} must be a valid authority") do
+        URI.parse("http://#{env[SERVER_NAME]}/") rescue false
+      end
+
+      ## The <tt>HTTP_HOST</tt> must be a valid authority as defined by RFC7540.
+      assert("#{env[HTTP_HOST]} must be a valid authority") do
+        URI.parse("http://#{env[HTTP_HOST]}/") rescue false
+      end
+
+      ## 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>).
+      %w[HTTP_CONTENT_TYPE HTTP_CONTENT_LENGTH].each { |header|
+        assert("env contains #{header}, must use #{header[5, -1]}") {
+          not env.include? header
+        }
+      }
+
+      ## The CGI keys (named without a period) must have String values.
+      ## If the string values for CGI keys contain non-ASCII characters,
+      ## they should use ASCII-8BIT encoding.
+      env.each { |key, value|
+        next  if key.include? "."   # Skip extensions
+        assert("env variable #{key} has non-string value #{value.inspect}") {
+          value.kind_of? String
+        }
+        next if value.encoding == Encoding::ASCII_8BIT
+        assert("env variable #{key} has value containing non-ASCII characters and has non-ASCII-8BIT encoding #{value.inspect} encoding: #{value.encoding}") {
+          value.b !~ /[\x80-\xff]/n
+        }
+      }
+
+      ## There are the following restrictions:
+
+      ## * <tt>rack.version</tt> must be an array of Integers.
+      assert("rack.version must be an Array, was #{env[RACK_VERSION].class}") {
+        env[RACK_VERSION].kind_of? Array
+      }
+      ## * <tt>rack.url_scheme</tt> must either be +http+ or +https+.
+      assert("rack.url_scheme unknown: #{env[RACK_URL_SCHEME].inspect}") {
+        %w[http https].include?(env[RACK_URL_SCHEME])
+      }
+
+      ## * There must be a valid input stream in <tt>rack.input</tt>.
+      check_input env[RACK_INPUT]
+      ## * There must be a valid error stream in <tt>rack.errors</tt>.
+      check_error env[RACK_ERRORS]
+      ## * There may be a valid hijack stream in <tt>rack.hijack_io</tt>
+      check_hijack env
+
+      ## * The <tt>REQUEST_METHOD</tt> must be a valid token.
+      assert("REQUEST_METHOD unknown: #{env[REQUEST_METHOD].dump}") {
+        env[REQUEST_METHOD] =~ /\A[0-9A-Za-z!\#$%&'*+.^_`|~-]+\z/
+      }
+
+      ## * The <tt>SCRIPT_NAME</tt>, if non-empty, must start with <tt>/</tt>
+      assert("SCRIPT_NAME must start with /") {
+        !env.include?(SCRIPT_NAME) ||
+        env[SCRIPT_NAME] == "" ||
+        env[SCRIPT_NAME] =~ /\A\//
+      }
+      ## * The <tt>PATH_INFO</tt>, if non-empty, must start with <tt>/</tt>
+      assert("PATH_INFO must start with /") {
+        !env.include?(PATH_INFO) ||
+        env[PATH_INFO] == "" ||
+        env[PATH_INFO] =~ /\A\//
+      }
+      ## * The <tt>CONTENT_LENGTH</tt>, if given, must consist of digits only.
+      assert("Invalid CONTENT_LENGTH: #{env["CONTENT_LENGTH"]}") {
+        !env.include?("CONTENT_LENGTH") || env["CONTENT_LENGTH"] =~ /\A\d+\z/
+      }
+
+      ## * 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.
+      assert("One of SCRIPT_NAME or PATH_INFO must be set (make PATH_INFO '/' if SCRIPT_NAME is empty)") {
+        env[SCRIPT_NAME] || env[PATH_INFO]
+      }
+      ##   <tt>SCRIPT_NAME</tt> never should be <tt>/</tt>, but instead be empty.
+      assert("SCRIPT_NAME cannot be '/', make it '' and PATH_INFO '/'") {
+        env[SCRIPT_NAME] != "/"
+      }
+    end
+
+    ## === The Input Stream
+    ##
+    ## The input stream is an IO-like object which contains the raw HTTP
+    ## POST data.
+    def check_input(input)
+      ## When applicable, its external encoding must be "ASCII-8BIT" and it
+      ## must be opened in binary mode, for Ruby 1.9 compatibility.
+      assert("rack.input #{input} does not have ASCII-8BIT as its external encoding") {
+        input.external_encoding == Encoding::ASCII_8BIT
+      } if input.respond_to?(:external_encoding)
+      assert("rack.input #{input} is not opened in binary mode") {
+        input.binmode?
+      } if input.respond_to?(:binmode?)
+
+      ## The input stream must respond to +gets+, +each+, +read+ and +rewind+.
+      [:gets, :each, :read, :rewind].each { |method|
+        assert("rack.input #{input} does not respond to ##{method}") {
+          input.respond_to? method
+        }
+      }
+    end
+
+    class InputWrapper
+      include Assertion
+
+      def initialize(input)
+        @input = input
+      end
+
+      ## * +gets+ must be called without arguments and return a string,
+      ##   or +nil+ on EOF.
+      def gets(*args)
+        assert("rack.input#gets called with arguments") { args.size == 0 }
+        v = @input.gets
+        assert("rack.input#gets didn't return a String") {
+          v.nil? or v.kind_of? String
+        }
+        v
+      end
+
+      ## * +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.
+      def read(*args)
+        assert("rack.input#read called with too many arguments") {
+          args.size <= 2
+        }
+        if args.size >= 1
+          assert("rack.input#read called with non-integer and non-nil length") {
+            args.first.kind_of?(Integer) || args.first.nil?
+          }
+          assert("rack.input#read called with a negative length") {
+            args.first.nil? || args.first >= 0
+          }
+        end
+        if args.size >= 2
+          assert("rack.input#read called with non-String buffer") {
+            args[1].kind_of?(String)
+          }
+        end
+
+        v = @input.read(*args)
+
+        assert("rack.input#read didn't return nil or a String") {
+          v.nil? or v.kind_of? String
+        }
+        if args[0].nil?
+          assert("rack.input#read(nil) returned nil on EOF") {
+            !v.nil?
+          }
+        end
+
+        v
+      end
+
+      ## * +each+ must be called without arguments and only yield Strings.
+      def each(*args)
+        assert("rack.input#each called with arguments") { args.size == 0 }
+        @input.each { |line|
+          assert("rack.input#each didn't yield a String") {
+            line.kind_of? String
+          }
+          yield line
+        }
+      end
+
+      ## * +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.
+      def rewind(*args)
+        assert("rack.input#rewind called with arguments") { args.size == 0 }
+        assert("rack.input#rewind raised Errno::ESPIPE") {
+          begin
+            @input.rewind
+            true
+          rescue Errno::ESPIPE
+            false
+          end
+        }
+      end
+
+      ## * +close+ must never be called on the input stream.
+      def close(*args)
+        assert("rack.input#close must not be called") { false }
+      end
+    end
+
+    ## === The Error Stream
+    def check_error(error)
+      ## The error stream must respond to +puts+, +write+ and +flush+.
+      [:puts, :write, :flush].each { |method|
+        assert("rack.error #{error} does not respond to ##{method}") {
+          error.respond_to? method
+        }
+      }
+    end
+
+    class ErrorWrapper
+      include Assertion
+
+      def initialize(error)
+        @error = error
+      end
+
+      ## * +puts+ must be called with a single argument that responds to +to_s+.
+      def puts(str)
+        @error.puts str
+      end
+
+      ## * +write+ must be called with a single argument that is a String.
+      def write(str)
+        assert("rack.errors#write not called with a String") { str.kind_of? String }
+        @error.write str
+      end
+
+      ## * +flush+ must be called without arguments and must be called
+      ##   in order to make the error appear for sure.
+      def flush
+        @error.flush
+      end
+
+      ## * +close+ must never be called on the error stream.
+      def close(*args)
+        assert("rack.errors#close must not be called") { false }
+      end
+    end
+
+    class HijackWrapper
+      include Assertion
+      extend Forwardable
+
+      REQUIRED_METHODS = [
+        :read, :write, :read_nonblock, :write_nonblock, :flush, :close,
+        :close_read, :close_write, :closed?
+      ]
+
+      def_delegators :@io, *REQUIRED_METHODS
+
+      def initialize(io)
+        @io = io
+        REQUIRED_METHODS.each do |meth|
+          assert("rack.hijack_io must respond to #{meth}") { io.respond_to? meth }
+        end
+      end
+    end
+
+    ## === Hijacking
+    #
+    # AUTHORS: n.b. The trailing whitespace between paragraphs is important and
+    # should not be removed. The whitespace creates paragraphs in the RDoc
+    # output.
+    #
+    ## ==== Request (before status)
+    def check_hijack(env)
+      if env[RACK_IS_HIJACK]
+        ## If rack.hijack? is true then rack.hijack must respond to #call.
+        original_hijack = env[RACK_HIJACK]
+        assert("rack.hijack must respond to call") { original_hijack.respond_to?(:call) }
+        env[RACK_HIJACK] = proc do
+          ## rack.hijack must return the io that will also be assigned (or is
+          ## already present, in rack.hijack_io.
+          io = original_hijack.call
+          HijackWrapper.new(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.
+          env[RACK_HIJACK_IO] = HijackWrapper.new(env[RACK_HIJACK_IO])
+          io
+        end
+      else
+        ##
+        ## If rack.hijack? is false, then rack.hijack should not be set.
+        assert("rack.hijack? is false, but rack.hijack is present") { env[RACK_HIJACK].nil? }
+        ##
+        ## If rack.hijack? is false, then rack.hijack_io should not be set.
+        assert("rack.hijack? is false, but rack.hijack_io is present") { env[RACK_HIJACK_IO].nil? }
+      end
+    end
+
+    ## ==== Response (after headers)
+    ## It is also possible to hijack a response after the status and headers
+    ## have been sent.
+    def check_hijack_response(headers, env)
+
+      # this check uses headers like a hash, but the spec only requires
+      # headers respond to #each
+      headers = Rack::Utils::HeaderHash[headers]
+
+      ## 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.
+
+      if env[RACK_IS_HIJACK] && headers[RACK_HIJACK]
+        assert('rack.hijack header must respond to #call') {
+          headers[RACK_HIJACK].respond_to? :call
+        }
+        original_hijack = headers[RACK_HIJACK]
+        proc do |io|
+          original_hijack.call HijackWrapper.new(io)
+        end
+      else
+        ##
+        ## The special response header <tt>rack.hijack</tt> must only be set
+        ## if the request env has <tt>rack.hijack?</tt> <tt>true</tt>.
+        assert('rack.hijack header must not be present if server does not support hijacking') {
+          headers[RACK_HIJACK].nil?
+        }
+
+        nil
+      end
+    end
+    ## ==== 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
+    def check_status(status)
+      ## This is an HTTP status. When parsed as integer (+to_i+), it must be
+      ## greater than or equal to 100.
+      assert("Status must be >=100 seen as integer") { status.to_i >= 100 }
+    end
+
+    ## === The Headers
+    def check_headers(header)
+      ## The header must respond to +each+, and yield values of key and value.
+      assert("headers object should respond to #each, but doesn't (got #{header.class} as headers)") {
+         header.respond_to? :each
+      }
+
+      header.each { |key, value|
+        ## The header keys must be Strings.
+        assert("header key must be a string, was #{key.class}") {
+          key.kind_of? String
+        }
+
+        ## Special headers starting "rack." are for communicating with the
+        ## server, and must not be sent back to the client.
+        next if key =~ /^rack\..+$/
+
+        ## The header must not contain a +Status+ key.
+        assert("header must not contain Status") { key.downcase != "status" }
+        ## The header must conform to RFC7230 token specification, i.e. cannot
+        ## contain non-printable ASCII, DQUOTE or "(),/:;<=>?@[\]{}".
+        assert("invalid header name: #{key}") { key !~ /[\(\),\/:;<=>\?@\[\\\]{}[:cntrl:]]/ }
+
+        ## The values of the header must be Strings,
+        assert("a header value must be a String, but the value of " +
+          "'#{key}' is a #{value.class}") { value.kind_of? String }
+        ## consisting of lines (for multiple header values, e.g. multiple
+        ## <tt>Set-Cookie</tt> values) separated by "\\n".
+        value.split("\n").each { |item|
+          ## The lines must not contain characters below 037.
+          assert("invalid header value #{key}: #{item.inspect}") {
+            item !~ /[\000-\037]/
+          }
+        }
+      }
+    end
+
+    ## === The Content-Type
+    def check_content_type(status, headers)
+      headers.each { |key, value|
+        ## There must not be a <tt>Content-Type</tt>, when the +Status+ is 1xx,
+        ## 204 or 304.
+        if key.downcase == "content-type"
+          assert("Content-Type header found in #{status} response, not allowed") {
+            not Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
+          }
+          return
+        end
+      }
+    end
+
+    ## === The Content-Length
+    def check_content_length(status, headers)
+      headers.each { |key, value|
+        if key.downcase == 'content-length'
+          ## There must not be a <tt>Content-Length</tt> header when the
+          ## +Status+ is 1xx, 204 or 304.
+          assert("Content-Length header found in #{status} response, not allowed") {
+            not Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.key? status.to_i
+          }
+          @content_length = value
+        end
+      }
+    end
+
+    def verify_content_length(bytes)
+      if @head_request
+        assert("Response body was given for HEAD request, but should be empty") {
+          bytes == 0
+        }
+      elsif @content_length
+        assert("Content-Length header was #{@content_length}, but should be #{bytes}") {
+          @content_length == bytes.to_s
+        }
+      end
+    end
+
+    ## === The Body
+    def each
+      @closed = false
+      bytes = 0
+
+      ## The Body must respond to +each+
+      assert("Response body must respond to each") do
+        @body.respond_to?(:each)
+      end
+
+      @body.each { |part|
+        ## and must only yield String values.
+        assert("Body yielded non-string value #{part.inspect}") {
+          part.kind_of? String
+        }
+        bytes += part.bytesize
+        yield part
+      }
+      verify_content_length(bytes)
+
+      ##
+      ## 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.
+      # XXX howto: assert("Body has not been closed") { @closed }
+
+
+      ##
+      ## 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.
+
+      if @body.respond_to?(:to_path)
+        assert("The file identified by body.to_path does not exist") {
+          ::File.exist? @body.to_path
+        }
+      end
+
+      ##
+      ## The Body commonly is an Array of Strings, the application
+      ## instance itself, or a File-like object.
+    end
+
+    def close
+      @closed = true
+      @body.close  if @body.respond_to?(:close)
+    end
+
+    # :startdoc:
+
+  end
+end
+
+## == 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.