rack 2.1.0 → 3.1.0

data/lib/rack/auth/abstract/handler.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative '../../constants'
+
 module Rack
   module Auth
     # Rack::Auth::AbstractHandler implements common authentication functionality.
@@ -21,7 +23,7 @@ module Rack
         return [ 401,
           { CONTENT_TYPE => 'text/plain',
             CONTENT_LENGTH => '0',
-            'WWW-Authenticate' => www_authenticate.to_s },
+            'www-authenticate' => www_authenticate.to_s },
           []
         ]
       end

data/lib/rack/auth/abstract/request.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'rack/request'
+require_relative '../../request'
 
 module Rack
   module Auth
@@ -27,7 +27,7 @@ module Rack
       end
 
       def scheme
-        @scheme ||= parts.first && parts.first.downcase
+        @scheme ||= parts.first&.downcase
       end
 
       def params

data/lib/rack/auth/basic.rb

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
-require 'rack/auth/abstract/handler'
-require 'rack/auth/abstract/request'
-require 'base64'
+require_relative 'abstract/handler'
+require_relative 'abstract/request'
 
 module Rack
   module Auth
@@ -10,8 +9,6 @@ module Rack
     #
     # Initialize with the Rack application that you want protecting,
     # and a block that checks if a username and password pair are valid.
-    #
-    # See also: <tt>example/protectedlobster.rb</tt>
 
     class Basic < AbstractHandler
 
@@ -44,11 +41,11 @@ module Rack
 
       class Request < Auth::AbstractRequest
         def basic?
-          "basic" == scheme
+          "basic" == scheme && credentials.length == 2
         end
 
         def credentials
-          @credentials ||= Base64.decode64(params).split(':', 2)
+          @credentials ||= params.unpack1('m').split(':', 2)
         end
 
         def username

data/lib/rack/bad_request.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Rack
+  # Represents a 400 Bad Request error when input data fails to meet the
+  # requirements.
+  module BadRequest
+  end
+end

data/lib/rack/body_proxy.rb

@@ -1,41 +1,63 @@
 # frozen_string_literal: true
 
 module Rack
+  # Proxy for response bodies allowing calling a block when
+  # the response body is closed (after the response has been fully
+  # sent to the client).
   class BodyProxy
+    # Set the response body to wrap, and the block to call when the
+    # response has been fully sent.
     def initialize(body, &block)
       @body = body
       @block = block
       @closed = false
     end
 
-    def respond_to?(method_name, include_all = false)
-      super or @body.respond_to?(method_name, include_all)
+    # Return whether the wrapped body responds to the method.
+    def respond_to_missing?(method_name, include_all = false)
+      case method_name
+      when :to_str
+        false
+      else
+        super or @body.respond_to?(method_name, include_all)
+      end
     end
 
+    # If not already closed, close the wrapped body and
+    # then call the block the proxy was initialized with.
     def close
       return if @closed
       @closed = true
       begin
-        @body.close if @body.respond_to? :close
+        @body.close if @body.respond_to?(:close)
       ensure
         @block.call
       end
     end
 
+    # Whether the proxy is closed.  The proxy starts as not closed,
+    # and becomes closed on the first call to close.
     def closed?
       @closed
     end
 
-    # N.B. This method is a special case to address the bug described by #434.
-    # We are applying this special case for #each only. Future bugs of this
-    # class will be handled by requesting users to patch their ruby
-    # implementation, to save adding too many methods in this class.
-    def each
-      @body.each { |body| yield body }
-    end
-
+    # Delegate missing methods to the wrapped body.
     def method_missing(method_name, *args, &block)
-      @body.__send__(method_name, *args, &block)
+      case method_name
+      when :to_str
+        super
+      when :to_ary
+        begin
+          @body.__send__(method_name, *args, &block)
+        ensure
+          close
+        end
+      else
+        @body.__send__(method_name, *args, &block)
+      end
     end
+    # :nocov:
+    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+    # :nocov:
   end
 end

data/lib/rack/builder.rb

@@ -1,76 +1,138 @@
 # frozen_string_literal: true
 
+require_relative 'urlmap'
+
+module Rack; end
+Rack::BUILDER_TOPLEVEL_BINDING = ->(builder){builder.instance_eval{binding}}
+
 module Rack
-  # Rack::Builder implements a small DSL to iteratively construct Rack
-  # applications.
+  # Rack::Builder provides a domain-specific language (DSL) to construct Rack
+  # applications. It is primarily used to parse +config.ru+ files which
+  # instantiate several middleware and a final application which are hosted
+  # by a Rack-compatible web server.
   #
   # Example:
   #
-  #  require 'rack/lobster'
-  #  app = Rack::Builder.new do
-  #    use Rack::CommonLogger
-  #    use Rack::ShowExceptions
-  #    map "/lobster" do
-  #      use Rack::Lint
-  #      run Rack::Lobster.new
-  #    end
-  #  end
+  #   app = Rack::Builder.new do
+  #     use Rack::CommonLogger
+  #     map "/ok" do
+  #       run lambda { |env| [200, {'content-type' => 'text/plain'}, ['OK']] }
+  #     end
+  #   end
   #
-  #  run app
+  #   run app
   #
   # Or
   #
-  #  app = Rack::Builder.app do
-  #    use Rack::CommonLogger
-  #    run lambda { |env| [200, {'Content-Type' => 'text/plain'}, ['OK']] }
-  #  end
+  #   app = Rack::Builder.app do
+  #     use Rack::CommonLogger
+  #     run lambda { |env| [200, {'content-type' => 'text/plain'}, ['OK']] }
+  #   end
   #
-  #  run app
+  #   run app
   #
   # +use+ adds middleware to the stack, +run+ dispatches to an application.
   # 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'
 
-    def self.parse_file(config, opts = Server::Options.new)
-      if config.end_with?('.ru')
-        return self.load_file(config, opts)
+    # 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.
+    #
+    # 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.
+    #
+    # 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
+    #   # is a 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 is a Rack application
+    def self.parse_file(path, **options)
+      if path.end_with?('.ru')
+        return self.load_file(path, **options)
       else
-        require config
-        app = Object.const_get(::File.basename(config, '.rb').split('_').map(&:capitalize).join(''))
-        return app, {}
+        require path
+        return Object.const_get(::File.basename(path, '.rb').split('_').map(&:capitalize).join(''))
       end
     end
 
-    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
+    # Load the given file as a rackup file, treating the
+    # contents as if specified inside a Rack::Builder block.
+    #
+    # 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
+    #
+    #   use Rack::ContentLength
+    #   require './app.rb'
+    #   run App
+    def self.load_file(path, **options)
+      config = ::File.read(path)
+      config.slice!(/\A#{UTF_8_BOM}/) if config.encoding == Encoding::UTF_8
 
-      if cfgfile[/^#\\(.*)/] && opts
-        options = opts.parse! $1.split(/\s+/)
+      if config[/^#\\(.*)/]
+        fail "Parsing options from the first comment line is no longer supported: #{path}"
       end
 
-      cfgfile.sub!(/^__END__\n.*\Z/m, '')
-      app = new_from_string cfgfile, path
+      config.sub!(/^__END__\n.*\Z/m, '')
 
-      return app, options
+      return new_from_string(config, path, **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, path = "(rackup)", **options)
+      builder = self.new(**options)
+
+      # 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.call(builder)
+      eval(builder_script, binding, path)
+
+      return builder.to_app
     end
 
-    def initialize(default_app = nil, &block)
-      @use, @map, @run, @warmup, @freeze_app = [], nil, default_app, nil, false
+    # 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 evaluated in the context of the instance.
+    def initialize(default_app = nil, **options, &block)
+      @use = []
+      @map = nil
+      @run = default_app
+      @warmup = nil
+      @freeze_app = false
+      @options = options
+
       instance_eval(&block) if block_given?
     end
 
+    # Any options provided to the Rack::Builder instance at initialization.
+    # These options can be server-specific. Some general options are:
+    #
+    # * +:isolation+: One of +process+, +thread+ or +fiber+. The execution
+    #   isolation model to use.
+    attr :options
+
+    # 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
@@ -89,7 +151,7 @@ module Rack
     #   end
     #
     #   use Middleware
-    #   run lambda { |env| [200, { "Content-Type" => "text/plain" }, ["OK"]] }
+    #   run lambda { |env| [200, { "content-type" => "text/plain" }, ["OK"]] }
     #
     # All requests through to this application will first be processed by the middleware class.
     # The +call+ method in this example sets an additional environment key which then can be
@@ -101,26 +163,41 @@ module Rack
       end
       @use << proc { |app| middleware.new(app, *args, &block) }
     end
+    # :nocov:
+    ruby2_keywords(:use) if respond_to?(:ruby2_keywords, true)
+    # :nocov:
 
-    # 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:
+    # Takes a block or argument that is an object that responds to #call and
+    # returns a Rack response.
+    #
+    # You can use a block:
+    #
+    #   run do |env|
+    #     [200, { "content-type" => "text/plain" }, ["Hello World!"]]
+    #   end
+    #
+    # You can also provide a lambda:
     #
-    #   run lambda { |env| [200, { "Content-Type" => "text/plain" }, ["OK"]] }
+    #   run lambda { |env| [200, { "content-type" => "text/plain" }, ["OK"]] }
     #
-    # However this could also be a class:
+    # You can also provide a class instance:
     #
     #   class Heartbeat
-    #     def self.call(env)
-    #      [200, { "Content-Type" => "text/plain" }, ["OK"]]
+    #     def call(env)
+    #      [200, { "content-type" => "text/plain" }, ["OK"]]
     #     end
     #   end
     #
-    #   run Heartbeat
-    def run(app)
-      @run = app
+    #   run Heartbeat.new
+    #
+    def run(app = nil, &block)
+      raise ArgumentError, "Both app and block given!" if app && block_given?
+
+      @run = app || block
     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)
@@ -133,25 +210,45 @@ module Rack
       @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.
+    #
+    #   class App
+    #     def call(env)
+    #       [200, {'content-type' => 'text/plain'}, ["Hello World"]]
+    #     end
+    #   end
     #
-    #   Rack::Builder.app do
-    #     map '/' do
-    #       run Heartbeat
+    #   class Heartbeat
+    #     def call(env)
+    #       [200, { "content-type" => "text/plain" }, ["OK"]]
     #     end
     #   end
     #
-    # The +use+ method can also be used here to specify middleware to run under a specific path:
+    #   app = Rack::Builder.app do
+    #     map '/heartbeat' do
+    #       run Heartbeat.new
+    #     end
+    #     run App.new
+    #   end
+    #
+    #   run app
+    #
+    # 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
+    #   app = Rack::Builder.app do
+    #     map '/heartbeat' do
     #       use Middleware
-    #       run Heartbeat
+    #       run Heartbeat.new
     #     end
+    #     run App.new
     #   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
@@ -163,6 +260,7 @@ module Rack
       @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
@@ -172,12 +270,17 @@ module Rack
       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 }

data/lib/rack/cascade.rb

@@ -1,26 +1,37 @@
 # frozen_string_literal: true
 
+require_relative 'constants'
+
 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" }, []]
-
+    # An array of applications to try in order.
     attr_reader :apps
 
-    def initialize(apps, catch = [404, 405])
+    # 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|
@@ -33,17 +44,20 @@ 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)
       @apps << app
     end
 
+    # Whether the given app is one of the apps to cascade to.
     def include?(app)
       @apps.include?(app)
     end

data/lib/rack/common_logger.rb

@@ -1,61 +1,74 @@
 # frozen_string_literal: true
 
-require 'rack/body_proxy'
+require_relative 'constants'
+require_relative 'utils'
+require_relative 'body_proxy'
+require_relative 'request'
 
 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}
 
+    # +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 = Utils.clock_time
-      status, header, body = @app.call(env)
-      header = Utils::HeaderHash.new(header)
-      body = BodyProxy.new(body) { log(env, status, header, began_at) }
-      [status, header, body]
+      status, headers, body = response = @app.call(env)
+
+      response[2] = BodyProxy.new(body) { log(env, status, headers, began_at) }
+      response
     end
 
     private
 
-    def log(env, status, header, began_at)
-      length = extract_content_length(header)
+    # Log the request to the configured logger.
+    def log(env, status, response_headers, began_at)
+      request = Rack::Request.new(env)
+      length = extract_content_length(response_headers)
 
-      msg = FORMAT % [
-        env['HTTP_X_FORWARDED_FOR'] || env["REMOTE_ADDR"] || "-",
-        env["REMOTE_USER"] || "-",
+      msg = sprintf(FORMAT,
+        request.ip || "-",
+        request.get_header("REMOTE_USER") || "-",
         Time.now.strftime("%d/%b/%Y:%H:%M:%S %z"),
-        env[REQUEST_METHOD],
-        env[PATH_INFO],
-        env[QUERY_STRING].empty? ? "" : "?#{env[QUERY_STRING]}",
-        env[SERVER_PROTOCOL],
+        request.request_method,
+        request.script_name,
+        request.path_info,
+        request.query_string.empty? ? "" : "?#{request.query_string}",
+        request.get_header(SERVER_PROTOCOL),
         status.to_s[0..3],
         length,
-        Utils.clock_time - began_at ]
+        Utils.clock_time - began_at)
+
+      msg.gsub!(/[^[:print:]\n]/) { |c| sprintf("\\x%x", c.ord) }
 
-      logger = @logger || env[RACK_ERRORS]
+      logger = @logger || request.get_header(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)
@@ -65,6 +78,8 @@ 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]
       !value || value.to_s == '0' ? '-' : value