actionpack 8.0.3 → 8.1.0.beta1

data/lib/action_controller/form_builder.rb

@@ -40,7 +40,7 @@ module ActionController
       # rendered by this controller and its subclasses.
       #
       # #### Parameters
-      # *   `builder` - Default form builder, an instance of
+      # *   `builder` - Default form builder. Accepts a subclass of
       #     ActionView::Helpers::FormBuilder
       def default_form_builder(builder)
         self._default_form_builder = builder

data/lib/action_controller/log_subscriber.rb

@@ -49,6 +49,13 @@ module ActionController
     end
     subscribe_log_level :halted_callback, :info
 
+    # Manually subscribed below
+    def rescue_from_callback(event)
+      exception = event.payload[:exception]
+      info { "rescue_from handled #{exception.class} (#{exception.message}) - #{exception.backtrace.first.delete_prefix("#{Rails.root}/")}" }
+    end
+    subscribe_log_level :rescue_from_callback, :info
+
     def send_file(event)
       info { "Sent file #{event.payload[:path]} (#{event.duration.round(1)}ms)" }
     end

data/lib/action_controller/metal/allow_browser.rb

@@ -14,7 +14,7 @@ module ActionController # :nodoc:
       # 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
+      # public/406-unsupported-browser.html with an HTTP status code of "406 Not
       # Acceptable".
       #
       # In addition to specifically named browser versions, you can also pass

data/lib/action_controller/metal/conditional_get.rb

@@ -332,6 +332,31 @@ module ActionController
       response.cache_control.replace(no_store: true)
     end
 
+    # Adds the `must-understand` directive to the `Cache-Control` header, which indicates
+    # that a cache MUST understand the semantics of the response status code that has been
+    # received, or discard the response.
+    #
+    # This is particularly useful when returning responses with new or uncommon
+    # status codes that might not be properly interpreted by older caches.
+    #
+    # #### Example
+    #
+    #     def show
+    #       @article = Article.find(params[:id])
+    #
+    #       if @article.early_access?
+    #         must_understand
+    #         render status: 203 # Non-Authoritative Information
+    #       else
+    #         fresh_when @article
+    #       end
+    #     end
+    #
+    def must_understand
+      response.cache_control[:must_understand] = true
+      response.cache_control[:no_store] = true
+    end
+
     private
       def combine_etags(validator, options)
         [validator, *etaggers.map { |etagger| instance_exec(options, &etagger) }].compact

data/lib/action_controller/metal/data_streaming.rb

@@ -134,9 +134,7 @@ module ActionController # :nodoc:
         raise ArgumentError, ":type option required" if content_type.nil?
 
         if content_type.is_a?(Symbol)
-          extension = Mime[content_type]
-          raise ArgumentError, "Unknown MIME type #{options[:type]}" unless extension
-          self.content_type = extension
+          self.content_type = content_type
         else
           if !type_provided && options[:filename]
             # If type wasn't provided, try guessing from file extension.

data/lib/action_controller/metal/exceptions.rb

@@ -103,4 +103,9 @@ module ActionController
       super(message)
     end
   end
+
+  # Raised when a Rate Limit is exceeded by too many requests within a period of
+  # time.
+  class TooManyRequests < ActionControllerError
+  end
 end

data/lib/action_controller/metal/flash.rb

@@ -38,15 +38,12 @@ module ActionController # :nodoc:
           define_method(type) do
             request.flash[type]
           end
+          private type
           helper_method(type) if respond_to?(:helper_method)
 
           self._flash_types += [type]
         end
       end
-
-      def action_methods # :nodoc:
-        @action_methods ||= super - _flash_types.map(&:to_s).to_set
-      end
     end
 
     private

data/lib/action_controller/metal/head.rb

@@ -25,6 +25,8 @@ module ActionController
         raise ArgumentError, "#{status.inspect} is not a valid value for `status`."
       end
 
+      raise ::AbstractController::DoubleRenderError if response_body
+
       status ||= :ok
 
       if options
@@ -41,7 +43,7 @@ module ActionController
 
       if include_content?(response_code)
         unless self.media_type
-          self.content_type = content_type || ((f = formats) && Mime[f.first]) || Mime[:html]
+          self.content_type = content_type || ((f = formats) && Mime[f.first]) || :html
         end
 
         response.charset = false

data/lib/action_controller/metal/permissions_policy.rb

@@ -24,8 +24,17 @@ module ActionController # :nodoc:
       #       end
       #     end
       #
+      # Requires a global policy defined in an initializer, which can be
+      # empty:
+      #
+      #     Rails.application.config.permissions_policy do |policy|
+      #       # policy.gyroscope :none
+      #     end
       def permissions_policy(**options, &block)
         before_action(options) do
+          unless request.respond_to?(:permissions_policy)
+            raise "Cannot override permissions_policy if no global permissions_policy configured."
+          end
           if block_given?
             policy = request.permissions_policy.clone
             instance_exec(policy, &block)

data/lib/action_controller/metal/rate_limiting.rb

@@ -18,8 +18,13 @@ module ActionController # :nodoc:
       # parameter. It's evaluated within the context of the controller processing the
       # request.
       #
-      # Requests that exceed the rate limit are refused with a `429 Too Many Requests`
-      # response. You can specialize this by passing a callable in the `with:`
+      # By default, rate limits are scoped to the controller's path. If you want to
+      # share rate limits across multiple controllers, you can provide your own scope,
+      # by passing value in the `scope:` parameter.
+      #
+      # Requests that exceed the rate limit will raise an `ActionController::TooManyRequests`
+      # error. By default, Action Dispatch will rescue from the error and refuse the request
+      # with a `429 Too Many Requests` response. You can specialize this by passing a callable in the `with:`
       # parameter. It's evaluated within the context of the controller processing the
       # request.
       #
@@ -46,23 +51,33 @@ module ActionController # :nodoc:
       #     class APIController < ApplicationController
       #       RATE_LIMIT_STORE = ActiveSupport::Cache::RedisCacheStore.new(url: ENV["REDIS_URL"])
       #       rate_limit to: 10, within: 3.minutes, store: RATE_LIMIT_STORE
+      #       rate_limit to: 100, within: 5.minutes, scope: :api_global
       #     end
       #
       #     class SessionsController < ApplicationController
       #       rate_limit to: 3, within: 2.seconds, name: "short-term"
       #       rate_limit to: 10, within: 5.minutes, name: "long-term"
       #     end
-      def rate_limit(to:, within:, by: -> { request.remote_ip }, with: -> { head :too_many_requests }, store: cache_store, name: nil, **options)
-        before_action -> { rate_limiting(to: to, within: within, by: by, with: with, store: store, name: name) }, **options
+      def rate_limit(to:, within:, by: -> { request.remote_ip }, with: -> { raise TooManyRequests }, store: cache_store, name: nil, scope: nil, **options)
+        before_action -> { rate_limiting(to: to, within: within, by: by, with: with, store: store, name: name, scope: scope || controller_path) }, **options
       end
     end
 
     private
-      def rate_limiting(to:, within:, by:, with:, store:, name:)
-        cache_key = ["rate-limit", controller_path, name, instance_exec(&by)].compact.join(":")
+      def rate_limiting(to:, within:, by:, with:, store:, name:, scope:)
+        by = instance_exec(&by)
+        cache_key = ["rate-limit", scope, name, by].compact.join(":")
         count = store.increment(cache_key, 1, expires_in: within)
         if count && count > to
-          ActiveSupport::Notifications.instrument("rate_limit.action_controller", request: request) do
+          ActiveSupport::Notifications.instrument("rate_limit.action_controller",
+              request: request,
+              count: count,
+              to: to,
+              within: within,
+              by: by,
+              name: name,
+              scope: scope,
+              cache_key: cache_key) do
             instance_exec(&with)
           end
         end

data/lib/action_controller/metal/redirecting.rb

@@ -15,6 +15,19 @@ module ActionController
 
     included do
       mattr_accessor :raise_on_open_redirects, default: false
+      mattr_accessor :action_on_path_relative_redirect, default: :log
+      class_attribute :_allowed_redirect_hosts, :allowed_redirect_hosts_permissions, instance_accessor: false, instance_predicate: false
+      singleton_class.alias_method :allowed_redirect_hosts, :_allowed_redirect_hosts
+    end
+
+    module ClassMethods # :nodoc:
+      def allowed_redirect_hosts=(hosts)
+        hosts = hosts.dup.freeze
+        self._allowed_redirect_hosts = hosts
+        self.allowed_redirect_hosts_permissions = if hosts.present?
+          ActionDispatch::HostAuthorization::Permissions.new(hosts)
+        end
+      end
     end
 
     # Redirects the browser to the target specified in `options`. This parameter can
@@ -100,6 +113,26 @@ module ActionController
     #
     # See #url_from for more information on what an internal and safe URL is, or how
     # to fall back to an alternate redirect URL in the unsafe case.
+    #
+    # ### Path Relative URL Redirect Protection
+    #
+    # Rails also protects against potentially unsafe path relative URL redirects that don't
+    # start with a leading slash. These can create security vulnerabilities:
+    #
+    #     redirect_to "example.com"     # Creates http://yourdomain.comexample.com
+    #     redirect_to "@attacker.com"   # Creates http://yourdomain.com@attacker.com
+    #                                   # which browsers interpret as user@host
+    #
+    # You can configure how Rails handles these cases using:
+    #
+    #     config.action_controller.action_on_path_relative_redirect = :log    # default
+    #     config.action_controller.action_on_path_relative_redirect = :notify
+    #     config.action_controller.action_on_path_relative_redirect = :raise
+    #
+    # * `:log` - Logs a warning but allows the redirect
+    # * `:notify` - Sends an ActiveSupport notification but allows the redirect
+    #   (includes stack trace to help identify the source)
+    # * `:raise` - Raises an UnsafeRedirectError
     def redirect_to(options = {}, response_options = {})
       raise ActionControllerError.new("Cannot redirect to nil!") unless options
       raise AbstractController::DoubleRenderError if response_body
@@ -166,6 +199,10 @@ module ActionController
       when /\A([a-z][a-z\d\-+.]*:|\/\/).*/i
         options.to_str
       when String
+        if !options.start_with?("/", "?") && !options.empty?
+          _handle_path_relative_redirect(options)
+        end
+
         request.protocol + request.host_with_port + options
       when Proc
         _compute_redirect_to_location request, instance_eval(&options)
@@ -229,12 +266,14 @@ module ActionController
       end
 
       def _url_host_allowed?(url)
-        host = URI(url.to_s).host
+        url_to_s = url.to_s
+        host = URI(url_to_s).host
 
-        return true if host == request.host
-        return false unless host.nil?
-        return false unless url.to_s.start_with?("/")
-        !url.to_s.start_with?("//")
+        if host.nil?
+          url_to_s.start_with?("/") && !url_to_s.start_with?("//")
+        else
+          host == request.host || self.class.allowed_redirect_hosts_permissions&.allows?(host)
+        end
       rescue ArgumentError, URI::Error
         false
       end
@@ -248,5 +287,22 @@ module ActionController
           raise UnsafeRedirectError, msg
         end
       end
+
+      def _handle_path_relative_redirect(url)
+        message = "Path relative URL redirect detected: #{url.inspect}"
+
+        case action_on_path_relative_redirect
+        when :log
+          logger&.warn message
+        when :notify
+          ActiveSupport::Notifications.instrument("unsafe_redirect.action_controller",
+            url: url,
+            message: message,
+            stack_trace: caller
+          )
+        when :raise
+          raise UnsafeRedirectError, message
+        end
+      end
   end
 end

data/lib/action_controller/metal/renderers.rb

@@ -27,8 +27,23 @@ module ActionController
     # Default values are `:json`, `:js`, `:xml`.
     RENDERERS = Set.new
 
+    module DeprecatedEscapeJsonResponses # :nodoc:
+      def escape_json_responses=(value)
+        if value
+          ActionController.deprecator.warn(<<~MSG.squish)
+            Setting action_controller.escape_json_responses = true is deprecated and will have no effect in Rails 8.2.
+            Set it to `false`, or remove the config.
+          MSG
+        end
+        super
+      end
+    end
+
     included do
       class_attribute :_renderers, default: Set.new.freeze
+      class_attribute :escape_json_responses, instance_writer: false, instance_accessor: false, default: true
+
+      singleton_class.prepend DeprecatedEscapeJsonResponses
     end
 
     # Used in ActionController::Base and ActionController::API to include all
@@ -86,7 +101,7 @@ module ActionController
       remove_possible_method(method_name)
     end
 
-    def self._render_with_renderer_method_name(key)
+    def self._render_with_renderer_method_name(key) # :nodoc:
       "_render_with_renderer_#{key}"
     end
 
@@ -140,7 +155,7 @@ module ActionController
       _render_to_body_with_renderer(options) || super
     end
 
-    def _render_to_body_with_renderer(options)
+    def _render_to_body_with_renderer(options) # :nodoc:
       _renderers.each do |name|
         if options.key?(name)
           _process_options(options)
@@ -153,28 +168,34 @@ module ActionController
 
     add :json do |json, options|
       json_options = options.except(:callback, :content_type, :status)
+      json_options[:escape] ||= false if !self.class.escape_json_responses? && options[:callback].blank?
       json = json.to_json(json_options) unless json.kind_of?(String)
 
       if options[:callback].present?
         if media_type.nil? || media_type == Mime[:json]
-          self.content_type = Mime[:js]
+          self.content_type = :js
         end
 
         "/**/#{options[:callback]}(#{json})"
       else
-        self.content_type = Mime[:json] if media_type.nil?
+        self.content_type = :json if media_type.nil?
         json
       end
     end
 
     add :js do |js, options|
-      self.content_type = Mime[:js] if media_type.nil?
+      self.content_type = :js if media_type.nil?
       js.respond_to?(:to_js) ? js.to_js(options) : js
     end
 
     add :xml do |xml, options|
-      self.content_type = Mime[:xml] if media_type.nil?
+      self.content_type = :xml if media_type.nil?
       xml.respond_to?(:to_xml) ? xml.to_xml(options) : xml
     end
+
+    add :markdown do |md, options|
+      self.content_type = :md if media_type.nil?
+      md.respond_to?(:to_markdown) ? md.to_markdown : md
+    end
   end
 end

data/lib/action_controller/metal/rendering.rb

@@ -160,6 +160,12 @@ module ActionController
     #         render "posts/new", status: :unprocessable_entity
     #         # => renders app/views/posts/new.html.erb with HTTP status code 422
     #
+    # `:variants`
+    # :  This tells Rails to look for the first template matching any of the variations.
+    #
+    #         render "posts/index", variants: [:mobile]
+    #         # => renders app/views/posts/index.html+mobile.erb
+    #
     #--
     # Check for double render errors and set the content_type after rendering.
     def render(*args)
@@ -208,7 +214,7 @@ module ActionController
       end
 
       def _set_html_content_type
-        self.content_type = Mime[:html].to_s
+        self.content_type = :html
       end
 
       def _set_rendered_content_type(format)

data/lib/action_controller/metal/request_forgery_protection.rb

@@ -71,32 +71,39 @@ module ActionController # :nodoc:
     included do
       # Sets the token parameter name for RequestForgery. Calling
       # `protect_from_forgery` sets it to `:authenticity_token` by default.
-      config_accessor :request_forgery_protection_token
+      singleton_class.delegate :request_forgery_protection_token, :request_forgery_protection_token=, to: :config
+      delegate :request_forgery_protection_token, :request_forgery_protection_token=, to: :config
       self.request_forgery_protection_token ||= :authenticity_token
 
       # Holds the class which implements the request forgery protection.
-      config_accessor :forgery_protection_strategy
+      singleton_class.delegate :forgery_protection_strategy, :forgery_protection_strategy=, to: :config
+      delegate :forgery_protection_strategy, :forgery_protection_strategy=, to: :config
       self.forgery_protection_strategy = nil
 
       # Controls whether request forgery protection is turned on or not. Turned off by
       # default only in test mode.
-      config_accessor :allow_forgery_protection
+      singleton_class.delegate :allow_forgery_protection, :allow_forgery_protection=, to: :config
+      delegate :allow_forgery_protection, :allow_forgery_protection=, to: :config
       self.allow_forgery_protection = true if allow_forgery_protection.nil?
 
       # Controls whether a CSRF failure logs a warning. On by default.
-      config_accessor :log_warning_on_csrf_failure
+      singleton_class.delegate :log_warning_on_csrf_failure, :log_warning_on_csrf_failure=, to: :config
+      delegate :log_warning_on_csrf_failure, :log_warning_on_csrf_failure=, to: :config
       self.log_warning_on_csrf_failure = true
 
       # Controls whether the Origin header is checked in addition to the CSRF token.
-      config_accessor :forgery_protection_origin_check
+      singleton_class.delegate :forgery_protection_origin_check, :forgery_protection_origin_check=, to: :config
+      delegate :forgery_protection_origin_check, :forgery_protection_origin_check=, to: :config
       self.forgery_protection_origin_check = false
 
       # Controls whether form-action/method specific CSRF tokens are used.
-      config_accessor :per_form_csrf_tokens
+      singleton_class.delegate :per_form_csrf_tokens, :per_form_csrf_tokens=, to: :config
+      delegate :per_form_csrf_tokens, :per_form_csrf_tokens=, to: :config
       self.per_form_csrf_tokens = false
 
       # The strategy to use for storing and retrieving CSRF tokens.
-      config_accessor :csrf_token_storage_strategy
+      singleton_class.delegate :csrf_token_storage_strategy, :csrf_token_storage_strategy=, to: :config
+      delegate :csrf_token_storage_strategy, :csrf_token_storage_strategy=, to: :config
       self.csrf_token_storage_strategy = SessionStore.new
 
       helper_method :form_authenticity_token
@@ -461,7 +468,7 @@ module ActionController # :nodoc:
       # *   Does the `X-CSRF-Token` header match the form_authenticity_token?
       #
       def verified_request? # :doc:
-        !protect_against_forgery? || request.get? || request.head? ||
+        request.get? || request.head? || !protect_against_forgery? ||
           (valid_request_origin? && any_authenticity_token_valid?)
       end
 
@@ -621,6 +628,7 @@ module ActionController # :nodoc:
         If you cannot change the referrer policy, you can disable origin checking with the
         Rails.application.config.action_controller.forgery_protection_origin_check setting.
       MSG
+      private_constant :NULL_ORIGIN_MESSAGE
 
       # Checks if the request originated from the same origin by looking at the Origin
       # header.
@@ -634,7 +642,7 @@ module ActionController # :nodoc:
         end
       end
 
-      def normalize_action_path(action_path) # :doc:
+      def normalize_action_path(action_path)
         uri = URI.parse(action_path)
 
         if uri.relative? && (action_path.blank? || !action_path.start_with?("/"))
@@ -644,7 +652,7 @@ module ActionController # :nodoc:
         end
       end
 
-      def normalize_relative_action_path(rel_action_path) # :doc:
+      def normalize_relative_action_path(rel_action_path)
         uri = URI.parse(request.path)
         # add the action path to the request.path
         uri.path += "/#{rel_action_path}"

data/lib/action_controller/metal/rescue.rb

@@ -13,6 +13,15 @@ module ActionController # :nodoc:
     extend ActiveSupport::Concern
     include ActiveSupport::Rescuable
 
+    module ClassMethods
+      def handler_for_rescue(exception, ...) # :nodoc:
+        if handler = super
+          ActiveSupport::Notifications.instrument("rescue_from_callback.action_controller", exception: exception)
+          handler
+        end
+      end
+    end
+
     # Override this method if you want to customize when detailed exceptions must be
     # shown. This method is only called when `consider_all_requests_local` is
     # `false`. By default, it returns `false`, but someone may set it to

data/lib/action_controller/railtie.rb

@@ -13,8 +13,10 @@ module ActionController
   class Railtie < Rails::Railtie # :nodoc:
     config.action_controller = ActiveSupport::OrderedOptions.new
     config.action_controller.raise_on_open_redirects = false
+    config.action_controller.action_on_path_relative_redirect = :log
     config.action_controller.log_query_tags_around_actions = true
     config.action_controller.wrap_parameters_by_default = false
+    config.action_controller.allowed_redirect_hosts = []
 
     config.eager_load_namespaces << AbstractController
     config.eager_load_namespaces << ActionController
@@ -93,12 +95,6 @@ module ActionController
       end
     end
 
-    initializer "action_controller.compile_config_methods" do
-      ActiveSupport.on_load(:action_controller) do
-        config.compile_methods! if config.respond_to?(:compile_methods!)
-      end
-    end
-
     initializer "action_controller.request_forgery_protection" do |app|
       ActiveSupport.on_load(:action_controller_base) do
         if app.config.action_controller.default_protect_from_forgery

data/lib/action_dispatch/http/cache.rb

@@ -63,6 +63,114 @@ module ActionDispatch
             success
           end
         end
+
+        def cache_control_directives
+          @cache_control_directives ||= CacheControlDirectives.new(get_header("HTTP_CACHE_CONTROL"))
+        end
+
+        # Represents the HTTP Cache-Control header for requests,
+        # providing methods to access various cache control directives
+        # Reference: https://www.rfc-editor.org/rfc/rfc9111.html#name-request-directives
+        class CacheControlDirectives
+          def initialize(cache_control_header)
+            @only_if_cached = false
+            @no_cache = false
+            @no_store = false
+            @no_transform = false
+            @max_age = nil
+            @max_stale = nil
+            @min_fresh = nil
+            @stale_if_error = false
+            parse_directives(cache_control_header)
+          end
+
+          # Returns true if the only-if-cached directive is present.
+          # This directive indicates that the client only wishes to obtain a
+          # stored response. If a valid stored response is not available,
+          # the server should respond with a 504 (Gateway Timeout) status.
+          def only_if_cached?
+            @only_if_cached
+          end
+
+          # Returns true if the no-cache directive is present.
+          # This directive indicates that a cache must not use the response
+          # to satisfy subsequent requests without successful validation on the origin server.
+          def no_cache?
+            @no_cache
+          end
+
+          # Returns true if the no-store directive is present.
+          # This directive indicates that a cache must not store any part of the
+          # request or response.
+          def no_store?
+            @no_store
+          end
+
+          # Returns true if the no-transform directive is present.
+          # This directive indicates that a cache or proxy must not transform the payload.
+          def no_transform?
+            @no_transform
+          end
+
+          # Returns the value of the max-age directive.
+          # This directive indicates that the client is willing to accept a response
+          # whose age is no greater than the specified number of seconds.
+          attr_reader :max_age
+
+          # Returns the value of the max-stale directive.
+          # When max-stale is present with a value, returns that integer value.
+          # When max-stale is present without a value, returns true (unlimited staleness).
+          # When max-stale is not present, returns nil.
+          attr_reader :max_stale
+
+          # Returns true if max-stale directive is present (with or without a value)
+          def max_stale?
+            !@max_stale.nil?
+          end
+
+          # Returns true if max-stale directive is present without a value (unlimited staleness)
+          def max_stale_unlimited?
+            @max_stale == true
+          end
+
+          # Returns the value of the min-fresh directive.
+          # This directive indicates that the client is willing to accept a response
+          # whose freshness lifetime is no less than its current age plus the specified time in seconds.
+          attr_reader :min_fresh
+
+          # Returns the value of the stale-if-error directive.
+          # This directive indicates that the client is willing to accept a stale response
+          # if the check for a fresh one fails with an error for the specified number of seconds.
+          attr_reader :stale_if_error
+
+          private
+            def parse_directives(header_value)
+              return unless header_value
+
+              header_value.delete(" ").downcase.split(",").each do |directive|
+                name, value = directive.split("=", 2)
+
+                case name
+                when "max-age"
+                  @max_age = value.to_i
+                when "min-fresh"
+                  @min_fresh = value.to_i
+                when "stale-if-error"
+                  @stale_if_error = value.to_i
+                when "no-cache"
+                  @no_cache = true
+                when "no-store"
+                  @no_store = true
+                when "no-transform"
+                  @no_transform = true
+                when "only-if-cached"
+                  @only_if_cached = true
+                when "max-stale"
+                  @max_stale = value ? value.to_i : true
+                end
+              end
+            end
+        end
       end
 
       module Response
@@ -142,7 +250,7 @@ module ActionDispatch
       private
         DATE          = "Date"
         LAST_MODIFIED = "Last-Modified"
-        SPECIAL_KEYS  = Set.new(%w[extras no-store no-cache max-age public private must-revalidate])
+        SPECIAL_KEYS  = Set.new(%w[extras no-store no-cache max-age public private must-revalidate must-understand])
 
         def generate_weak_etag(validators)
           "W/#{generate_strong_etag(validators)}"
@@ -187,6 +295,7 @@ module ActionDispatch
         PRIVATE               = "private"
         MUST_REVALIDATE       = "must-revalidate"
         IMMUTABLE             = "immutable"
+        MUST_UNDERSTAND       = "must-understand"
 
         def handle_conditional_get!
           # Normally default cache control setting is handled by ETag middleware. But, if
@@ -221,6 +330,7 @@ module ActionDispatch
 
           if control[:no_store]
             options << PRIVATE if control[:private]
+            options << MUST_UNDERSTAND if control[:must_understand]
             options << NO_STORE
           elsif control[:no_cache]
             options << PUBLIC if control[:public]