rack 3.0.5 → 3.2.0

data/lib/rack/media_type.rb

@@ -4,7 +4,7 @@ module Rack
   # Rack::MediaType parse media type and parameters out of content_type string
 
   class MediaType
-    SPLIT_PATTERN = %r{\s*[;,]\s*}
+    SPLIT_PATTERN = /[;,]/
 
     class << self
       # The media type (type/subtype) portion of the CONTENT_TYPE header
@@ -14,8 +14,11 @@ module Rack
       # For more information on the use of media types in HTTP, see:
       # http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.7
       def type(content_type)
-        return nil unless content_type
-        content_type.split(SPLIT_PATTERN, 2).first.tap(&:downcase!)
+        return nil unless content_type && !content_type.empty?
+        type = content_type.split(SPLIT_PATTERN, 2).first
+        type.rstrip!
+        type.downcase!
+        type
       end
 
       # The media type parameters provided in CONTENT_TYPE as a Hash, or
@@ -23,21 +26,27 @@ module Rack
       # provided.  e.g., when the CONTENT_TYPE is "text/plain;charset=utf-8",
       # this method responds with the following Hash:
       #   { 'charset' => 'utf-8' }
+      #
+      # This will pass back parameters with empty strings in the hash if they
+      # lack a value (e.g., "text/plain;charset=" will return { 'charset' => '' },
+      # and "text/plain;charset" will return { 'charset' => '' }, similarly to 
+      # the query params parser (barring the latter case, which returns nil instead)).
       def params(content_type)
-        return {} if content_type.nil?
+        return {} if content_type.nil? || content_type.empty?
 
         content_type.split(SPLIT_PATTERN)[1..-1].each_with_object({}) do |s, hsh|
+          s.strip!
           k, v = s.split('=', 2)
-
-          hsh[k.tap(&:downcase!)] = strip_doublequotes(v)
+          k.downcase!
+          hsh[k] = strip_doublequotes(v)
         end
       end
 
       private
 
-        def strip_doublequotes(str)
-          (str.start_with?('"') && str.end_with?('"')) ? str[1..-2] : str
-        end
+      def strip_doublequotes(str)
+        (str && str.start_with?('"') && str.end_with?('"')) ? str[1..-2] : str || ''
+      end
     end
   end
 end

data/lib/rack/mime.rb

@@ -290,7 +290,7 @@ module Rack
       ".jpg"       => "image/jpeg",
       ".jpgv"      => "video/jpeg",
       ".jpm"       => "video/jpm",
-      ".js"        => "application/javascript",
+      ".js"        => "text/javascript",
       ".json"      => "application/json",
       ".karbon"    => "application/vnd.kde.karbon",
       ".kfo"       => "application/vnd.kde.kformula",
@@ -338,6 +338,7 @@ module Rack
       ".mif"       => "application/vnd.mif",
       ".mime"      => "message/rfc822",
       ".mj2"       => "video/mj2",
+      ".mjs"       => "text/javascript",
       ".mlp"       => "application/vnd.dolby.mlp",
       ".mmd"       => "application/vnd.chipnuts.karaoke-mmd",
       ".mmf"       => "application/vnd.smaf",
@@ -409,7 +410,7 @@ module Rack
       ".ogx"       => "application/ogg",
       ".org"       => "application/vnd.lotus-organizer",
       ".otc"       => "application/vnd.oasis.opendocument.chart-template",
-      ".otf"       => "application/vnd.oasis.opendocument.formula-template",
+      ".otf"       => "font/otf",
       ".otg"       => "application/vnd.oasis.opendocument.graphics-template",
       ".oth"       => "application/vnd.oasis.opendocument.text-web",
       ".oti"       => "application/vnd.oasis.opendocument.image-template",
@@ -590,7 +591,7 @@ module Rack
       ".trm"       => "application/x-msterminal",
       ".ts"        => "video/mp2t",
       ".tsv"       => "text/tab-separated-values",
-      ".ttf"       => "application/octet-stream",
+      ".ttf"       => "font/ttf",
       ".twd"       => "application/vnd.simtech-mindmapper",
       ".txd"       => "application/vnd.genomatix.tuxedo",
       ".txf"       => "application/vnd.mobius.txf",
@@ -636,8 +637,8 @@ module Rack
       ".wmv"       => "video/x-ms-wmv",
       ".wmx"       => "video/x-ms-wmx",
       ".wmz"       => "application/x-ms-wmz",
-      ".woff"      => "application/font-woff",
-      ".woff2"     => "application/font-woff2",
+      ".woff"      => "font/woff",
+      ".woff2"     => "font/woff2",
       ".wpd"       => "application/vnd.wordperfect",
       ".wpl"       => "application/vnd.ms-wpl",
       ".wps"       => "application/vnd.ms-works",

data/lib/rack/mock_request.rb

@@ -41,11 +41,6 @@ module Rack
       end
     end
 
-    DEFAULT_ENV = {
-      RACK_INPUT        => StringIO.new,
-      RACK_ERRORS       => StringIO.new,
-    }.freeze
-
     def initialize(app)
       @app = app
     end
@@ -104,7 +99,7 @@ module Rack
       uri = parse_uri_rfc2396(uri)
       uri.path = "/#{uri.path}" unless uri.path[0] == ?/
 
-      env = DEFAULT_ENV.dup
+      env = {}
 
       env[REQUEST_METHOD]  = (opts[:method] ? opts[:method].to_s.upcase : GET).b
       env[SERVER_NAME]     = (uri.host || "example.org").b
@@ -144,20 +139,20 @@ module Rack
         end
       end
 
-      opts[:input] ||= String.new
-      if String === opts[:input]
-        rack_input = StringIO.new(opts[:input])
-      else
-        rack_input = opts[:input]
+      rack_input = opts[:input]
+      if String === rack_input
+        rack_input = StringIO.new(rack_input)
       end
 
-      rack_input.set_encoding(Encoding::BINARY)
-      env[RACK_INPUT] = rack_input
+      if rack_input
+        rack_input.set_encoding(Encoding::BINARY) if rack_input.respond_to?(:set_encoding)
+        env[RACK_INPUT] = rack_input
 
-      env["CONTENT_LENGTH"] ||= env[RACK_INPUT].size.to_s if env[RACK_INPUT].respond_to?(:size)
+        env["CONTENT_LENGTH"] ||= env[RACK_INPUT].size.to_s if env[RACK_INPUT].respond_to?(:size)
+      end
 
       opts.each { |field, value|
-        env[field] = value  if String === field
+        env[field] = value if String === field
       }
 
       env

data/lib/rack/mock_response.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'cgi/cookie'
 require 'time'
 
 require_relative 'response'
@@ -11,6 +10,30 @@ module Rack
   # MockRequest.
 
   class MockResponse < Rack::Response
+    class Cookie
+      attr_reader :name, :value, :path, :domain, :expires, :secure
+
+      def initialize(args)
+        @name = args["name"]
+        @value = args["value"]
+        @path = args["path"]
+        @domain = args["domain"]
+        @expires = args["expires"]
+        @secure = args["secure"]
+      end
+
+      def method_missing(method_name, *args, &block)
+        @value.send(method_name, *args, &block)
+      end
+      # :nocov:
+      ruby2_keywords(:method_missing) if respond_to?(:ruby2_keywords, true)
+      # :nocov:
+
+      def respond_to_missing?(method_name, include_all = false)
+        @value.respond_to?(method_name, include_all) || super
+      end
+    end
+
     class << self
       alias [] new
     end
@@ -78,22 +101,20 @@ module Rack
 
     def parse_cookies_from_header
       cookies = Hash.new
-      if headers.has_key? 'set-cookie'
-        set_cookie_header = headers.fetch('set-cookie')
-        Array(set_cookie_header).each do |header_value|
-          header_value.split("\n").each do |cookie|
-            cookie_name, cookie_filling = cookie.split('=', 2)
-            cookie_attributes = identify_cookie_attributes cookie_filling
-            parsed_cookie = CGI::Cookie.new(
-              'name' => cookie_name.strip,
-              'value' => cookie_attributes.fetch('value'),
-              'path' => cookie_attributes.fetch('path', nil),
-              'domain' => cookie_attributes.fetch('domain', nil),
-              'expires' => cookie_attributes.fetch('expires', nil),
-              'secure' => cookie_attributes.fetch('secure', false)
-            )
-            cookies.store(cookie_name, parsed_cookie)
-          end
+      set_cookie_header = headers['set-cookie']
+      if set_cookie_header && !set_cookie_header.empty?
+        Array(set_cookie_header).each do |cookie|
+          cookie_name, cookie_filling = cookie.split('=', 2)
+          cookie_attributes = identify_cookie_attributes cookie_filling
+          parsed_cookie = Cookie.new(
+            'name' => cookie_name.strip,
+            'value' => cookie_attributes.fetch('value'),
+            'path' => cookie_attributes.fetch('path', nil),
+            'domain' => cookie_attributes.fetch('domain', nil),
+            'expires' => cookie_attributes.fetch('expires', nil),
+            'secure' => cookie_attributes.fetch('secure', false)
+          )
+          cookies.store(cookie_name, parsed_cookie)
         end
       end
       cookies
@@ -102,7 +123,7 @@ module Rack
     def identify_cookie_attributes(cookie_filling)
       cookie_bits = cookie_filling.split(';')
       cookie_attributes = Hash.new
-      cookie_attributes.store('value', cookie_bits[0].strip)
+      cookie_attributes.store('value', Array(cookie_bits[0].strip))
       cookie_bits.drop(1).each do |bit|
         if bit.include? '='
           cookie_attribute, attribute_value = bit.split('=', 2)

data/lib/rack/multipart/parser.rb

@@ -3,51 +3,60 @@
 require 'strscan'
 
 require_relative '../utils'
+require_relative '../bad_request'
 
 module Rack
   module Multipart
-    class MultipartPartLimitError < Errno::EMFILE; end
+    class MultipartPartLimitError < Errno::EMFILE
+      include BadRequest
+    end
 
-    class MultipartTotalPartLimitError < StandardError; end
+    class MultipartTotalPartLimitError < StandardError
+      include BadRequest
+    end
 
     # Use specific error class when parsing multipart request
     # that ends early.
-    class EmptyContentError < ::EOFError; end
+    class EmptyContentError < ::EOFError
+      include BadRequest
+    end
 
     # Base class for multipart exceptions that do not subclass from
     # other exception classes for backwards compatibility.
-    class Error < StandardError; end
+    class BoundaryTooLongError < StandardError
+      include BadRequest
+    end
+
+    # Prefer to use the BoundaryTooLongError class or Rack::BadRequest.
+    Error = BoundaryTooLongError
 
     EOL = "\r\n"
+    FWS = /[ \t]+(?:\r\n[ \t]+)?/ # whitespace with optional folding
+    HEADER_VALUE = "(?:[^\r\n]|\r\n[ \t])*" # anything but a non-folding CRLF
     MULTIPART = %r|\Amultipart/.*boundary=\"?([^\";,]+)\"?|ni
-    TOKEN = /[^\s()<>,;:\\"\/\[\]?=]+/
-    CONDISP = /Content-Disposition:\s*#{TOKEN}\s*/i
-    VALUE = /"(?:\\"|[^"])*"|#{TOKEN}/
-    BROKEN = /^#{CONDISP}.*;\s*filename=(#{VALUE})/i
-    MULTIPART_CONTENT_TYPE = /Content-Type: (.*)#{EOL}/ni
-    MULTIPART_CONTENT_DISPOSITION = /Content-Disposition:[^:]*;\s*name=(#{VALUE})/ni
-    MULTIPART_CONTENT_ID = /Content-ID:\s*([^#{EOL}]*)/ni
-    # Updated definitions from RFC 2231
-    ATTRIBUTE_CHAR = %r{[^ \x00-\x1f\x7f)(><@,;:\\"/\[\]?='*%]}
-    ATTRIBUTE = /#{ATTRIBUTE_CHAR}+/
-    SECTION = /\*[0-9]+/
-    REGULAR_PARAMETER_NAME = /#{ATTRIBUTE}#{SECTION}?/
-    REGULAR_PARAMETER = /(#{REGULAR_PARAMETER_NAME})=(#{VALUE})/
-    EXTENDED_OTHER_NAME = /#{ATTRIBUTE}\*[1-9][0-9]*\*/
-    EXTENDED_OTHER_VALUE = /%[0-9a-fA-F]{2}|#{ATTRIBUTE_CHAR}/
-    EXTENDED_OTHER_PARAMETER = /(#{EXTENDED_OTHER_NAME})=(#{EXTENDED_OTHER_VALUE}*)/
-    EXTENDED_INITIAL_NAME = /#{ATTRIBUTE}(?:\*0)?\*/
-    EXTENDED_INITIAL_VALUE = /[a-zA-Z0-9\-]*'[a-zA-Z0-9\-]*'#{EXTENDED_OTHER_VALUE}*/
-    EXTENDED_INITIAL_PARAMETER = /(#{EXTENDED_INITIAL_NAME})=(#{EXTENDED_INITIAL_VALUE})/
-    EXTENDED_PARAMETER = /#{EXTENDED_INITIAL_PARAMETER}|#{EXTENDED_OTHER_PARAMETER}/
-    DISPPARM = /;\s*(?:#{REGULAR_PARAMETER}|#{EXTENDED_PARAMETER})\s*/
-    RFC2183 = /^#{CONDISP}(#{DISPPARM})+$/i
-
+    MULTIPART_CONTENT_TYPE = /^Content-Type:#{FWS}?(#{HEADER_VALUE})/ni
+    MULTIPART_CONTENT_DISPOSITION = /^Content-Disposition:#{FWS}?(#{HEADER_VALUE})/ni
+    MULTIPART_CONTENT_ID = /^Content-ID:#{FWS}?(#{HEADER_VALUE})/ni
+
+    # Rack::Multipart::Parser handles parsing of multipart/form-data requests.
+    #
+    # File Parameter Contents
+    #
+    # When processing file uploads, the parser returns a hash containing
+    # information about uploaded files. For +file+ parameters, the hash includes:
+    #
+    # * +:filename+ - The original filename, already URL decoded by the parser
+    # * +:type+ - The content type of the uploaded file  
+    # * +:name+ - The parameter name from the form
+    # * +:tempfile+ - A Tempfile object containing the uploaded data
+    # * +:head+ - The raw header content for this part
     class Parser
       BUFSIZE = 1_048_576
       TEXT_PLAIN = "text/plain"
       TEMPFILE_FACTORY = lambda { |filename, content_type|
-        Tempfile.new(["RackMultipart", ::File.extname(filename.gsub("\0", '%00'))])
+        extension = ::File.extname(filename.gsub("\0", '%00'))[0, 129]
+
+        Tempfile.new(["RackMultipart", extension])
       }
 
       class BoundedIO # :nodoc:
@@ -98,7 +107,7 @@ module Rack
         if boundary.length > 70
           # RFC 1521 Section 7.2.1 imposes a 70 character maximum for the boundary.
           # Most clients use no more than 55 characters.
-          raise Error, "multipart boundary size too large (#{boundary.length} characters)"
+          raise BoundaryTooLongError, "multipart boundary size too large (#{boundary.length} characters)"
         end
 
         io = BoundedIO.new(io, content_length) if content_length
@@ -213,6 +222,8 @@ module Rack
 
         @sbuf = StringScanner.new("".dup)
         @body_regex = /(?:#{EOL}|\A)--#{Regexp.quote(boundary)}(?:#{EOL}|--)/m
+        @body_regex_at_end = /#{@body_regex}\z/m
+        @end_boundary_size = boundary.bytesize + 4 # (-- at start, -- at finish)
         @rx_max_size = boundary.bytesize + 6 # (\r\n-- at start, either \r\n or -- at finish)
         @head_regex = /(.*?#{EOL})#{EOL}/m
       end
@@ -244,7 +255,8 @@ module Rack
         @collector.each do |part|
           part.get_data do |data|
             tag_multipart_encoding(part.filename, part.content_type, part.name, data)
-            @query_parser.normalize_params(@params, part.name, data)
+            name, data = handle_dummy_encoding(part.name, data)
+            @query_parser.normalize_params(@params, name, data)
           end
         end
         MultipartInfo.new @params.to_params_hash, @collector.find_all(&:file?).map(&:body)
@@ -252,12 +264,6 @@ module Rack
 
       private
 
-      def dequote(str) # From WEBrick::HTTPUtils
-        ret = (/\A"(.*)"\Z/ =~ str) ? $1 : str.dup
-        ret.gsub!(/\\(.)/, "\\1")
-        ret
-      end
-
       def read_data(io, outbuf)
         content = io.read(@bufsize, outbuf)
         handle_empty_content!(content)
@@ -279,7 +285,14 @@ module Rack
             @state = :MIME_HEAD
             return
           when :END_BOUNDARY
-            # invalid multipart upload, but retry for opening boundary
+            # invalid multipart upload
+            if @sbuf.pos == @end_boundary_size && @sbuf.rest == EOL
+              # stop parsing a buffer if a buffer is only an end boundary.
+              @state = :DONE
+              return
+            end
+
+            # retry for opening boundary
           else
             # no boundary found, keep reading data
             return :want_read
@@ -297,17 +310,101 @@ module Rack
         end
       end
 
+      CONTENT_DISPOSITION_MAX_PARAMS = 16
+      CONTENT_DISPOSITION_MAX_BYTES = 1536
       def handle_mime_head
         if @sbuf.scan_until(@head_regex)
           head = @sbuf[1]
           content_type = head[MULTIPART_CONTENT_TYPE, 1]
-          if name = head[MULTIPART_CONTENT_DISPOSITION, 1]
-            name = dequote(name)
+          if (disposition = head[MULTIPART_CONTENT_DISPOSITION, 1]) &&
+              disposition.bytesize <= CONTENT_DISPOSITION_MAX_BYTES
+
+            # ignore actual content-disposition value (should always be form-data)
+            i = disposition.index(';')
+            disposition.slice!(0, i+1)
+            param = nil
+            num_params = 0
+
+            # Parse parameter list
+            while i = disposition.index('=')
+              # Only parse up to max parameters, to avoid potential denial of service
+              num_params += 1
+              break if num_params > CONTENT_DISPOSITION_MAX_PARAMS
+
+              # Found end of parameter name, ensure forward progress in loop
+              param = disposition.slice!(0, i+1)
+
+              # Remove ending equals and preceding whitespace from parameter name
+              param.chomp!('=')
+              param.lstrip!
+
+              if disposition[0] == '"'
+                # Parameter value is quoted, parse it, handling backslash escapes
+                disposition.slice!(0, 1)
+                value = String.new
+
+                while i = disposition.index(/(["\\])/)
+                  c = $1
+
+                  # Append all content until ending quote or escape
+                  value << disposition.slice!(0, i)
+
+                  # Remove either backslash or ending quote,
+                  # ensures forward progress in loop
+                  disposition.slice!(0, 1)
+
+                  # stop parsing parameter value if found ending quote
+                  break if c == '"'
+
+                  escaped_char = disposition.slice!(0, 1)
+                  if param == 'filename' && escaped_char != '"'
+                    # Possible IE uploaded filename, append both escape backslash and value
+                    value << c << escaped_char
+                  else
+                    # Other only append escaped value
+                    value << escaped_char
+                  end
+                end
+              else
+                if i = disposition.index(';')
+                  # Parameter value unquoted (which may be invalid), value ends at semicolon
+                  value = disposition.slice!(0, i)
+                else
+                  # If no ending semicolon, assume remainder of line is value and stop
+                  # parsing
+                  disposition.strip!
+                  value = disposition
+                  disposition = ''
+                end
+              end
+
+              case param
+              when 'name'
+                name = value
+              when 'filename'
+                filename = value
+              when 'filename*'
+                filename_star = value
+              # else
+              # ignore other parameters
+              end
+
+              # skip trailing semicolon, to proceed to next parameter
+              if i = disposition.index(';')
+                disposition.slice!(0, i+1)
+              end
+            end
           else
             name = head[MULTIPART_CONTENT_ID, 1]
           end
 
-          filename = get_filename(head)
+          if filename_star
+            encoding, _, filename = filename_star.split("'", 3)
+            filename = normalize_filename(filename || '')
+            filename.force_encoding(find_encoding(encoding))
+          elsif filename
+            filename = normalize_filename(filename)
+          end
 
           if name.nil? || name.empty?
             name = filename || "#{content_type || TEXT_PLAIN}[]".dup
@@ -322,7 +419,7 @@ module Rack
 
       def handle_mime_body
         if (body_with_boundary = @sbuf.check_until(@body_regex)) # check but do not advance the pointer yet
-          body = body_with_boundary.sub(/#{@body_regex}\z/m, '') # remove the boundary from the string
+          body = body_with_boundary.sub(@body_regex_at_end, '') # remove the boundary from the string
           @collector.on_mime_body @mime_index, body
           @sbuf.pos += body.length + 2 # skip \r\n after the content
           @state = :CONSUME_TOKEN
@@ -352,39 +449,14 @@ module Rack
         end
       end
 
-      def get_filename(head)
-        filename = nil
-        case head
-        when RFC2183
-          params = Hash[*head.scan(DISPPARM).flat_map(&:compact)]
-
-          if filename = params['filename*']
-            encoding, _, filename = filename.split("'", 3)
-          elsif filename = params['filename']
-            filename = $1 if filename =~ /^"(.*)"$/
-          end
-        when BROKEN
-          filename = $1
-          filename = $1 if filename =~ /^"(.*)"$/
-        end
-
-        return unless filename
-
+      def normalize_filename(filename)
         if filename.scan(/%.?.?/).all? { |s| /%[0-9a-fA-F]{2}/.match?(s) }
           filename = Utils.unescape_path(filename)
         end
 
         filename.scrub!
 
-        if filename !~ /\\[^\\"]/
-          filename = filename.gsub(/\\(.)/, '\1')
-        end
-
-        if encoding
-          filename.force_encoding ::Encoding.find(encoding)
-        end
-
-        filename
+        filename.split(/[\/\\]/).last || String.new
       end
 
       CHARSET = "charset"
@@ -410,11 +482,7 @@ module Rack
               v.strip!
               v = v[1..-2] if v.start_with?('"') && v.end_with?('"')
               if k == "charset"
-                encoding = begin
-                  Encoding.find v
-                rescue ArgumentError
-                  Encoding::BINARY
-                end
+                encoding = find_encoding(v)
               end
             end
           end
@@ -424,6 +492,34 @@ module Rack
         body.force_encoding(encoding)
       end
 
+      # Return the related Encoding object. However, because
+      # enc is submitted by the user, it may be invalid, so
+      # use a binary encoding in that case.
+      def find_encoding(enc)
+        Encoding.find enc
+      rescue ArgumentError
+        Encoding::BINARY
+      end
+
+      REENCODE_DUMMY_ENCODINGS = {
+        # ISO-2022-JP is a legacy but still widely used encoding in Japan
+        # Here we convert ISO-2022-JP to UTF-8 so that it can be handled.
+        Encoding::ISO_2022_JP => true
+
+        # Other dummy encodings are rarely used and have not been supported yet.
+        # Adding support for them will require careful considerations.
+      }
+
+      def handle_dummy_encoding(name, body)
+        # A string object with a 'dummy' encoding does not have full functionality and can cause errors.
+        # So here we covert it to UTF-8 so that it can be handled properly.
+        if name.encoding.dummy? && REENCODE_DUMMY_ENCODINGS[name.encoding]
+          name = name.encode(Encoding::UTF_8)
+          body = body.encode(Encoding::UTF_8)
+        end
+        return name, body
+      end
+
       def handle_empty_content!(content)
         if content.nil? || content.empty?
           raise EmptyContentError

data/lib/rack/multipart/uploaded_file.rb

@@ -5,14 +5,47 @@ require 'fileutils'
 
 module Rack
   module Multipart
+    # Despite the misleading name, UploadedFile is designed for use for
+    # preparing multipart file upload bodies, generally for use in tests.
+    # It is not designed for and should not be used for handling uploaded
+    # files (there is no need for that, since Rack's multipart parser
+    # already creates Tempfiles for that). Using this with non-trusted
+    # filenames can create a security vulnerability.
+    #
+    # You should only use this class if you plan on passing the instances
+    # to Rack::MockRequest for use in creating multipart request bodies.
+    #
+    # UploadedFile delegates most methods to the tempfile it contains.
     class UploadedFile
-
-      # The filename, *not* including the path, of the "uploaded" file
+      # The provided name of the file. This generally is the basename of
+      # path provided during initialization, but it can contain slashes if they
+      # were present in the filename argument when the instance was created.
       attr_reader :original_filename
 
-      # The content type of the "uploaded" file
+      # The content type of the instance.
       attr_accessor :content_type
 
+      # Create a new UploadedFile.  For backwards compatibility, this accepts
+      # both positional and keyword versions of the same arguments:
+      #
+      # filepath/path :: The path to the file
+      # ct/content_type :: The content_type of the file
+      # bin/binary :: Whether to set binmode on the file before copying data into it.
+      #
+      # If both positional and keyword arguments are present, the keyword arguments
+      # take precedence.
+      #
+      # The following keyword-only arguments are also accepted:
+      #
+      # filename :: Override the filename to use for the file.  This is so the
+      #             filename for the upload does not need to match the basename of
+      #             the file path.  This should not contain slashes, unless you are
+      #             trying to test how an application handles invalid filenames in
+      #             multipart upload bodies.
+      # io :: Use the given IO-like instance as the tempfile, instead of creating
+      #       a Tempfile instance.  This is useful for building multipart file
+      #       upload bodies without a file being present on the filesystem. If you are
+      #       providing this, you should also provide the filename argument.
       def initialize(filepath = nil, ct = "text/plain", bin = false,
                      path: filepath, content_type: ct, binary: bin, filename: nil, io: nil)
         if io
@@ -28,15 +61,19 @@ module Rack
         @content_type = content_type
       end
 
+      # The path of the tempfile for the instance, if the tempfile has a path.
+      # nil if the tempfile does not have a path.
       def path
         @tempfile.path if @tempfile.respond_to?(:path)
       end
       alias_method :local_path, :path
 
-      def respond_to?(*args)
-        super or @tempfile.respond_to?(*args)
+      # Return true if the tempfile responds to the method.
+      def respond_to_missing?(*args)
+        @tempfile.respond_to?(*args)
       end
 
+      # Delegate method missing calls to the tempfile.
       def method_missing(method_name, *args, &block) #:nodoc:
         @tempfile.__send__(method_name, *args, &block)
       end