Class: Rack::Lint

Inherits:

Object

• Object
• Rack::Lint

Includes:

Assertion

Defined in:

lib/rack/lint.rb

Overview

Rack::Lint validates your application and the requests and responses according to the Rack spec.

Defined Under Namespace

Modules: Assertion Classes: ErrorWrapper, HijackWrapper, InputWrapper, LintError

Instance Method Summary

• #_call(env) ⇒ Object
• #call(env = nil) ⇒ Object

  A Rack application is a Ruby object (not a class) that responds to call.

• #check_content_length(status, headers) ⇒ Object

  The Content-Length.

• #check_content_type(status, headers) ⇒ Object

  The Content-Type.

• #check_env(env) ⇒ Object

  The Environment.

• #check_error(error) ⇒ Object

  The Error Stream.

• #check_headers(header) ⇒ Object

  The Headers.

• #check_hijack(env) ⇒ Object

  Hijacking.

• #check_hijack_response(headers, env) ⇒ Object

  Response (after headers) It is also possible to hijack a response after the status and headers have been sent.

• #check_input(input) ⇒ Object

  The Input Stream.

• #check_status(status) ⇒ Object

  The Status.

• #close ⇒ Object
• #each ⇒ Object

  The Body.

• #initialize(app) ⇒ Lint constructor

  A new instance of Lint.

• #verify_content_length(bytes) ⇒ Object

Methods included from Assertion

#assert

Constructor Details

#initialize(app) ⇒ Lint

Returns a new instance of Lint.

# File 'lib/rack/lint.rb', line 9

def initialize(app)
  @app = app
  @content_length = nil
end

Instance Method Details

#_call(env) ⇒ Object

# File 'lib/rack/lint.rb', line 40

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:
  status, headers, @body = @app.call(env)
  ## The *status*,
  check_status status
  ## the *headers*,
  check_headers headers

  check_hijack_response headers, env

  ## and the *body*.
  check_content_type status, headers
  check_content_length status, headers
  @head_request = env[REQUEST_METHOD] == "HEAD"
  [status, headers, self]
end

#call(env = nil) ⇒ Object

A Rack application is a Ruby object (not a class) that responds to call.

# File 'lib/rack/lint.rb', line 36

def call(env=nil)
  dup._call(env)
end

#check_content_length(status, headers) ⇒ Object

The Content-Length

# File 'lib/rack/lint.rb', line 673

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, 205 or 304.
      assert("Content-Length header found in #{status} response, not allowed") {
        not Rack::Utils::STATUS_WITH_NO_ENTITY_BODY.include? status.to_i
      }
      @content_length = value
    end
  }
end

#check_content_type(status, headers) ⇒ Object

The Content-Type

# File 'lib/rack/lint.rb', line 659

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, 205 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.include? status.to_i
      }
      return
    end
  }
end

#check_env(env) ⇒ Object

The Environment

# File 'lib/rack/lint.rb', line 65

def check_env(env)
  ## The environment must be an 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
  }

  ##
  ## 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 I 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
  ##                            <a href="https://tools.ietf.org/html/rfc3875#section-4.1.18">
  ##                            RFC3875 section 4.1.18</a> 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)
    }
  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 SERVER_PORT
     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 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.
  env.each { |key, value|
    next  if key.include? "."   # Skip extensions
    assert("env variable #{key} has non-string value #{value.inspect}") {
      value.kind_of? String
    }
  }

  ## 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]}") {
    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

#check_error(error) ⇒ Object

The Error Stream

# File 'lib/rack/lint.rb', line 455

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

#check_headers(header) ⇒ Object

The Headers

# File 'lib/rack/lint.rb', line 624

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|
    ## 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 keys must be Strings.
    assert("header key must be a string, was #{key.class}") {
      key.kind_of? String
    }
    ## 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

#check_hijack(env) ⇒ Object

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)

# File 'lib/rack/lint.rb', line 520

def check_hijack(env)
  if env['rack.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

#check_hijack_response(headers, env) ⇒ Object

Response (after headers)

It is also possible to hijack a response after the status and headers have been sent.

# File 'lib/rack/lint.rb', line 567

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.new(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.hijack?'] && headers['rack.hijack']
    assert('rack.hijack header must respond to #call') {
      headers['rack.hijack'].respond_to? :call
    }
    original_hijack = headers['rack.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?
    }
  end
end

#check_input(input) ⇒ Object

The Input Stream

The input stream is an IO-like object which contains the raw HTTP POST data.

# File 'lib/rack/lint.rb', line 335

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.name == "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

#check_status(status) ⇒ Object

The Status

# File 'lib/rack/lint.rb', line 617

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

#close ⇒ Object

# File 'lib/rack/lint.rb', line 746

def close
  @closed = true
  @body.close  if @body.respond_to?(:close)
end

#each ⇒ Object

The Body

# File 'lib/rack/lint.rb', line 699

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 += Rack::Utils.bytesize(part)
    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

#verify_content_length(bytes) ⇒ Object

# File 'lib/rack/lint.rb', line 686

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