Merge pull request rails#54833 from heka1024/add-must-understand

Add `must-understand` directive

Author: byroot

actionpack/CHANGELOG.md

@@ -1,3 +1,24 @@
+*   Implement `must-understand` directive according to RFC 9111.
+
+    The `must-understand` directive indicates that a cache must understand the semantics of the response status code, or discard the response. This directive is enforced to be used only with `no-store` to ensure proper cache behavior.
+
+    ```ruby
+    class ArticlesController < ApplicationController
+      def show
+        @article = Article.find(params[:id])
+
+        if @article.special_format?
+          must_understand
+          render status: 203 # Non-Authoritative Information
+        else
+          fresh_when @article
+        end
+      end
+    end
+    ```
+
+    *heka1024*
+
 *   The JSON renderer doesn't escape HTML entities or Unicode line separators anymore.
 
     Using `render json:` will no longer escape `<`, `>`, `&`, `U+2028` and `U+2029` characters that can cause errors

actionpack/lib/action_controller/metal/conditional_get.rb

@@ -332,6 +332,31 @@ def no_store
       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

actionpack/lib/action_dispatch/http/cache.rb

@@ -142,7 +142,7 @@ def strong_etag?
       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 +187,7 @@ def prepare_cache_control!
         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 +222,7 @@ def merge_and_normalize_cache_control!(cache_control)
 
           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]

actionpack/test/controller/conditional_get_directives_test.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "abstract_unit"
+
+class ConditionalGetDirectivesController < ActionController::Base
+  def must_understand_action
+    must_understand
+    render plain: "using must-understand directive"
+  end
+
+  def cache_control_with_must_understand
+    fresh_when etag: "123", cache_control: { must_understand: true }
+    render plain: "with must-understand via cache_control" unless performed?
+  end
+
+  def must_understand_without_no_store
+    response.cache_control[:no_cache] = true
+    response.cache_control[:must_understand] = true
+    render plain: "no-cache with must-understand"
+  end
+end
+
+class ConditionalGetDirectivesTest < ActionController::TestCase
+  tests ConditionalGetDirectivesController
+
+  def test_must_understand
+    get :must_understand_action
+    assert_response :success
+    assert_includes @response.headers["Cache-Control"], "must-understand"
+  end
+
+  def test_cache_control_with_must_understand
+    get :cache_control_with_must_understand
+    assert_response :success
+    assert_not_includes @response.headers["Cache-Control"], "must-understand"
+  end
+
+  def test_must_understand_without_no_store
+    get :must_understand_without_no_store
+    assert_response :success
+    assert_not_includes @response.headers["Cache-Control"], "must-understand"
+    assert_includes @response.headers["Cache-Control"], "no-cache"
+  end
+end