rack 2.1.3 → 2.2.1

data/lib/rack.rb

@@ -11,23 +11,11 @@
 # All modules meant for use in your application are <tt>autoload</tt>ed here,
 # so it should be enough just to <tt>require 'rack'</tt> in your code.
 
-module Rack
-  # The Rack protocol version number implemented.
-  VERSION = [1, 3]
-
-  # Return the Rack protocol version as a dotted string.
-  def self.version
-    VERSION.join(".")
-  end
-
-  RELEASE = "2.1.3"
-
-  # Return the Rack release as a dotted string.
-  def self.release
-    RELEASE
-  end
+require_relative 'rack/version'
 
+module Rack
   HTTP_HOST         = 'HTTP_HOST'
+  HTTP_PORT         = 'HTTP_PORT'
   HTTP_VERSION      = 'HTTP_VERSION'
   HTTPS             = 'HTTPS'
   PATH_INFO         = 'PATH_INFO'
@@ -37,9 +25,9 @@ module Rack
   QUERY_STRING      = 'QUERY_STRING'
   SERVER_PROTOCOL   = 'SERVER_PROTOCOL'
   SERVER_NAME       = 'SERVER_NAME'
-  SERVER_ADDR       = 'SERVER_ADDR'
   SERVER_PORT       = 'SERVER_PORT'
   CACHE_CONTROL     = 'Cache-Control'
+  EXPIRES           = 'Expires'
   CONTENT_LENGTH    = 'Content-Length'
   CONTENT_TYPE      = 'Content-Type'
   SET_COOKIE        = 'Set-Cookie'
@@ -98,6 +86,7 @@ module Rack
   autoload :ContentLength, "rack/content_length"
   autoload :ContentType, "rack/content_type"
   autoload :ETag, "rack/etag"
+  autoload :Events, "rack/events"
   autoload :File, "rack/file"
   autoload :Files, "rack/files"
   autoload :Deflater, "rack/deflater"
@@ -108,11 +97,13 @@ module Rack
   autoload :Lint, "rack/lint"
   autoload :Lock, "rack/lock"
   autoload :Logger, "rack/logger"
+  autoload :MediaType, "rack/media_type"
   autoload :MethodOverride, "rack/method_override"
   autoload :Mime, "rack/mime"
   autoload :NullLogger, "rack/null_logger"
   autoload :Recursive, "rack/recursive"
   autoload :Reloader, "rack/reloader"
+  autoload :RewindableInput, "rack/rewindable_input"
   autoload :Runtime, "rack/runtime"
   autoload :Sendfile, "rack/sendfile"
   autoload :Server, "rack/server"

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'rack/request'
-
 module Rack
   module Auth
     class AbstractRequest

data/lib/rack/auth/basic.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'rack/auth/abstract/handler'
-require 'rack/auth/abstract/request'
+require_relative 'abstract/handler'
+require_relative 'abstract/request'
 require 'base64'
 
 module Rack
@@ -44,7 +44,7 @@ module Rack
 
       class Request < Auth::AbstractRequest
         def basic?
-          "basic" == scheme
+          "basic" == scheme && credentials.length == 2
         end
 
         def credentials

data/lib/rack/auth/digest/md5.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require 'rack/auth/abstract/handler'
-require 'rack/auth/digest/request'
-require 'rack/auth/digest/params'
-require 'rack/auth/digest/nonce'
+require_relative '../abstract/handler'
+require_relative 'request'
+require_relative 'params'
+require_relative 'nonce'
 require 'digest/md5'
 
 module Rack

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

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require 'rack/auth/abstract/request'
-require 'rack/auth/digest/params'
-require 'rack/auth/digest/nonce'
+require_relative '../abstract/request'
+require_relative 'params'
+require_relative 'nonce'
 
 module Rack
   module Auth

data/lib/rack/body_proxy.rb

@@ -1,17 +1,25 @@
 # 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)
+    # Return whether the wrapped body responds to the method.
+    def respond_to_missing?(method_name, include_all = false)
       super or @body.respond_to?(method_name, include_all)
     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
@@ -22,20 +30,16 @@ module Rack
       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)
     end
+    ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
   end
 end

data/lib/rack/builder.rb

@@ -35,6 +35,32 @@ module Rack
     # 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)
       if config.end_with?('.ru')
         return self.load_file(config, opts)
@@ -45,6 +71,25 @@ module Rack
       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 = {}
 
@@ -52,6 +97,7 @@ module Rack
       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
 
@@ -61,16 +107,26 @@ module Rack
       return app, options
     end
 
+    # 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)")
-      eval "Rack::Builder.new {\n" + builder_script + "\n}.to_app",
-        TOPLEVEL_BINDING, file, 0
+      # 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, @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
@@ -121,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)
@@ -134,25 +191,31 @@ 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.
     #
     #   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
@@ -164,6 +227,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
@@ -173,12 +237,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

@@ -2,25 +2,37 @@
 
 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
+    # 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])
+    # 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 +45,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/chunked.rb

@@ -1,53 +1,74 @@
 # frozen_string_literal: true
 
-require 'rack/utils'
-
 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}"
 
-      include Rack::Utils
-
+      # Store the response body to be chunked.
       def initialize(body)
         @body = body
       end
 
+      # 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
-        insert_trailers(&block)
-        yield TERM
+        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
 
-      def insert_trailers(&block)
+      # 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
 
-      def insert_trailers(&block)
+      # Yield strings for each trailer header.
+      def yield_trailers
         @body.trailers.each_pair do |k, v|
           yield "#{k}: #{v}\r\n"
         end
@@ -58,10 +79,11 @@ module Rack
       @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
+      # 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
@@ -69,24 +91,27 @@ module Rack
       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[SERVER_PROTOCOL]) ||
-         STATUS_WITH_NO_ENTITY_BODY.key?(status.to_i) ||
-         headers[CONTENT_LENGTH] ||
-         headers[TRANSFER_ENCODING]
-        [status, headers, body]
-      else
-        headers.delete(CONTENT_LENGTH)
         headers[TRANSFER_ENCODING] = 'chunked'
         if headers['Trailer']
-          [status, headers, TrailerBody.new(body)]
+          body = TrailerBody.new(body)
         else
-          [status, headers, Body.new(body)]
+          body = Body.new(body)
         end
       end
+
+      [status, headers, body]
     end
   end
 end