actionpack 7.1.5.1 → 8.1.2

data/lib/action_dispatch/middleware/remote_ip.rb

@@ -1,37 +1,41 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "ipaddr"
 
 module ActionDispatch
-  # = Action Dispatch \RemoteIp
+  # # Action Dispatch RemoteIp
   #
-  # This middleware calculates the IP address of the remote client that is
-  # making the request. It does this by checking various headers that could
-  # contain the address, and then picking the last-set address that is not
-  # on the list of trusted IPs. This follows the precedent set by e.g.
-  # {the Tomcat server}[https://issues.apache.org/bugzilla/show_bug.cgi?id=50453].
-  # A more detailed explanation of the algorithm is given at GetIp#calculate_ip.
+  # This middleware calculates the IP address of the remote client that is making
+  # the request. It does this by checking various headers that could contain the
+  # address, and then picking the last-set address that is not on the list of
+  # trusted IPs. This follows the precedent set by e.g. [the Tomcat
+  # server](https://issues.apache.org/bugzilla/show_bug.cgi?id=50453). A more
+  # detailed explanation of the algorithm is given at GetIp#calculate_ip.
   #
-  # Some Rack servers concatenate repeated headers, like {HTTP RFC 2616}[https://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}[https://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)
-  # then you should test your Rack server to make sure your data is good.
+  # Some Rack servers concatenate repeated headers, like [HTTP RFC
+  # 2616](https://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](https://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) 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.
-  # This middleware assumes that there is at least one proxy sitting around
-  # and setting headers with the client's remote IP address. If you don't use
-  # a proxy, because you are hosted on e.g. Heroku without SSL, any client can
-  # claim to have any IP address by setting the +X-Forwarded-For+ header. If you
-  # care about that, then you need to explicitly drop or ignore those headers
-  # sometime before this middleware runs. Alternatively, remove this middleware
-  # to avoid inadvertently relying on it.
+  # IF YOU DON'T USE A PROXY, THIS MAKES YOU VULNERABLE TO IP SPOOFING. This
+  # middleware assumes that there is at least one proxy sitting around and setting
+  # headers with the client's remote IP address. If you don't use a proxy, because
+  # you are hosted on e.g. Heroku without SSL, any client can claim to have any IP
+  # address by setting the `X-Forwarded-For` header. If you care about that, then
+  # you need to explicitly drop or ignore those headers sometime before this
+  # middleware runs. Alternatively, remove this middleware to avoid inadvertently
+  # relying on it.
   class RemoteIp
     class IpSpoofAttackError < StandardError; end
 
-    # The default trusted IPs list simply includes IP addresses that are
-    # guaranteed by the IP specification to be private addresses. Those will
-    # not be the ultimate client IP in production, and so are discarded. See
+    # The default trusted IPs list simply includes IP addresses that are guaranteed
+    # by the IP specification to be private addresses. Those will not be the
+    # ultimate client IP in production, and so are discarded. See
     # https://en.wikipedia.org/wiki/Private_network for details.
     TRUSTED_PROXIES = [
       "127.0.0.0/8",    # localhost IPv4 range, per RFC-3330
@@ -40,24 +44,26 @@ module ActionDispatch
       "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
+      "169.254.0.0/16", # link-local IPv4 range 169.254.x.x
+      "fe80::/10",      # link-local IPv6 range fe80::/10
     ].map { |proxy| IPAddr.new(proxy) }
 
     attr_reader :check_ip, :proxies
 
-    # Create a new +RemoteIp+ middleware instance.
+    # Create a new `RemoteIp` middleware instance.
     #
-    # The +ip_spoofing_check+ option is on by default. When on, an exception
-    # is raised if it looks like the client is trying to lie about its own IP
-    # address. It makes sense to turn off this check on sites aimed at non-IP
-    # clients (like WAP devices), or behind proxies that set headers in an
-    # incorrect or confusing way (like AWS ELB).
+    # The `ip_spoofing_check` option is on by default. When on, an exception is
+    # raised if it looks like the client is trying to lie about its own IP address.
+    # It makes sense to turn off this check on sites aimed at non-IP 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 an enumerable which will be used
-    # instead of +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 enumerable which will be used
+    # instead of `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, ip_spoofing_check = true, custom_proxies = nil)
       @app = app
       @check_ip = ip_spoofing_check
@@ -82,19 +88,19 @@ module ActionDispatch
       end
     end
 
-    # Since the IP address may not be needed, we store the object here
-    # without calculating the IP to keep from slowing down the majority of
-    # requests. For those requests that do need to know the IP, the
-    # GetIp#calculate_ip method will calculate the memoized client IP address.
+    # Since the IP address may not be needed, we store the object here without
+    # calculating the IP to keep from slowing down the majority of requests. For
+    # those requests that do need to know the IP, the GetIp#calculate_ip method will
+    # calculate the memoized client IP address.
     def call(env)
       req = ActionDispatch::Request.new env
       req.remote_ip = GetIp.new(req, check_ip, proxies)
       @app.call(req.env)
     end
 
-    # The GetIp class exists as a way to defer processing of the request data
-    # into an actual IP address. If the ActionDispatch::Request#remote_ip method
-    # is called, this class will calculate the value and then memoize it.
+    # The GetIp class exists as a way to defer processing of the request data 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
       def initialize(req, check_ip, proxies)
         @req      = req
@@ -102,63 +108,64 @@ module ActionDispatch
         @proxies  = proxies
       end
 
-      # Sort through the various IP address headers, looking for the IP most
-      # likely to be the address of the actual remote client making this
-      # request.
+      # Sort through the various IP address headers, looking for the IP most likely to
+      # be the address of the actual remote client making this request.
       #
-      # 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
-      # 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.
+      # 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 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.
       #
-      # As discussed in {this post about Rails IP Spoofing}[https://web.archive.org/web/20170626095448/https://blog.gingerlime.com/2012/rails-ip-spoofing-vulnerabilities-and-protection/],
-      # while the first IP in the list is likely to be the "originating" IP,
-      # it could also have been set by the client maliciously.
+      # As discussed in [this post about Rails IP
+      # Spoofing](https://web.archive.org/web/20170626095448/https://blog.gingerlime.com/2012/rails-ip-spoofing-vulnerabilities-and-protection/),
+      # while the first IP in the list is likely to be the "originating" IP, it
+      # could also have been set by the client maliciously.
       #
-      # In order to find the first address that is (probably) accurate, we
-      # take the list of IPs, remove known and trusted proxies, and then take
-      # the last address left, which was presumably set by one of those proxies.
+      # In order to find the first address that is (probably) accurate, we take the
+      # list of IPs, remove known and trusted proxies, and then take the last address
+      # left, which was presumably set by one of those proxies.
       def calculate_ip
         # Set by the Rack web server, this is a single value.
-        remote_addr = ips_from(@req.remote_addr).last
+        remote_addr = sanitize_ips(ips_from(@req.remote_addr)).last
 
         # Could be a CSV list and/or repeated headers that were concatenated.
-        client_ips    = ips_from(@req.client_ip).reverse!
-        forwarded_ips = ips_from(@req.x_forwarded_for).reverse!
+        client_ips    = sanitize_ips(ips_from(@req.client_ip)).reverse!
+        forwarded_ips = sanitize_ips(@req.forwarded_for || []).reverse!
 
-        # +Client-Ip+ and +X-Forwarded-For+ should not, generally, both be set.
-        # If they are both set, it means that either:
+        # `Client-Ip` and `X-Forwarded-For` should not, generally, both be set. If they
+        # are both set, it means that either:
         #
         # 1) This request passed through two proxies with incompatible IP header
-        #    conventions.
-        # 2) The client passed one of +Client-Ip+ or +X-Forwarded-For+
-        #    (whichever the proxy servers weren't using) themselves.
+        #     conventions.
+        #
+        # 2) The client passed one of `Client-Ip` or `X-Forwarded-For`
+        #     (whichever the proxy servers weren't using) themselves.
         #
-        # Either way, there is no way for us to determine which header is the
-        # right one after the fact. Since we have no idea, if we are concerned
-        # about IP spoofing we need to give up and explode. (If you're not
-        # concerned about IP spoofing you can turn the +ip_spoofing_check+
-        # option off.)
+        # Either way, there is no way for us to determine which header is the right one
+        # after the fact. Since we have no idea, if we are concerned about IP spoofing
+        # we need to give up and explode. (If you're not concerned about IP spoofing you
+        # can turn the `ip_spoofing_check` option off.)
         should_check_ip = @check_ip && client_ips.last && forwarded_ips.last
         if should_check_ip && !forwarded_ips.include?(client_ips.last)
           # We don't know which came from the proxy, and which from the user
           raise IpSpoofAttackError, "IP spoofing attack?! " \
             "HTTP_CLIENT_IP=#{@req.client_ip.inspect} " \
-            "HTTP_X_FORWARDED_FOR=#{@req.x_forwarded_for.inspect}"
+            "HTTP_X_FORWARDED_FOR=#{@req.x_forwarded_for.inspect}" \
+            " HTTP_FORWARDED=" + @req.forwarded_for.map { "for=#{_1}" }.join(", ").inspect if @req.forwarded_for.any?
         end
 
         # We assume these things about the IP headers:
         #
-        #   - X-Forwarded-For will be a list of IPs, one per proxy, or blank
-        #   - Client-Ip is propagated from the outermost proxy, or is blank
-        #   - REMOTE_ADDR will be the IP that made the request to Rack
+        #     - X-Forwarded-For will be a list of IPs, one per proxy, or blank
+        #     - Client-Ip is propagated from the outermost proxy, or is blank
+        #     - REMOTE_ADDR will be the IP that made the request to Rack
         ips = forwarded_ips + client_ips
         ips.compact!
 
-        # If every single IP option is in the trusted list, return the IP
-        # that's furthest away
+        # If every single IP option is in the trusted list, return the IP that's
+        # furthest away
         filter_proxies(ips + [remote_addr]).first || ips.last || remote_addr
       end
 
@@ -172,7 +179,10 @@ module ActionDispatch
       def ips_from(header) # :doc:
         return [] unless header
         # Split the comma-separated list into an array of strings.
-        ips = header.strip.split(/[,\s]+/)
+        header.strip.split(/[,\s]+/)
+      end
+
+      def sanitize_ips(ips) # :doc:
         ips.select! do |ip|
           # Only return IPs that are valid according to the IPAddr#new method.
           range = IPAddr.new(ip).to_range

data/lib/action_dispatch/middleware/request_id.rb

@@ -1,30 +1,36 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "securerandom"
 require "active_support/core_ext/string/access"
 
 module ActionDispatch
-  # = Action Dispatch \RequestId
+  # # Action Dispatch RequestId
   #
-  # Makes a unique request id available to the +action_dispatch.request_id+ env variable (which is then accessible
-  # through ActionDispatch::Request#request_id or the alias ActionDispatch::Request#uuid) and sends
-  # the same id to the client via the +X-Request-Id+ header.
+  # Makes a unique request id available to the `action_dispatch.request_id` env
+  # variable (which is then accessible through ActionDispatch::Request#request_id
+  # or the alias ActionDispatch::Request#uuid) and sends the same id to the client
+  # via the `X-Request-Id` header.
   #
-  # 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.
+  # 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.
   #
-  # The unique request id can be used to trace a request end-to-end and would typically end up being part of log files
-  # from multiple pieces of the stack.
+  # The unique request id can be used to trace a request end-to-end and would
+  # typically end up being part of log files from multiple pieces of the stack.
   class RequestId
     def initialize(app, header:)
       @app = app
       @header = header
+      @env_header = "HTTP_#{header.upcase.tr("-", "_")}"
     end
 
     def call(env)
       req = ActionDispatch::Request.new env
-      req.request_id = make_request_id(req.headers[@header])
+      req.request_id = make_request_id(req.get_header(@env_header))
       @app.call(env).tap { |_status, headers, _body| headers[@header] = req.request_id }
     end
 

data/lib/action_dispatch/middleware/server_timing.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/notifications"
 
 module ActionDispatch
@@ -29,8 +31,8 @@ module ActionDispatch
 
       def ensure_subscribed
         @mutex.synchronize do
-          # Subscribe to all events, except those beginning with "!"
-          # Ideally we would be more selective of what is being measured
+          # Subscribe to all events, except those beginning with "!" Ideally we would be
+          # more selective of what is being measured
           @subscriber ||= ActiveSupport::Notifications.subscribe(/\A[^!]/, self)
         end
       end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "rack/utils"
 require "rack/request"
 require "rack/session/abstract/id"

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

@@ -1,23 +1,33 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch/middleware/session/abstract_store"
 
 module ActionDispatch
   module Session
-    # = Action Dispatch Session \CacheStore
+    # # Action Dispatch Session CacheStore
+    #
+    # A session store that uses an ActiveSupport::Cache::Store to store the
+    # sessions. This store is most useful if you don't store critical data in your
+    # sessions and you don't need them to live for extended periods of time.
     #
-    # A session store that uses an ActiveSupport::Cache::Store to store the sessions. This store is most useful
-    # if you don't store critical data in your sessions and you don't need them to live for extended periods
-    # of time.
+    # #### Options
+    # *   `cache`         - The cache to use. If it is not specified, `Rails.cache`
+    #     will be used.
+    # *   `expire_after`  - The length of time a session will be stored before
+    #     automatically expiring. By default, the `:expires_in` option of the cache
+    #     is used.
+    # *   `check_collisions`  - Check if newly generated session ids aren't already in use.
+    #     If for some reason 128 bits of randomness aren't considered secure enough to avoid
+    #     collisions, this option can be enabled to ensure newly generated ids aren't in use.
+    #     By default, it is set to `false` to avoid additional cache write operations.
     #
-    # ==== Options
-    # * <tt>cache</tt>         - The cache to use. If it is not specified, <tt>Rails.cache</tt> will be used.
-    # * <tt>expire_after</tt>  - The length of time a session will be stored before automatically expiring.
-    #   By default, the <tt>:expires_in</tt> option of the cache is used.
     class CacheStore < AbstractSecureStore
       def initialize(app, options = {})
         @cache = options[:cache] || Rails.cache
         options[:expire_after] ||= @cache.options[:expires_in]
+        @check_collisions = options[:check_collisions] || false
         super
       end
 
@@ -56,6 +66,18 @@ module ActionDispatch
         def get_session_with_fallback(sid)
           @cache.read(cache_key(sid.private_id)) || @cache.read(cache_key(sid.public_id))
         end
+
+        def generate_sid
+          if @check_collisions
+            loop do
+              sid = super
+              key = cache_key(sid.private_id)
+              break sid if @cache.write(key, {}, unless_exist: true, expires_in: default_options[:expire_after])
+            end
+          else
+            super
+          end
+        end
     end
   end
 end

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

@@ -1,53 +1,54 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/hash/keys"
 require "action_dispatch/middleware/session/abstract_store"
 require "rack/session/cookie"
 
 module ActionDispatch
   module Session
-    # = Action Dispatch Session \CookieStore
+    # # Action Dispatch Session CookieStore
     #
-    # This cookie-based session store is the \Rails default. It is
-    # dramatically faster than the alternatives.
+    # This cookie-based session store is the Rails default. It is dramatically
+    # faster than the alternatives.
     #
     # Sessions typically contain at most a user ID and flash message; both fit
-    # within the 4096 bytes cookie size limit. A +CookieOverflow+ exception is raised if
-    # you attempt to store more than 4096 bytes of data.
+    # within the 4096 bytes cookie size limit. A `CookieOverflow` exception is
+    # raised if you attempt to store more than 4096 bytes of data.
     #
-    # The cookie jar used for storage is automatically configured to be the
-    # best possible option given your application's configuration.
+    # The cookie jar used for storage is automatically configured to be the best
+    # possible option given your application's configuration.
     #
-    # Your cookies will be encrypted using your application's +secret_key_base+. This
-    # goes a step further than signed cookies in that encrypted cookies cannot
-    # be altered or read by users. This is the default starting in \Rails 4.
+    # Your cookies will be encrypted using your application's `secret_key_base`.
+    # This goes a step further than signed cookies in that encrypted cookies cannot
+    # be altered or read by users. This is the default starting in Rails 4.
     #
     # Configure your session store in an initializer:
     #
-    #   Rails.application.config.session_store :cookie_store, key: '_your_app_session'
+    #     Rails.application.config.session_store :cookie_store, key: '_your_app_session'
     #
-    # In the development and test environments your application's +secret_key_base+ is
-    # generated by \Rails and stored in a temporary file in <tt>tmp/local_secret.txt</tt>.
-    # In all other environments, it is stored encrypted in the
-    # <tt>config/credentials.yml.enc</tt> file.
+    # In the development and test environments your application's `secret_key_base`
+    # is generated by Rails and stored in a temporary file in
+    # `tmp/local_secret.txt`. In all other environments, it is stored encrypted in
+    # the `config/credentials.yml.enc` file.
     #
-    # If your application was not updated to \Rails 5.2 defaults, the +secret_key_base+
-    # will be found in the old <tt>config/secrets.yml</tt> file.
+    # If your application was not updated to Rails 5.2 defaults, the
+    # `secret_key_base` will be found in the old `config/secrets.yml` file.
     #
-    # Note that changing your +secret_key_base+ will invalidate all existing session.
-    # 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
+    # Note that changing your `secret_key_base` will invalidate all existing
+    # session. 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 changing it.
     #
-    # Because CookieStore extends +Rack::Session::Abstract::Persisted+, many of the
-    # options described there can be used to customize the session cookie that
-    # is generated. For example:
+    # Because CookieStore extends `Rack::Session::Abstract::Persisted`, many of the
+    # options described there can be used to customize the session cookie that is
+    # generated. For example:
     #
-    #   Rails.application.config.session_store :cookie_store, expire_after: 14.days
+    #     Rails.application.config.session_store :cookie_store, expire_after: 14.days
     #
     # would set the session cookie to expire automatically 14 days after creation.
-    # Other useful options include <tt>:key</tt>, <tt>:secure</tt>,
-    # <tt>:httponly</tt>, and <tt>:same_site</tt>.
+    # Other useful options include `:key`, `:secure`, `:httponly`, and `:same_site`.
     class CookieStore < AbstractSecureStore
       class SessionId < DelegateClass(Rack::Session::SessionId)
         attr_reader :cookie_value

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch/middleware/session/abstract_store"
 begin
   require "rack/session/dalli"
@@ -10,12 +12,14 @@ end
 
 module ActionDispatch
   module Session
-    # = Action Dispatch Session \MemCacheStore
+    # # Action Dispatch Session MemCacheStore
     #
     # A session store that uses MemCache to implement storage.
     #
-    # ==== Options
-    # * <tt>expire_after</tt>  - The length of time a session will be stored before automatically expiring.
+    # #### Options
+    # *   `expire_after`  - The length of time a session will be stored before
+    #     automatically expiring.
+    #
     class MemCacheStore < Rack::Session::Dalli
       include Compatibility
       include StaleSessionCheck

data/lib/action_dispatch/middleware/show_exceptions.rb

@@ -1,26 +1,27 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "action_dispatch/middleware/exception_wrapper"
 
 module ActionDispatch
-  # = Action Dispatch \ShowExceptions
+  # # Action Dispatch ShowExceptions
   #
-  # This middleware rescues any exception returned by the application
-  # and calls an exceptions app that will wrap it in a format for the end user.
+  # This middleware rescues any exception returned by the application and calls an
+  # exceptions app that will wrap it in a format for the end user.
   #
   # The exceptions app should be passed as a parameter on initialization of
-  # +ShowExceptions+. Every time there is an exception, +ShowExceptions+ will
-  # store the exception in <tt>env["action_dispatch.exception"]</tt>, rewrite
-  # the +PATH_INFO+ to the exception status code, and call the Rack app.
+  # `ShowExceptions`. Every time there is an exception, `ShowExceptions` will
+  # store the exception in `env["action_dispatch.exception"]`, rewrite the
+  # `PATH_INFO` to the exception status code, and call the Rack app.
   #
-  # In \Rails applications, the exceptions app can be configured with
-  # +config.exceptions_app+, which defaults to ActionDispatch::PublicExceptions.
+  # In Rails applications, the exceptions app can be configured with
+  # `config.exceptions_app`, which defaults to ActionDispatch::PublicExceptions.
   #
-  # If the application returns a response with the <tt>X-Cascade</tt> header
-  # set to <tt>"pass"</tt>, this middleware will send an empty response as a
-  # result with the correct status code. If any exception happens inside the
-  # exceptions app, this middleware catches the exceptions and returns a
-  # failsafe response.
+  # If the application returns a response with the `X-Cascade` header set to
+  # `"pass"`, this middleware will send an empty response as a result with the
+  # correct status code. If any exception happens inside the exceptions app, this
+  # middleware catches the exceptions and returns a failsafe response.
   class ShowExceptions
     def initialize(app, exceptions_app)
       @app = app
@@ -64,9 +65,8 @@ module ActionDispatch
       end
 
       def fallback_to_html_format_if_invalid_mime_type(request)
-        # If the MIME type for the request is invalid then the
-        # @exceptions_app may not be able to handle it. To make it
-        # easier to handle, we switch to HTML.
+        # If the MIME type for the request is invalid then the @exceptions_app may not
+        # be able to handle it. To make it easier to handle, we switch to HTML.
         begin
           request.content_mime_type
         rescue ActionDispatch::Http::MimeNegotiation::InvalidType