actionpack 7.1.3 → 7.2.1.1

data/lib/action_controller/metal/allow_browser.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# :markup: markdown
+
+module ActionController # :nodoc:
+  module AllowBrowser
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      # Specify the browser versions that will be allowed to access all actions (or
+      # some, as limited by `only:` or `except:`). Only browsers matched in the hash
+      # or named set passed to `versions:` will be blocked if they're below the
+      # versions specified. This means that all other browsers, as well as agents that
+      # aren't reporting a user-agent header, will be allowed access.
+      #
+      # A browser that's blocked will by default be served the file in
+      # public/406-unsupported-browser.html with a HTTP status code of "406 Not
+      # Acceptable".
+      #
+      # In addition to specifically named browser versions, you can also pass
+      # `:modern` as the set to restrict support to browsers natively supporting webp
+      # images, web push, badges, import maps, CSS nesting, and CSS :has. This
+      # includes Safari 17.2+, Chrome 120+, Firefox 121+, Opera 106+.
+      #
+      # You can use https://caniuse.com to check for browser versions supporting the
+      # features you use.
+      #
+      # You can use `ActiveSupport::Notifications` to subscribe to events of browsers
+      # being blocked using the `browser_block.action_controller` event name.
+      #
+      # Examples:
+      #
+      #     class ApplicationController < ActionController::Base
+      #       # Allow only browsers natively supporting webp images, web push, badges, import maps, CSS nesting, and CSS :has
+      #       allow_browser versions: :modern
+      #     end
+      #
+      #     class ApplicationController < ActionController::Base
+      #       # All versions of Chrome and Opera will be allowed, but no versions of "internet explorer" (ie). Safari needs to be 16.4+ and Firefox 121+.
+      #       allow_browser versions: { safari: 16.4, firefox: 121, ie: false }
+      #     end
+      #
+      #     class MessagesController < ApplicationController
+      #       # In addition to the browsers blocked by ApplicationController, also block Opera below 104 and Chrome below 119 for the show action.
+      #       allow_browser versions: { opera: 104, chrome: 119 }, only: :show
+      #     end
+      def allow_browser(versions:, block: -> { render file: Rails.root.join("public/406-unsupported-browser.html"), layout: false, status: :not_acceptable }, **options)
+        before_action -> { allow_browser(versions: versions, block: block) }, **options
+      end
+    end
+
+    private
+      def allow_browser(versions:, block:)
+        require "useragent"
+
+        if BrowserBlocker.new(request, versions: versions).blocked?
+          ActiveSupport::Notifications.instrument("browser_block.action_controller", request: request, versions: versions) do
+            instance_exec(&block)
+          end
+        end
+      end
+
+      class BrowserBlocker
+        SETS = {
+          modern: { safari: 17.2, chrome: 120, firefox: 121, opera: 106, ie: false }
+        }
+
+        attr_reader :request, :versions
+
+        def initialize(request, versions:)
+          @request, @versions = request, versions
+        end
+
+        def blocked?
+          user_agent_version_reported? && unsupported_browser?
+        end
+
+        private
+          def parsed_user_agent
+            @parsed_user_agent ||= UserAgent.parse(request.user_agent)
+          end
+
+          def user_agent_version_reported?
+            request.user_agent.present? && parsed_user_agent.version.to_s.present?
+          end
+
+          def unsupported_browser?
+            version_guarded_browser? && version_below_minimum_required? && !bot?
+          end
+
+          def version_guarded_browser?
+            minimum_browser_version_for_browser != nil
+          end
+
+          def bot?
+            parsed_user_agent.bot?
+          end
+
+          def version_below_minimum_required?
+            if minimum_browser_version_for_browser
+              parsed_user_agent.version < UserAgent::Version.new(minimum_browser_version_for_browser.to_s)
+            else
+              true
+            end
+          end
+
+          def minimum_browser_version_for_browser
+            expanded_versions[normalized_browser_name]
+          end
+
+          def expanded_versions
+            @expanded_versions ||= (SETS[versions] || versions).with_indifferent_access
+          end
+
+          def normalized_browser_name
+            case name = parsed_user_agent.browser.downcase
+            when "internet explorer" then "ie"
+            else name
+            end
+          end
+      end
+  end
+end

data/lib/action_controller/metal/basic_implicit_render.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 module ActionController
   module BasicImplicitRender # :nodoc:
     def send_action(method, *args)

data/lib/action_controller/metal/conditional_get.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# :markup: markdown
+
 require "active_support/core_ext/object/try"
 require "active_support/core_ext/integer/time"
 
@@ -14,116 +16,124 @@ module ActionController
     end
 
     module ClassMethods
-      # Allows you to consider additional controller-wide information when generating an ETag.
-      # For example, if you serve pages tailored depending on who's logged in at the moment, you
-      # may want to add the current user id to be part of the ETag to prevent unauthorized displaying
-      # of cached pages.
+      # Allows you to consider additional controller-wide information when generating
+      # an ETag. For example, if you serve pages tailored depending on who's logged in
+      # at the moment, you may want to add the current user id to be part of the ETag
+      # to prevent unauthorized displaying of cached pages.
       #
-      #   class InvoicesController < ApplicationController
-      #     etag { current_user&.id }
+      #     class InvoicesController < ApplicationController
+      #       etag { current_user&.id }
       #
-      #     def show
-      #       # Etag will differ even for the same invoice when it's viewed by a different current_user
-      #       @invoice = Invoice.find(params[:id])
-      #       fresh_when etag: @invoice
+      #       def show
+      #         # Etag will differ even for the same invoice when it's viewed by a different current_user
+      #         @invoice = Invoice.find(params[:id])
+      #         fresh_when etag: @invoice
+      #       end
       #     end
-      #   end
       def etag(&etagger)
         self.etaggers += [etagger]
       end
     end
 
-    # Sets the +etag+, +last_modified+, or both on the response, and renders a
-    # <tt>304 Not Modified</tt> response if the request is already fresh.
-    #
-    # ==== Options
-    #
-    # [+:etag+]
-    #   Sets a "weak" ETag validator on the response. See the +:weak_etag+ option.
-    # [+:weak_etag+]
-    #   Sets a "weak" ETag validator on the response. Requests that specify an
-    #   +If-None-Match+ header may receive a <tt>304 Not Modified</tt> response
-    #   if the ETag matches exactly.
-    #
-    #   A weak ETag indicates semantic equivalence, not byte-for-byte equality,
-    #   so they're good for caching HTML pages in browser caches. They can't be
-    #   used for responses that must be byte-identical, like serving +Range+
-    #   requests within a PDF file.
-    # [+:strong_etag+]
-    #   Sets a "strong" ETag validator on the response. Requests that specify an
-    #   +If-None-Match+ header may receive a <tt>304 Not Modified</tt> response
-    #   if the ETag matches exactly.
-    #
-    #   A strong ETag implies exact equality -- the response must match byte for
-    #   byte. This is necessary for serving +Range+ requests within a large
-    #   video or PDF file, for example, or for compatibility with some CDNs that
-    #   don't support weak ETags.
-    # [+:last_modified+]
-    #   Sets a "weak" last-update validator on the response. Subsequent requests
-    #   that specify an +If-Modified-Since+ header may receive a <tt>304 Not Modified</tt>
-    #   response if +last_modified+ <= +If-Modified-Since+.
-    # [+:public+]
-    #   By default the +Cache-Control+ header is private. Set this option to
-    #   +true+ if you want your application to be cacheable by other devices,
-    #   such as proxy caches.
-    # [+:cache_control+]
-    #   When given, will overwrite an existing +Cache-Control+ header. For a
-    #   list of +Cache-Control+ directives, see the {article on
-    #   MDN}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control].
-    # [+:template+]
-    #   By default, the template digest for the current controller/action is
-    #   included in ETags. If the action renders a different template, you can
-    #   include its digest instead. If the action doesn't render a template at
-    #   all, you can pass <tt>template: false</tt> to skip any attempt to check
-    #   for a template digest.
-    #
-    # ==== Examples
-    #
-    #   def show
-    #     @article = Article.find(params[:id])
-    #     fresh_when(etag: @article, last_modified: @article.updated_at, public: true)
-    #   end
-    #
-    # This will send a <tt>304 Not Modified</tt> response if the request
-    # specifies a matching ETag and +If-Modified-Since+ header. Otherwise, it
-    # will render the +show+ template.
+    # Sets the `etag`, `last_modified`, or both on the response, and renders a `304
+    # Not Modified` response if the request is already fresh.
+    #
+    # #### Options
+    #
+    # `:etag`
+    # :   Sets a "weak" ETag validator on the response. See the `:weak_etag` option.
+    #
+    # `:weak_etag`
+    # :   Sets a "weak" ETag validator on the response. Requests that specify an
+    #     `If-None-Match` header may receive a `304 Not Modified` response if the
+    #     ETag matches exactly.
+    #
+    # :   A weak ETag indicates semantic equivalence, not byte-for-byte equality, so
+    #     they're good for caching HTML pages in browser caches. They can't be used
+    #     for responses that must be byte-identical, like serving `Range` requests
+    #     within a PDF file.
+    #
+    # `:strong_etag`
+    # :   Sets a "strong" ETag validator on the response. Requests that specify an
+    #     `If-None-Match` header may receive a `304 Not Modified` response if the
+    #     ETag matches exactly.
+    #
+    # :   A strong ETag implies exact equality -- the response must match byte for
+    #     byte. This is necessary for serving `Range` requests within a large video
+    #     or PDF file, for example, or for compatibility with some CDNs that don't
+    #     support weak ETags.
+    #
+    # `:last_modified`
+    # :   Sets a "weak" last-update validator on the response. Subsequent requests
+    #     that specify an `If-Modified-Since` header may receive a `304 Not
+    #     Modified` response if `last_modified` <= `If-Modified-Since`.
+    #
+    # `:public`
+    # :   By default the `Cache-Control` header is private. Set this option to
+    #     `true` if you want your application to be cacheable by other devices, such
+    #     as proxy caches.
+    #
+    # `:cache_control`
+    # :   When given, will overwrite an existing `Cache-Control` header. For a list
+    #     of `Cache-Control` directives, see the [article on
+    #     MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Contr
+    #     ol).
+    #
+    # `:template`
+    # :   By default, the template digest for the current controller/action is
+    #     included in ETags. If the action renders a different template, you can
+    #     include its digest instead. If the action doesn't render a template at
+    #     all, you can pass `template: false` to skip any attempt to check for a
+    #     template digest.
+    #
+    #
+    # #### Examples
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(etag: @article, last_modified: @article.updated_at, public: true)
+    #     end
+    #
+    # This will send a `304 Not Modified` response if the request specifies a
+    # matching ETag and `If-Modified-Since` header. Otherwise, it will render the
+    # `show` template.
     #
     # You can also just pass a record:
     #
-    #   def show
-    #     @article = Article.find(params[:id])
-    #     fresh_when(@article)
-    #   end
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(@article)
+    #     end
     #
-    # +etag+ will be set to the record, and +last_modified+ will be set to the
-    # record's +updated_at+.
+    # `etag` will be set to the record, and `last_modified` will be set to the
+    # record's `updated_at`.
     #
-    # You can also pass an object that responds to +maximum+, such as a
-    # collection of records:
+    # You can also pass an object that responds to `maximum`, such as a collection
+    # of records:
     #
-    #   def index
-    #     @articles = Article.all
-    #     fresh_when(@articles)
-    #   end
+    #     def index
+    #       @articles = Article.all
+    #       fresh_when(@articles)
+    #     end
     #
-    # In this case, +etag+ will be set to the collection, and +last_modified+
-    # will be set to <tt>maximum(:updated_at)</tt> (the timestamp of the most
-    # recently updated record).
+    # In this case, `etag` will be set to the collection, and `last_modified` will
+    # be set to `maximum(:updated_at)` (the timestamp of the most recently updated
+    # record).
     #
-    # When passing a record or a collection, you can still specify other
-    # options, such as +:public+ and +:cache_control+:
+    # When passing a record or a collection, you can still specify other options,
+    # such as `:public` and `:cache_control`:
     #
-    #   def show
-    #     @article = Article.find(params[:id])
-    #     fresh_when(@article, public: true, cache_control: { no_cache: true })
-    #   end
+    #     def show
+    #       @article = Article.find(params[:id])
+    #       fresh_when(@article, public: true, cache_control: { no_cache: true })
+    #     end
     #
-    # The above will set <tt>Cache-Control: public, no-cache</tt> in the response.
+    # The above will set `Cache-Control: public, no-cache` in the response.
     #
     # When rendering a different template than the controller/action's default
     # template, you can indicate which digest to include in the ETag:
     #
-    #   before_action { fresh_when @article, template: "widgets/show" }
+    #     before_action { fresh_when @article, template: "widgets/show" }
     #
     def fresh_when(object = nil, etag: nil, weak_etag: nil, strong_etag: nil, last_modified: nil, public: false, cache_control: {}, template: nil)
       response.cache_control.delete(:no_store)
@@ -145,131 +155,135 @@ module ActionController
       head :not_modified if request.fresh?(response)
     end
 
-    # Sets the +etag+ and/or +last_modified+ on the response and checks them
-    # against the request. If the request doesn't match the provided options, it
-    # is considered stale, and the response should be rendered from scratch.
-    # Otherwise, it is fresh, and a <tt>304 Not Modified</tt> is sent.
+    # Sets the `etag` and/or `last_modified` on the response and checks them against
+    # the request. If the request doesn't match the provided options, it is
+    # considered stale, and the response should be rendered from scratch. Otherwise,
+    # it is fresh, and a `304 Not Modified` is sent.
     #
-    # ==== Options
+    # #### Options
     #
     # See #fresh_when for supported options.
     #
-    # ==== Examples
+    # #### Examples
     #
-    #   def show
-    #     @article = Article.find(params[:id])
+    #     def show
+    #       @article = Article.find(params[:id])
     #
-    #     if stale?(etag: @article, last_modified: @article.updated_at)
-    #       @statistics = @article.really_expensive_call
-    #       respond_to do |format|
-    #         # all the supported formats
+    #       if stale?(etag: @article, last_modified: @article.updated_at)
+    #         @statistics = @article.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
     #       end
     #     end
-    #   end
     #
     # You can also just pass a record:
     #
-    #   def show
-    #     @article = Article.find(params[:id])
+    #     def show
+    #       @article = Article.find(params[:id])
     #
-    #     if stale?(@article)
-    #       @statistics = @article.really_expensive_call
-    #       respond_to do |format|
-    #         # all the supported formats
+    #       if stale?(@article)
+    #         @statistics = @article.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
     #       end
     #     end
-    #   end
     #
-    # +etag+ will be set to the record, and +last_modified+ will be set to the
-    # record's +updated_at+.
+    # `etag` will be set to the record, and `last_modified` will be set to the
+    # record's `updated_at`.
     #
-    # You can also pass an object that responds to +maximum+, such as a
-    # collection of records:
+    # You can also pass an object that responds to `maximum`, such as a collection
+    # of records:
     #
-    #   def index
-    #     @articles = Article.all
+    #     def index
+    #       @articles = Article.all
     #
-    #     if stale?(@articles)
-    #       @statistics = @articles.really_expensive_call
-    #       respond_to do |format|
-    #         # all the supported formats
+    #       if stale?(@articles)
+    #         @statistics = @articles.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
     #       end
     #     end
-    #   end
     #
-    # In this case, +etag+ will be set to the collection, and +last_modified+
-    # will be set to <tt>maximum(:updated_at)</tt> (the timestamp of the most
-    # recently updated record).
+    # In this case, `etag` will be set to the collection, and `last_modified` will
+    # be set to `maximum(:updated_at)` (the timestamp of the most recently updated
+    # record).
     #
-    # When passing a record or a collection, you can still specify other
-    # options, such as +:public+ and +:cache_control+:
+    # When passing a record or a collection, you can still specify other options,
+    # such as `:public` and `:cache_control`:
     #
-    #   def show
-    #     @article = Article.find(params[:id])
+    #     def show
+    #       @article = Article.find(params[:id])
     #
-    #     if stale?(@article, public: true, cache_control: { no_cache: true })
-    #       @statistics = @articles.really_expensive_call
-    #       respond_to do |format|
-    #         # all the supported formats
+    #       if stale?(@article, public: true, cache_control: { no_cache: true })
+    #         @statistics = @articles.really_expensive_call
+    #         respond_to do |format|
+    #           # all the supported formats
+    #         end
     #       end
     #     end
-    #   end
     #
-    # The above will set <tt>Cache-Control: public, no-cache</tt> in the response.
+    # The above will set `Cache-Control: public, no-cache` in the response.
     #
     # When rendering a different template than the controller/action's default
     # template, you can indicate which digest to include in the ETag:
     #
-    #   def show
-    #     super if stale?(@article, template: "widgets/show")
-    #   end
+    #     def show
+    #       super if stale?(@article, template: "widgets/show")
+    #     end
     #
     def stale?(object = nil, **freshness_kwargs)
       fresh_when(object, **freshness_kwargs)
       !request.fresh?(response)
     end
 
-    # Sets the +Cache-Control+ header, overwriting existing directives. This
-    # method will also ensure an HTTP +Date+ header for client compatibility.
+    # Sets the `Cache-Control` header, overwriting existing directives. This method
+    # will also ensure an HTTP `Date` header for client compatibility.
+    #
+    # Defaults to issuing the `private` directive, so that intermediate caches must
+    # not cache the response.
+    #
+    # #### Options
+    #
+    # `:public`
+    # :   If true, replaces the default `private` directive with the `public`
+    #     directive.
+    #
+    # `:must_revalidate`
+    # :   If true, adds the `must-revalidate` directive.
     #
-    # Defaults to issuing the +private+ directive, so that intermediate caches
-    # must not cache the response.
+    # `:stale_while_revalidate`
+    # :   Sets the value of the `stale-while-revalidate` directive.
     #
-    # ==== Options
+    # `:stale_if_error`
+    # :   Sets the value of the `stale-if-error` directive.
     #
-    # [+:public+]
-    #   If true, replaces the default +private+ directive with the +public+
-    #   directive.
-    # [+:must_revalidate+]
-    #   If true, adds the +must-revalidate+ directive.
-    # [+:stale_while_revalidate+]
-    #   Sets the value of the +stale-while-revalidate+ directive.
-    # [+:stale_if_error+]
-    #   Sets the value of the +stale-if-error+ directive.
     #
-    # Any additional key-value pairs are concatenated as directives. For a list
-    # of supported +Cache-Control+ directives, see the {article on
-    # MDN}[https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control].
+    # Any additional key-value pairs are concatenated as directives. For a list of
+    # supported `Cache-Control` directives, see the [article on
+    # MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).
     #
-    # ==== Examples
+    # #### Examples
     #
-    #   expires_in 10.minutes
-    #   # => Cache-Control: max-age=600, private
+    #     expires_in 10.minutes
+    #     # => Cache-Control: max-age=600, private
     #
-    #   expires_in 10.minutes, public: true
-    #   # => Cache-Control: max-age=600, public
+    #     expires_in 10.minutes, public: true
+    #     # => Cache-Control: max-age=600, public
     #
-    #   expires_in 10.minutes, public: true, must_revalidate: true
-    #   # => Cache-Control: max-age=600, public, must-revalidate
+    #     expires_in 10.minutes, public: true, must_revalidate: true
+    #     # => Cache-Control: max-age=600, public, must-revalidate
     #
-    #   expires_in 1.hour, stale_while_revalidate: 60.seconds
-    #   # => Cache-Control: max-age=3600, private, stale-while-revalidate=60
+    #     expires_in 1.hour, stale_while_revalidate: 60.seconds
+    #     # => Cache-Control: max-age=3600, private, stale-while-revalidate=60
     #
-    #   expires_in 1.hour, stale_if_error: 5.minutes
-    #   # => Cache-Control: max-age=3600, private, stale-if-error=300
+    #     expires_in 1.hour, stale_if_error: 5.minutes
+    #     # => Cache-Control: max-age=3600, private, stale-if-error=300
     #
-    #   expires_in 1.hour, public: true, "s-maxage": 3.hours, "no-transform": true
-    #   # => Cache-Control: max-age=3600, public, s-maxage=10800, no-transform=true
+    #     expires_in 1.hour, public: true, "s-maxage": 3.hours, "no-transform": true
+    #     # => Cache-Control: max-age=3600, public, s-maxage=10800, no-transform=true
     #
     def expires_in(seconds, options = {})
       response.cache_control.delete(:no_store)
@@ -286,8 +300,8 @@ module ActionController
       response.date = Time.now unless response.date?
     end
 
-    # Sets an HTTP 1.1 +Cache-Control+ header of <tt>no-cache</tt>. This means the
-    # resource will be marked as stale, so clients must always revalidate.
+    # Sets an HTTP 1.1 `Cache-Control` header of `no-cache`. This means the resource
+    # will be marked as stale, so clients must always revalidate.
     # Intermediate/browser caches may still store the asset.
     def expires_now
       response.cache_control.replace(no_cache: true)
@@ -295,12 +309,12 @@ module ActionController
 
     # Cache or yield the block. The cache is supposed to never expire.
     #
-    # You can use this method when you have an HTTP response that never changes,
-    # and the browser and proxies should cache it indefinitely.
+    # You can use this method when you have an HTTP response that never changes, and
+    # the browser and proxies should cache it indefinitely.
     #
-    # * +public+: By default, HTTP responses are private, cached only on the
-    #   user's web browser. To allow proxies to cache the response, set +true+ to
-    #   indicate that they can serve the cached response to all users.
+    # *   `public`: By default, HTTP responses are private, cached only on the
+    #     user's web browser. To allow proxies to cache the response, set `true` to
+    #     indicate that they can serve the cached response to all users.
     def http_cache_forever(public: false)
       expires_in 100.years, public: public
 
@@ -309,8 +323,8 @@ module ActionController
                       public: public)
     end
 
-    # Sets an HTTP 1.1 +Cache-Control+ header of <tt>no-store</tt>. This means the
-    # resource may not be stored in any cache.
+    # Sets an HTTP 1.1 `Cache-Control` header of `no-store`. This means the resource
+    # may not be stored in any cache.
     def no_store
       response.cache_control.replace(no_store: true)
     end