actionpack 4.1.7 → 4.2.1

data/lib/action_dispatch/middleware/debug_exceptions.rb

@@ -35,14 +35,25 @@ module ActionDispatch
 
       if env['action_dispatch.show_detailed_exceptions']
         request = Request.new(env)
+        traces = wrapper.traces
+
+        trace_to_show = 'Application Trace'
+        if traces[trace_to_show].empty? && wrapper.rescue_template != 'routing_error'
+          trace_to_show = 'Full Trace'
+        end
+
+        if source_to_show = traces[trace_to_show].first
+          source_to_show_id = source_to_show[:id]
+        end
+
         template = ActionView::Base.new([RESCUES_TEMPLATE_PATH],
           request: request,
           exception: wrapper.exception,
-          application_trace: wrapper.application_trace,
-          framework_trace: wrapper.framework_trace,
-          full_trace: wrapper.full_trace,
+          traces: traces,
+          show_source_idx: source_to_show_id,
+          trace_to_show: trace_to_show,
           routes_inspector: routes_inspector(exception),
-          source_extract: wrapper.source_extract,
+          source_extracts: wrapper.source_extracts,
           line_number: wrapper.line_number,
           file: wrapper.file
         )

data/lib/action_dispatch/middleware/exception_wrapper.rb

@@ -6,16 +6,17 @@ module ActionDispatch
     cattr_accessor :rescue_responses
     @@rescue_responses = Hash.new(:internal_server_error)
     @@rescue_responses.merge!(
-      'ActionController::RoutingError'             => :not_found,
-      'AbstractController::ActionNotFound'         => :not_found,
-      'ActionController::MethodNotAllowed'         => :method_not_allowed,
-      'ActionController::UnknownHttpMethod'        => :method_not_allowed,
-      'ActionController::NotImplemented'           => :not_implemented,
-      'ActionController::UnknownFormat'            => :not_acceptable,
-      'ActionController::InvalidAuthenticityToken' => :unprocessable_entity,
-      'ActionDispatch::ParamsParser::ParseError'   => :bad_request,
-      'ActionController::BadRequest'               => :bad_request,
-      'ActionController::ParameterMissing'         => :bad_request
+      'ActionController::RoutingError'                => :not_found,
+      'AbstractController::ActionNotFound'            => :not_found,
+      'ActionController::MethodNotAllowed'            => :method_not_allowed,
+      'ActionController::UnknownHttpMethod'           => :method_not_allowed,
+      'ActionController::NotImplemented'              => :not_implemented,
+      'ActionController::UnknownFormat'               => :not_acceptable,
+      'ActionController::InvalidAuthenticityToken'    => :unprocessable_entity,
+      'ActionController::InvalidCrossOriginRequest'   => :unprocessable_entity,
+      'ActionDispatch::ParamsParser::ParseError'      => :bad_request,
+      'ActionController::BadRequest'                  => :bad_request,
+      'ActionController::ParameterMissing'            => :bad_request
     )
 
     cattr_accessor :rescue_templates
@@ -56,21 +57,52 @@ module ActionDispatch
       clean_backtrace(:all)
     end
 
+    def traces
+      appplication_trace_with_ids = []
+      framework_trace_with_ids = []
+      full_trace_with_ids = []
+
+      full_trace.each_with_index do |trace, idx|
+        trace_with_id = { id: idx, trace: trace }
+
+        if application_trace.include?(trace)
+          appplication_trace_with_ids << trace_with_id
+        else
+          framework_trace_with_ids << trace_with_id
+        end
+
+        full_trace_with_ids << trace_with_id
+      end
+
+      {
+        "Application Trace" => appplication_trace_with_ids,
+        "Framework Trace" => framework_trace_with_ids,
+        "Full Trace" => full_trace_with_ids
+      }
+    end
+
     def self.status_code_for_exception(class_name)
       Rack::Utils.status_code(@@rescue_responses[class_name])
     end
 
-    def source_extract
-      if application_trace && trace = application_trace.first
-        file, line, _ = trace.split(":")
-        @file = file
-        @line_number = line.to_i
-        source_fragment(@file, @line_number)
+    def source_extracts
+      backtrace.map do |trace|
+        file, line = trace.split(":")
+        line_number = line.to_i
+
+        {
+          code: source_fragment(file, line_number),
+          line_number: line_number
+        }
       end
     end
 
     private
 
+    def backtrace
+      Array(@exception.backtrace)
+    end
+
     def original_exception(exception)
       if registered_original_exception?(exception)
         exception.original_exception
@@ -85,9 +117,9 @@ module ActionDispatch
 
     def clean_backtrace(*args)
       if backtrace_cleaner
-        backtrace_cleaner.clean(@exception.backtrace, *args)
+        backtrace_cleaner.clean(backtrace, *args)
       else
-        @exception.backtrace
+        backtrace
       end
     end
 

data/lib/action_dispatch/middleware/flash.rb

@@ -10,7 +10,7 @@ module ActionDispatch
     end
   end
 
-  # The flash provides a way to pass temporary objects between actions. Anything you place in the flash will be exposed
+  # The flash provides a way to pass temporary primitive-types (String, Array, Hash) between actions. Anything you place in the flash will be exposed
   # to the very next action and then cleared out. This is a great way of doing notices and alerts, such as a create
   # action that sets <tt>flash[:notice] = "Post successfully created"</tt> before redirecting to a display action that can
   # then expose the flash to its template. Actually, that exposure is automatically done.
@@ -37,8 +37,11 @@ module ActionDispatch
   #   flash.alert = "You must be logged in"
   #   flash.notice = "Post successfully created"
   #
-  # This example just places a string in the flash, but you can put any object in there. And of course, you can put as
-  # many as you like at a time too. Just remember: They'll be gone by the time the next action has been performed.
+  # This example places a string in the flash. And of course, you can put as many as you like at a time too. If you want to pass
+  # non-primitive types, you will have to handle that in your application. Example: To show messages with links, you will have to
+  # use sanitize helper.
+  #
+  # Just remember: They'll be gone by the time the next action has been performed.
   #
   # See docs on the FlashHash class for more details about the flash.
   class Flash
@@ -76,7 +79,7 @@ module ActionDispatch
     class FlashHash
       include Enumerable
 
-      def self.from_session_value(value)
+      def self.from_session_value(value) #:nodoc:
         flash = case value
                 when FlashHash # Rails 3.1, 3.2
                   new(value.instance_variable_get(:@flashes), value.instance_variable_get(:@used))
@@ -88,8 +91,11 @@ module ActionDispatch
 
         flash.tap(&:sweep)
       end
-
-      def to_session_value
+      
+      # Builds a hash containing the discarded values and the hashes
+      # representing the flashes.
+      # If there are no values in @flashes, returns nil.
+      def to_session_value #:nodoc:
         return nil if empty?
         {'discard' => @discard.to_a, 'flashes' => @flashes}
       end
@@ -129,7 +135,7 @@ module ActionDispatch
       end
 
       def key?(name)
-        @flashes.key? name
+        @flashes.key? name.to_s
       end
 
       def delete(key)

data/lib/action_dispatch/middleware/params_parser.rb

@@ -47,7 +47,7 @@ module ActionDispatch
         else
           false
         end
-      rescue Exception => e # JSON or Ruby code block errors
+      rescue => e # JSON or Ruby code block errors
         logger(env).debug "Error occurred while parsing request parameters.\nContents:\n\n#{request.raw_post}"
 
         raise ParseError.new(e.message, e)

data/lib/action_dispatch/middleware/public_exceptions.rb

@@ -1,4 +1,14 @@
 module ActionDispatch
+  # When called, this middleware renders an error page. By default if an HTML
+  # response is expected it will render static error pages from the `/public`
+  # directory. For example when this middleware receives a 500 response it will
+  # render the template found in `/public/500.html`.
+  # If an internationalized locale is set, this middleware will attempt to render
+  # the template in `/public/500.<locale>.html`. If an internationalized template
+  # is not found it will fall back on `/public/500.html`.
+  #
+  # When a request with a content type other than HTML is made, this middleware
+  # will attempt to convert error information into the appropriate response type.
   class PublicExceptions
     attr_accessor :public_path
 
@@ -32,9 +42,8 @@ module ActionDispatch
     end
 
     def render_html(status)
-      found = false
-      path = "#{public_path}/#{status}.#{I18n.locale}.html" if I18n.locale
-      path = "#{public_path}/#{status}.html" unless path && (found = File.exist?(path))
+      path = "#{public_path}/#{status}.#{I18n.locale}.html"
+      path = "#{public_path}/#{status}.html" unless (found = File.exist?(path))
 
       if found || File.exist?(path)
         render_format(status, 'text/html', File.read(path))

data/lib/action_dispatch/middleware/remote_ip.rb

@@ -1,3 +1,5 @@
+require 'ipaddr'
+
 module ActionDispatch
   # This middleware calculates the IP address of the remote client that is
   # making the request. It does this by checking various headers that could
@@ -11,7 +13,7 @@ module ActionDispatch
   # Some Rack servers concatenate repeated headers, like {HTTP RFC 2616}[http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2]
   # requires. Some Rack servers simply drop preceding headers, and only report
   # the value that was {given in the last header}[http://andre.arko.net/2011/12/26/repeated-headers-and-ruby-web-servers].
-  # If you are behind multiple proxy servers (like Nginx to HAProxy to Unicorn)
+  # If you are behind multiple proxy servers (like NGINX to HAProxy to Unicorn)
   # then you should test your Rack server to make sure your data is good.
   #
   # IF YOU DON'T USE A PROXY, THIS MAKES YOU VULNERABLE TO IP SPOOFING.
@@ -28,14 +30,14 @@ module ActionDispatch
     # guaranteed by the IP specification to be private addresses. Those will
     # not be the ultimate client IP in production, and so are discarded. See
     # http://en.wikipedia.org/wiki/Private_network for details.
-    TRUSTED_PROXIES = %r{
-      ^127\.0\.0\.1$                | # localhost IPv4
-      ^::1$                         | # localhost IPv6
-      ^fc00:                        | # private IPv6 range fc00
-      ^10\.                         | # private IPv4 range 10.x.x.x
-      ^172\.(1[6-9]|2[0-9]|3[0-1])\.| # private IPv4 range 172.16.0.0 .. 172.31.255.255
-      ^192\.168\.                     # private IPv4 range 192.168.x.x
-    }x
+    TRUSTED_PROXIES = [
+      "127.0.0.1",      # localhost IPv4
+      "::1",            # localhost IPv6
+      "fc00::/7",       # private IPv6 range fc00::/7
+      "10.0.0.0/8",     # private IPv4 range 10.x.x.x
+      "172.16.0.0/12",  # private IPv4 range 172.16.0.0 .. 172.31.255.255
+      "192.168.0.0/16", # private IPv4 range 192.168.x.x
+    ].map { |proxy| IPAddr.new(proxy) }
 
     attr_reader :check_ip, :proxies
 
@@ -47,24 +49,24 @@ module ActionDispatch
     # clients (like WAP devices), or behind proxies that set headers in an
     # incorrect or confusing way (like AWS ELB).
     #
-    # The +custom_proxies+ argument can take a regex, which will be used
-    # instead of +TRUSTED_PROXIES+, or a string, which will be used in addition
-    # to +TRUSTED_PROXIES+. Any proxy setup will put the value you want in the
-    # middle (or at the beginning) of the X-Forwarded-For list, with your proxy
-    # servers after it. If your proxies aren't removed, pass them in via the
-    # +custom_proxies+ parameter. That way, the middleware will ignore those
-    # IP addresses, and return the one that you want.
+    # The +custom_proxies+ argument can take an Array of string, IPAddr, or
+    # Regexp objects which will be used instead of +TRUSTED_PROXIES+. If a
+    # single string, IPAddr, or Regexp object is provided, it will be used in
+    # addition to +TRUSTED_PROXIES+. Any proxy setup will put the value you
+    # want in the middle (or at the beginning) of the X-Forwarded-For list,
+    # with your proxy servers after it. If your proxies aren't removed, pass
+    # them in via the +custom_proxies+ parameter. That way, the middleware will
+    # ignore those IP addresses, and return the one that you want.
     def initialize(app, check_ip_spoofing = true, custom_proxies = nil)
       @app = app
       @check_ip = check_ip_spoofing
-      @proxies = case custom_proxies
-        when Regexp
-          custom_proxies
-        when nil
-          TRUSTED_PROXIES
-        else
-          Regexp.union(TRUSTED_PROXIES, custom_proxies)
-        end
+      @proxies = if custom_proxies.blank?
+        TRUSTED_PROXIES
+      elsif custom_proxies.respond_to?(:any?)
+        custom_proxies
+      else
+        Array(custom_proxies) + TRUSTED_PROXIES
+      end
     end
 
     # Since the IP address may not be needed, we store the object here
@@ -80,32 +82,6 @@ module ActionDispatch
     # into an actual IP address. If the ActionDispatch::Request#remote_ip method
     # is called, this class will calculate the value and then memoize it.
     class GetIp
-
-      # This constant contains a regular expression that validates every known
-      # form of IP v4 and v6 address, with or without abbreviations, adapted
-      # from {this gist}[https://gist.github.com/gazay/1289635].
-      VALID_IP = %r{
-        (^(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[0-9]{1,2})(\.(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[0-9]{1,2})){3}$)                                                        | # ip v4
-        (^(
-        (([0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4})                                                                                                                   | # ip v6 not abbreviated
-        (([0-9A-Fa-f]{1,4}:){6}:[0-9A-Fa-f]{1,4})                                                                                                                  | # ip v6 with double colon in the end
-        (([0-9A-Fa-f]{1,4}:){5}:([0-9A-Fa-f]{1,4}:)?[0-9A-Fa-f]{1,4})                                                                                              | # - ip addresses v6
-        (([0-9A-Fa-f]{1,4}:){4}:([0-9A-Fa-f]{1,4}:){0,2}[0-9A-Fa-f]{1,4})                                                                                          | # - with
-        (([0-9A-Fa-f]{1,4}:){3}:([0-9A-Fa-f]{1,4}:){0,3}[0-9A-Fa-f]{1,4})                                                                                          | # - double colon
-        (([0-9A-Fa-f]{1,4}:){2}:([0-9A-Fa-f]{1,4}:){0,4}[0-9A-Fa-f]{1,4})                                                                                          | # - in the middle
-        (([0-9A-Fa-f]{1,4}:){6} ((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3} (\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))                            | # ip v6 with compatible to v4
-        (([0-9A-Fa-f]{1,4}:){1,5}:((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))                           | # ip v6 with compatible to v4
-        (([0-9A-Fa-f]{1,4}:){1}:([0-9A-Fa-f]{1,4}:){0,4}((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))     | # ip v6 with compatible to v4
-        (([0-9A-Fa-f]{1,4}:){0,2}:([0-9A-Fa-f]{1,4}:){0,3}((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))   | # ip v6 with compatible to v4
-        (([0-9A-Fa-f]{1,4}:){0,3}:([0-9A-Fa-f]{1,4}:){0,2}((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))   | # ip v6 with compatible to v4
-        (([0-9A-Fa-f]{1,4}:){0,4}:([0-9A-Fa-f]{1,4}:){1}((\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))     | # ip v6 with compatible to v4
-        (::([0-9A-Fa-f]{1,4}:){0,5}((\b((25[0-5])|(1\d{2})|(2[0-4]\d) |(\d{1,2}))\b)\.){3}(\b((25[0-5])|(1\d{2})|(2[0-4]\d)|(\d{1,2}))\b))                         | # ip v6 with compatible to v4
-        ([0-9A-Fa-f]{1,4}::([0-9A-Fa-f]{1,4}:){0,5}[0-9A-Fa-f]{1,4})                                                                                               | # ip v6 with compatible to v4
-        (::([0-9A-Fa-f]{1,4}:){0,6}[0-9A-Fa-f]{1,4})                                                                                                               | # ip v6 with double colon at the beginning
-        (([0-9A-Fa-f]{1,4}:){1,7}:)                                                                                                                                  # ip v6 without ending
-        )$)
-      }x
-
       def initialize(env, middleware)
         @env      = env
         @check_ip = middleware.check_ip
@@ -118,7 +94,7 @@ module ActionDispatch
       #
       # REMOTE_ADDR will be correct if the request is made directly against the
       # Ruby process, on e.g. Heroku. When the request is proxied by another
-      # server like HAProxy or Nginx, the IP address that made the original
+      # server like HAProxy or NGINX, the IP address that made the original
       # request will be put in an X-Forwarded-For header. If there are multiple
       # proxies, that header may contain a list of IPs. Other proxy services
       # set the Client-Ip header instead, so we check that too.
@@ -173,12 +149,22 @@ module ActionDispatch
       def ips_from(header)
         # Split the comma-separated list into an array of strings
         ips = @env[header] ? @env[header].strip.split(/[,\s]+/) : []
-        # Only return IPs that are valid according to the regex
-        ips.select{ |ip| ip =~ VALID_IP }
+        ips.select do |ip|
+          begin
+            # Only return IPs that are valid according to the IPAddr#new method
+            range = IPAddr.new(ip).to_range
+            # we want to make sure nobody is sneaking a netmask in
+            range.begin == range.end
+          rescue ArgumentError
+            nil
+          end
+        end
       end
 
       def filter_proxies(ips)
-        ips.reject { |ip| ip =~ @proxies }
+        ips.reject do |ip|
+          @proxies.any? { |proxy| proxy === ip }
+        end
       end
 
     end

data/lib/action_dispatch/middleware/request_id.rb

@@ -5,7 +5,7 @@ module ActionDispatch
   # Makes a unique request id available to the action_dispatch.request_id env variable (which is then accessible through
   # ActionDispatch::Request#uuid) and sends the same id to the client via the X-Request-Id header.
   #
-  # The unique request id is either based off the X-Request-Id header in the request, which would typically be generated
+  # The unique request id is either based on the X-Request-Id header in the request, which would typically be generated
   # by a firewall, load balancer, or the web server, or, if this header is not available, a random uuid. If the
   # header is accepted from the outside world, we sanitize it to a max of 255 chars and alphanumeric and dashes only.
   #

data/lib/action_dispatch/middleware/session/cookie_store.rb

@@ -49,7 +49,7 @@ module ActionDispatch
     # reasonably sure that your upgrade is otherwise complete. Additionally,
     # you should take care to make sure you are not relying on the ability to
     # decode signed cookies generated by your app in external applications or
-    # Javascript before upgrading.
+    # JavaScript before upgrading.
     #
     # Note that changing the secret key will invalidate all existing sessions!
     class CookieStore < Rack::Session::Abstract::ID

data/lib/action_dispatch/middleware/show_exceptions.rb

@@ -42,6 +42,7 @@ module ActionDispatch
       wrapper = ExceptionWrapper.new(env, exception)
       status  = wrapper.status_code
       env["action_dispatch.exception"] = wrapper.exception
+      env["action_dispatch.original_path"] = env["PATH_INFO"]
       env["PATH_INFO"] = "/#{status}"
       response = @exceptions_app.call(env)
       response[1]['X-Cascade'] == 'pass' ? pass_response(status) : response

data/lib/action_dispatch/middleware/static.rb

@@ -2,69 +2,98 @@ require 'rack/utils'
 require 'active_support/core_ext/uri'
 
 module ActionDispatch
+  # This middleware returns a file's contents from disk in the body response.
+  # When initialized it can accept an optional 'Cache-Control' header which
+  # will be set when a response containing a file's contents is delivered.
+  #
+  # This middleware will render the file specified in `env["PATH_INFO"]`
+  # where the base path is in the +root+ directory. For example if the +root+
+  # is set to `public/` then a request with `env["PATH_INFO"]` of
+  # `assets/application.js` will return a response with contents of a file
+  # located at `public/assets/application.js` if the file exists. If the file
+  # does not exist a 404 "File not Found" response will be returned.
   class FileHandler
     def initialize(root, cache_control)
       @root          = root.chomp('/')
       @compiled_root = /^#{Regexp.escape(root)}/
-      headers = cache_control && { 'Cache-Control' => cache_control }
-      @file_server   = ::Rack::File.new(@root, headers)
+      headers        = cache_control && { 'Cache-Control' => cache_control }
+      @file_server = ::Rack::File.new(@root, headers)
     end
 
     def match?(path)
-      path = unescape_path(path)
+      path = URI.parser.unescape(path)
       return false unless path.valid_encoding?
 
-      full_path = path.empty? ? @root : File.join(@root,
-        clean_path_info(escape_glob_chars(path)))
-      paths = "#{full_path}#{ext}"
+      paths = [path, "#{path}#{ext}", "#{path}/index#{ext}"].map { |v|
+        Rack::Utils.clean_path_info v
+      }
 
-      matches = Dir[paths]
-      match = matches.detect { |m| File.file?(m) }
-      if match
-        match.sub!(@compiled_root, '')
-        ::Rack::Utils.escape(match)
+      if match = paths.detect { |p|
+        path = File.join(@root, p)
+        begin
+          File.file?(path) && File.readable?(path)
+        rescue SystemCallError
+          false
+        end
+
+      }
+        return ::Rack::Utils.escape(match)
       end
     end
 
     def call(env)
-      @file_server.call(env)
-    end
-
-    def ext
-      @ext ||= begin
-        ext = ::ActionController::Base.default_static_extension
-        "{,#{ext},/index#{ext}}"
+      path      = env['PATH_INFO']
+      gzip_path = gzip_file_path(path)
+
+      if gzip_path && gzip_encoding_accepted?(env)
+        env['PATH_INFO']            = gzip_path
+        status, headers, body       = @file_server.call(env)
+        headers['Content-Encoding'] = 'gzip'
+        headers['Content-Type']     = content_type(path)
+      else
+        status, headers, body = @file_server.call(env)
       end
-    end
 
-    def unescape_path(path)
-      URI.parser.unescape(path)
-    end
+      headers['Vary'] = 'Accept-Encoding' if gzip_path
 
-    def escape_glob_chars(path)
-      path.gsub(/[*?{}\[\]]/, "\\\\\\&")
+      return [status, headers, body]
+    ensure
+      env['PATH_INFO'] = path
     end
 
     private
+      def ext
+        ::ActionController::Base.default_static_extension
+      end
 
-    PATH_SEPS = Regexp.union(*[::File::SEPARATOR, ::File::ALT_SEPARATOR].compact)
-
-    def clean_path_info(path_info)
-      parts = path_info.split PATH_SEPS
-
-      clean = []
-
-      parts.each do |part|
-        next if part.empty? || part == '.'
-        part == '..' ? clean.pop : clean << part
+      def content_type(path)
+        ::Rack::Mime.mime_type(::File.extname(path), 'text/plain')
       end
 
-      clean.unshift '/' if parts.empty? || parts.first.empty?
+      def gzip_encoding_accepted?(env)
+        env['HTTP_ACCEPT_ENCODING'] =~ /\bgzip\b/i
+      end
 
-      ::File.join(*clean)
-    end
+      def gzip_file_path(path)
+        can_gzip_mime = content_type(path) =~ /\A(?:text\/|application\/javascript)/
+        gzip_path     = "#{path}.gz"
+        if can_gzip_mime && File.exist?(File.join(@root, ::Rack::Utils.unescape(gzip_path)))
+          gzip_path
+        else
+          false
+        end
+      end
   end
 
+  # This middleware will attempt to return the contents of a file's body from
+  # disk in the response.  If a file is not found on disk, the request will be
+  # delegated to the application stack. This middleware is commonly initialized
+  # to serve assets from a server's `public/` directory.
+  #
+  # This middleware verifies the path to ensure that only files
+  # living in the root directory can be rendered. A request cannot
+  # produce a directory traversal using this middleware. Only 'GET' and 'HEAD'
+  # requests will result in a file being returned.
   class Static
     def initialize(app, path, cache_control=nil)
       @app = app