rack 2.0.9.3 → 2.2.0

data/lib/rack/builder.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   # Rack::Builder implements a small DSL to iteratively construct Rack
   # applications.
@@ -29,32 +31,102 @@ module Rack
   # You can use +map+ to construct a Rack::URLMap in a convenient way.
 
   class Builder
+
+    # https://stackoverflow.com/questions/2223882/whats-the-difference-between-utf-8-and-utf-8-without-bom
+    UTF_8_BOM = '\xef\xbb\xbf'
+
+    # Parse the given config file to get a Rack application.
+    #
+    # If the config file ends in +.ru+, it is treated as a
+    # rackup file and the contents will be treated as if
+    # specified inside a Rack::Builder block, using the given
+    # options.
+    #
+    # If the config file does not end in +.ru+, it is
+    # required and Rack will use the basename of the file
+    # to guess which constant will be the Rack application to run.
+    # The options given will be ignored in this case.
+    #
+    # Examples:
+    #
+    #   Rack::Builder.parse_file('config.ru')
+    #   # Rack application built using Rack::Builder.new
+    #
+    #   Rack::Builder.parse_file('app.rb')
+    #   # requires app.rb, which can be anywhere in Ruby's
+    #   # load path. After requiring, assumes App constant
+    #   # contains Rack application
+    #
+    #   Rack::Builder.parse_file('./my_app.rb')
+    #   # requires ./my_app.rb, which should be in the
+    #   # process's current directory.  After requiring,
+    #   # assumes MyApp constant contains Rack application
     def self.parse_file(config, opts = Server::Options.new)
-      options = {}
-      if config =~ /\.ru$/
-        cfgfile = ::File.read(config)
-        if cfgfile[/^#\\(.*)/] && opts
-          options = opts.parse! $1.split(/\s+/)
-        end
-        cfgfile.sub!(/^__END__\n.*\Z/m, '')
-        app = new_from_string cfgfile, config
+      if config.end_with?('.ru')
+        return self.load_file(config, opts)
       else
         require config
         app = Object.const_get(::File.basename(config, '.rb').split('_').map(&:capitalize).join(''))
+        return app, {}
+      end
+    end
+
+    # Load the given file as a rackup file, treating the
+    # contents as if specified inside a Rack::Builder block.
+    #
+    # Treats the first comment at the beginning of a line
+    # that starts with a backslash as options similar to
+    # options passed on a rackup command line.
+    #
+    # Ignores content in the file after +__END__+, so that
+    # use of +__END__+ will not result in a syntax error.
+    #
+    # Example config.ru file:
+    #
+    #   $ cat config.ru
+    #
+    #   #\ -p 9393
+    #
+    #   use Rack::ContentLength
+    #   require './app.rb'
+    #   run App
+    def self.load_file(path, opts = Server::Options.new)
+      options = {}
+
+      cfgfile = ::File.read(path)
+      cfgfile.slice!(/\A#{UTF_8_BOM}/) if cfgfile.encoding == Encoding::UTF_8
+
+      if cfgfile[/^#\\(.*)/] && opts
+        warn "Parsing options from the first comment line is deprecated!"
+        options = opts.parse! $1.split(/\s+/)
       end
+
+      cfgfile.sub!(/^__END__\n.*\Z/m, '')
+      app = new_from_string cfgfile, path
+
       return app, options
     end
 
-    def self.new_from_string(builder_script, file="(rackup)")
-      eval "Rack::Builder.new {\n" + builder_script + "\n}.to_app",
-        TOPLEVEL_BINDING, file, 0
+    # Evaluate the given +builder_script+ string in the context of
+    # a Rack::Builder block, returning a Rack application.
+    def self.new_from_string(builder_script, file = "(rackup)")
+      # We want to build a variant of TOPLEVEL_BINDING with self as a Rack::Builder instance.
+      # We cannot use instance_eval(String) as that would resolve constants differently.
+      binding, builder = TOPLEVEL_BINDING.eval('Rack::Builder.new.instance_eval { [binding, self] }')
+      eval builder_script, binding, file
+      builder.to_app
     end
 
+    # Initialize a new Rack::Builder instance.  +default_app+ specifies the
+    # default application if +run+ is not called later.  If a block
+    # is given, it is evaluted in the context of the instance.
     def initialize(default_app = nil, &block)
-      @use, @map, @run, @warmup = [], nil, default_app, nil
+      @use, @map, @run, @warmup, @freeze_app = [], nil, default_app, nil, false
       instance_eval(&block) if block_given?
     end
 
+    # Create a new Rack::Builder instance and return the Rack application
+    # generated from it.
     def self.app(default_app = nil, &block)
       self.new(default_app, &block).to_app
     end
@@ -81,10 +153,11 @@ module Rack
     def use(middleware, *args, &block)
       if @map
         mapping, @map = @map, nil
-        @use << proc { |app| generate_map app, mapping }
+        @use << proc { |app| generate_map(app, mapping) }
       end
       @use << proc { |app| middleware.new(app, *args, &block) }
     end
+    ruby2_keywords(:use) if respond_to?(:ruby2_keywords, true)
 
     # Takes an argument that is an object that responds to #call and returns a Rack response.
     # The simplest form of this is a lambda object:
@@ -104,7 +177,8 @@ module Rack
       @run = app
     end
 
-    # Takes a lambda or block that is used to warm-up the application.
+    # Takes a lambda or block that is used to warm-up the application. This block is called
+    # before the Rack application is returned by to_app.
     #
     #   warmup do |app|
     #     client = Rack::MockRequest.new(app)
@@ -113,51 +187,70 @@ module Rack
     #
     #   use SomeMiddleware
     #   run MyApp
-    def warmup(prc=nil, &block)
+    def warmup(prc = nil, &block)
       @warmup = prc || block
     end
 
-    # Creates a route within the application.
+    # Creates a route within the application.  Routes under the mapped path will be sent to
+    # the Rack application specified by run inside the block.  Other requests will be sent to the
+    # default application specified by run outside the block.
     #
     #   Rack::Builder.app do
-    #     map '/' do
+    #     map '/heartbeat' do
     #       run Heartbeat
     #     end
+    #     run App
     #   end
     #
-    # The +use+ method can also be used here to specify middleware to run under a specific path:
+    # The +use+ method can also be used inside the block to specify middleware to run under a specific path:
     #
     #   Rack::Builder.app do
-    #     map '/' do
+    #     map '/heartbeat' do
     #       use Middleware
     #       run Heartbeat
     #     end
+    #     run App
     #   end
     #
-    # This example includes a piece of middleware which will run before requests hit +Heartbeat+.
+    # This example includes a piece of middleware which will run before +/heartbeat+ requests hit +Heartbeat+.
     #
+    # Note that providing a +path+ of +/+ will ignore any default application given in a +run+ statement
+    # outside the block.
     def map(path, &block)
       @map ||= {}
       @map[path] = block
     end
 
+    # Freeze the app (set using run) and all middleware instances when building the application
+    # in to_app.
+    def freeze_app
+      @freeze_app = true
+    end
+
+    # Return the Rack application generated by this instance.
     def to_app
       app = @map ? generate_map(@run, @map) : @run
       fail "missing run or map statement" unless app
-      app = @use.reverse.inject(app) { |a,e| e[a] }
+      app.freeze if @freeze_app
+      app = @use.reverse.inject(app) { |a, e| e[a].tap { |x| x.freeze if @freeze_app } }
       @warmup.call(app) if @warmup
       app
     end
 
+    # Call the Rack application generated by this builder instance. Note that
+    # this rebuilds the Rack application and runs the warmup code (if any)
+    # every time it is called, so it should not be used if performance is important.
     def call(env)
       to_app.call(env)
     end
 
     private
 
+    # Generate a URLMap instance by generating new Rack applications for each
+    # map block in this instance.
     def generate_map(default_app, mapping)
-      mapped = default_app ? {'/' => default_app} : {}
-      mapping.each { |r,b| mapped[r] = self.class.new(default_app, &b).to_app }
+      mapped = default_app ? { '/' => default_app } : {}
+      mapping.each { |r, b| mapped[r] = self.class.new(default_app, &b).to_app }
       URLMap.new(mapped)
     end
   end

data/lib/rack/cascade.rb

@@ -1,24 +1,38 @@
+# frozen_string_literal: true
+
 module Rack
   # Rack::Cascade tries a request on several apps, and returns the
-  # first response that is not 404 or 405 (or in a list of configurable
-  # status codes).
+  # first response that is not 404 or 405 (or in a list of configured
+  # status codes).  If all applications tried return one of the configured
+  # status codes, return the last response.
 
   class Cascade
-    NotFound = [404, {CONTENT_TYPE => "text/plain"}, []]
+    # deprecated, no longer used
+    NotFound = [404, { CONTENT_TYPE => "text/plain" }, []]
 
+    # An array of applications to try in order.
     attr_reader :apps
 
-    def initialize(apps, catch=[404, 405])
-      @apps = []; @has_app = {}
+    # Set the apps to send requests to, and what statuses result in
+    # cascading.  Arguments:
+    #
+    # apps: An enumerable of rack applications.
+    # cascade_for: The statuses to use cascading for.  If a response is received
+    #              from an app, the next app is tried.
+    def initialize(apps, cascade_for = [404, 405])
+      @apps = []
       apps.each { |app| add app }
 
-      @catch = {}
-      [*catch].each { |status| @catch[status] = true }
+      @cascade_for = {}
+      [*cascade_for].each { |status| @cascade_for[status] = true }
     end
 
+    # Call each app in order.  If the responses uses a status that requires
+    # cascading, try the next app.  If all responses require cascading,
+    # return the response from the last app.
     def call(env)
-      result = NotFound
-
+      return [404, { CONTENT_TYPE => "text/plain" }, []] if @apps.empty?
+      result = nil
       last_body = nil
 
       @apps.each do |app|
@@ -31,20 +45,22 @@ module Rack
         last_body.close if last_body.respond_to? :close
 
         result = app.call(env)
+        return result unless @cascade_for.include?(result[0].to_i)
         last_body = result[2]
-        break unless @catch.include?(result[0].to_i)
       end
 
       result
     end
 
+    # Append an app to the list of apps to cascade.  This app will
+    # be tried last.
     def add(app)
-      @has_app[app] = true
       @apps << app
     end
 
+    # Whether the given app is one of the apps to cascade to.
     def include?(app)
-      @has_app.include? app
+      @apps.include?(app)
     end
 
     alias_method :<<, :add

data/lib/rack/chunked.rb

@@ -1,69 +1,117 @@
-require 'rack/utils'
+# frozen_string_literal: true
 
 module Rack
 
   # Middleware that applies chunked transfer encoding to response bodies
   # when the response does not include a Content-Length header.
+  #
+  # This supports the Trailer response header to allow the use of trailing
+  # headers in the chunked encoding.  However, using this requires you manually
+  # specify a response body that supports a +trailers+ method.  Example:
+  #
+  #   [200, { 'Trailer' => 'Expires'}, ["Hello", "World"]]
+  #   # error raised
+  #
+  #   body = ["Hello", "World"]
+  #   def body.trailers
+  #     { 'Expires' => Time.now.to_s }
+  #   end
+  #   [200, { 'Trailer' => 'Expires'}, body]
+  #   # No exception raised
   class Chunked
     include Rack::Utils
 
-    # A body wrapper that emits chunked responses
+    # A body wrapper that emits chunked responses.
     class Body
       TERM = "\r\n"
-      TAIL = "0#{TERM}#{TERM}"
-
-      include Rack::Utils
+      TAIL = "0#{TERM}"
 
+      # Store the response body to be chunked.
       def initialize(body)
         @body = body
       end
 
-      def each
+      # For each element yielded by the response body, yield
+      # the element in chunked encoding.
+      def each(&block)
         term = TERM
         @body.each do |chunk|
           size = chunk.bytesize
           next if size == 0
 
-          chunk = chunk.b
-          yield [size.to_s(16), term, chunk, term].join
+          yield [size.to_s(16), term, chunk.b, term].join
         end
         yield TAIL
+        yield_trailers(&block)
+        yield term
       end
 
+      # Close the response body if the response body supports it.
       def close
         @body.close if @body.respond_to?(:close)
       end
+
+      private
+
+      # Do nothing as this class does not support trailer headers.
+      def yield_trailers
+      end
+    end
+
+    # A body wrapper that emits chunked responses and also supports
+    # sending Trailer headers.  Note that the response body provided to
+    # initialize must have a +trailers+ method that returns a hash
+    # of trailer headers, and the rack response itself should have a
+    # Trailer header listing the headers that the +trailers+ method
+    # will return.
+    class TrailerBody < Body
+      private
+
+      # Yield strings for each trailer header.
+      def yield_trailers
+        @body.trailers.each_pair do |k, v|
+          yield "#{k}: #{v}\r\n"
+        end
+      end
     end
 
     def initialize(app)
       @app = app
     end
 
-    # pre-HTTP/1.0 (informally "HTTP/0.9") HTTP requests did not have
-    # a version (nor response headers)
+    # Whether the HTTP version supports chunked encoding (HTTP 1.1 does).
     def chunkable_version?(ver)
       case ver
-      when "HTTP/1.0", nil, "HTTP/0.9"
+      # pre-HTTP/1.0 (informally "HTTP/0.9") HTTP requests did not have
+      # a version (nor response headers)
+      when 'HTTP/1.0', nil, 'HTTP/0.9'
         false
       else
         true
       end
     end
 
+    # If the rack app returns a response that should have a body,
+    # but does not have Content-Length or Transfer-Encoding headers,
+    # modify the response to use chunked Transfer-Encoding.
     def call(env)
       status, headers, body = @app.call(env)
-      headers = HeaderHash.new(headers)
+      headers = HeaderHash[headers]
+
+      if chunkable_version?(env[SERVER_PROTOCOL]) &&
+         !STATUS_WITH_NO_ENTITY_BODY.key?(status.to_i) &&
+         !headers[CONTENT_LENGTH] &&
+         !headers[TRANSFER_ENCODING]
 
-      if ! chunkable_version?(env[HTTP_VERSION]) ||
-         STATUS_WITH_NO_ENTITY_BODY.include?(status) ||
-         headers[CONTENT_LENGTH] ||
-         headers[TRANSFER_ENCODING]
-        [status, headers, body]
-      else
-        headers.delete(CONTENT_LENGTH)
         headers[TRANSFER_ENCODING] = 'chunked'
-        [status, headers, Body.new(body)]
+        if headers['Trailer']
+          body = TrailerBody.new(body)
+        else
+          body = Body.new(body)
+        end
       end
+
+      [status, headers, body]
     end
   end
 end

data/lib/rack/common_logger.rb

@@ -1,63 +1,66 @@
-require 'rack/body_proxy'
+# frozen_string_literal: true
 
 module Rack
   # Rack::CommonLogger forwards every request to the given +app+, and
   # logs a line in the
   # {Apache common log format}[http://httpd.apache.org/docs/1.3/logs.html#common]
-  # to the +logger+.
-  #
-  # If +logger+ is nil, CommonLogger will fall back +rack.errors+, which is
-  # an instance of Rack::NullLogger.
-  #
-  # +logger+ can be any class, including the standard library Logger, and is
-  # expected to have either +write+ or +<<+ method, which accepts the CommonLogger::FORMAT.
-  # According to the SPEC, the error stream must also respond to +puts+
-  # (which takes a single argument that responds to +to_s+), and +flush+
-  # (which is called without arguments in order to make the error appear for
-  # sure)
+  # to the configured logger.
   class CommonLogger
     # Common Log Format: http://httpd.apache.org/docs/1.3/logs.html#common
     #
     #   lilith.local - - [07/Aug/2006 23:58:02 -0400] "GET / HTTP/1.1" 500 -
     #
     #   %{%s - %s [%s] "%s %s%s %s" %d %s\n} %
-    FORMAT = %{%s - %s [%s] "%s %s%s %s" %d %s %0.4f\n}
+    #
+    # The actual format is slightly different than the above due to the
+    # separation of SCRIPT_NAME and PATH_INFO, and because the elapsed
+    # time in seconds is included at the end.
+    FORMAT = %{%s - %s [%s] "%s %s%s%s %s" %d %s %0.4f\n}
 
-    def initialize(app, logger=nil)
+    # +logger+ can be any object that supports the +write+ or +<<+ methods,
+    # which includes the standard library Logger.  These methods are called
+    # with a single string argument, the log message.
+    # If +logger+ is nil, CommonLogger will fall back <tt>env['rack.errors']</tt>.
+    def initialize(app, logger = nil)
       @app = app
       @logger = logger
     end
 
+    # Log all requests in common_log format after a response has been
+    # returned.  Note that if the app raises an exception, the request
+    # will not be logged, so if exception handling middleware are used,
+    # they should be loaded after this middleware.  Additionally, because
+    # the logging happens after the request body has been fully sent, any
+    # exceptions raised during the sending of the response body will
+    # cause the request not to be logged.
     def call(env)
-      began_at = Time.now
-      status, header, body = @app.call(env)
-      header = Utils::HeaderHash.new(header)
-      body = BodyProxy.new(body) { log(env, status, header, began_at) }
-      [status, header, body]
+      began_at = Utils.clock_time
+      status, headers, body = @app.call(env)
+      headers = Utils::HeaderHash[headers]
+      body = BodyProxy.new(body) { log(env, status, headers, began_at) }
+      [status, headers, body]
     end
 
     private
 
+    # Log the request to the configured logger.
     def log(env, status, header, began_at)
-      now = Time.now
       length = extract_content_length(header)
 
       msg = FORMAT % [
         env['HTTP_X_FORWARDED_FOR'] || env["REMOTE_ADDR"] || "-",
         env["REMOTE_USER"] || "-",
-        now.strftime("%d/%b/%Y:%H:%M:%S %z"),
+        Time.now.strftime("%d/%b/%Y:%H:%M:%S %z"),
         env[REQUEST_METHOD],
+        env[SCRIPT_NAME],
         env[PATH_INFO],
         env[QUERY_STRING].empty? ? "" : "?#{env[QUERY_STRING]}",
-        env[HTTP_VERSION],
+        env[SERVER_PROTOCOL],
         status.to_s[0..3],
         length,
-        now - began_at ]
-
-      msg.gsub!(/[^[:print:]\n]/) { |c| "\\x#{c.ord}" }
+        Utils.clock_time - began_at ]
 
       logger = @logger || env[RACK_ERRORS]
-
       # Standard library logger doesn't support write but it supports << which actually
       # calls to write on the log device without formatting
       if logger.respond_to?(:write)
@@ -67,9 +70,11 @@ module Rack
       end
     end
 
+    # Attempt to determine the content length for the response to
+    # include it in the logged data.
     def extract_content_length(headers)
-      value = headers[CONTENT_LENGTH] or return '-'
-      value.to_s == '0' ? '-' : value
+      value = headers[CONTENT_LENGTH]
+      !value || value.to_s == '0' ? '-' : value
     end
   end
 end

data/lib/rack/conditional_get.rb

@@ -1,4 +1,4 @@
-require 'rack/utils'
+# frozen_string_literal: true
 
 module Rack
 
@@ -19,11 +19,13 @@ module Rack
       @app = app
     end
 
+    # Return empty 304 response if the response has not been
+    # modified since the last request.
     def call(env)
       case env[REQUEST_METHOD]
       when "GET", "HEAD"
         status, headers, body = @app.call(env)
-        headers = Utils::HeaderHash.new(headers)
+        headers = Utils::HeaderHash[headers]
         if status == 200 && fresh?(env, headers)
           status = 304
           headers.delete(CONTENT_TYPE)
@@ -41,38 +43,40 @@ module Rack
 
   private
 
+    # Return whether the response has not been modified since the
+    # last request.
     def fresh?(env, headers)
-      modified_since = env['HTTP_IF_MODIFIED_SINCE']
-      none_match     = env['HTTP_IF_NONE_MATCH']
-
-      return false unless modified_since || none_match
-
-      success = true
-      success &&= modified_since?(to_rfc2822(modified_since), headers) if modified_since
-      success &&= etag_matches?(none_match, headers) if none_match
-      success
+      # If-None-Match has priority over If-Modified-Since per RFC 7232
+      if none_match = env['HTTP_IF_NONE_MATCH']
+        etag_matches?(none_match, headers)
+      elsif (modified_since = env['HTTP_IF_MODIFIED_SINCE']) && (modified_since = to_rfc2822(modified_since))
+        modified_since?(modified_since, headers)
+      end
     end
 
+    # Whether the ETag response header matches the If-None-Match request header.
+    # If so, the request has not been modified.
     def etag_matches?(none_match, headers)
-      etag = headers['ETag'] and etag == none_match
+      headers['ETag'] == none_match
     end
 
+    # Whether the Last-Modified response header matches the If-Modified-Since
+    # request header.  If so, the request has not been modified.
     def modified_since?(modified_since, headers)
       last_modified = to_rfc2822(headers['Last-Modified']) and
-        modified_since and
         modified_since >= last_modified
     end
 
+    # Return a Time object for the given string (which should be in RFC2822
+    # format), or nil if the string cannot be parsed.
     def to_rfc2822(since)
       # shortest possible valid date is the obsolete: 1 Nov 97 09:55 A
       # anything shorter is invalid, this avoids exceptions for common cases
       # most common being the empty string
       if since && since.length >= 16
-        # NOTE: there is no trivial way to write this in a non execption way
+        # NOTE: there is no trivial way to write this in a non exception way
         #   _rfc2822 returns a hash but is not that usable
         Time.rfc2822(since) rescue nil
-      else
-        nil
       end
     end
   end

data/lib/rack/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   # Rack::Config modifies the environment using the block given during
   # initialization.

data/lib/rack/content_length.rb

@@ -1,9 +1,11 @@
-require 'rack/utils'
-require 'rack/body_proxy'
+# frozen_string_literal: true
 
 module Rack
 
-  # Sets the Content-Length header on responses with fixed-length bodies.
+  # Sets the Content-Length header on responses that do not specify
+  # a Content-Length or Transfer-Encoding header.  Note that this
+  # does not fix responses that have an invalid Content-Length
+  # header specified.
   class ContentLength
     include Rack::Utils
 
@@ -13,12 +15,11 @@ module Rack
 
     def call(env)
       status, headers, body = @app.call(env)
-      headers = HeaderHash.new(headers)
+      headers = HeaderHash[headers]
 
-      if !STATUS_WITH_NO_ENTITY_BODY.include?(status.to_i) &&
+      if !STATUS_WITH_NO_ENTITY_BODY.key?(status.to_i) &&
          !headers[CONTENT_LENGTH] &&
-         !headers[TRANSFER_ENCODING] &&
-         body.respond_to?(:to_ary)
+         !headers[TRANSFER_ENCODING]
 
         obody = body
         body, length = [], 0

data/lib/rack/content_type.rb

@@ -1,4 +1,4 @@
-require 'rack/utils'
+# frozen_string_literal: true
 
 module Rack
 
@@ -7,7 +7,8 @@ module Rack
   # Builder Usage:
   #   use Rack::ContentType, "text/plain"
   #
-  # When no content type argument is provided, "text/html" is assumed.
+  # When no content type argument is provided, "text/html" is the
+  # default.
   class ContentType
     include Rack::Utils
 
@@ -17,9 +18,9 @@ module Rack
 
     def call(env)
       status, headers, body = @app.call(env)
-      headers = Utils::HeaderHash.new(headers)
+      headers = Utils::HeaderHash[headers]
 
-      unless STATUS_WITH_NO_ENTITY_BODY.include?(status)
+      unless STATUS_WITH_NO_ENTITY_BODY.key?(status.to_i)
         headers[CONTENT_TYPE] ||= @content_type
       end