Merge pull request rails#55033 from egg528/add-http-request-cache-control-directives-support

byroot · web-flow · commit 0da7aaf5526a · 2025-05-13T09:09:11.000+02:00
Add support for Cache-Control request directives
diff --git a/actionpack/CHANGELOG.md b/actionpack/CHANGELOG.md
@@ -1,3 +1,42 @@
+*   Add comprehensive support for HTTP Cache-Control request directives according to RFC 9111.
+
+    Provides a `request.cache_control_directives` object that gives access to request cache directives:
+
+    ```ruby
+    # Boolean directives
+    request.cache_control_directives.only_if_cached?  # => true/false
+    request.cache_control_directives.no_cache?        # => true/false
+    request.cache_control_directives.no_store?        # => true/false
+    request.cache_control_directives.no_transform?    # => true/false
+
+    # Value directives
+    request.cache_control_directives.max_age          # => integer or nil
+    request.cache_control_directives.max_stale        # => integer or nil (or true for valueless max-stale)
+    request.cache_control_directives.min_fresh        # => integer or nil
+    request.cache_control_directives.stale_if_error   # => integer or nil
+
+    # Special helpers for max-stale
+    request.cache_control_directives.max_stale?         # => true if max-stale present (with or without value)
+    request.cache_control_directives.max_stale_unlimited? # => true only for valueless max-stale
+    ```
+
+    Example usage:
+
+    ```ruby
+    def show
+      if request.cache_control_directives.only_if_cached?
+        @article = Article.find_cached(params[:id])
+        return head(:gateway_timeout) if @article.nil?
+      else
+        @article = Article.find(params[:id])
+      end
+
+      render :show
+    end
+    ```
+
+    *egg528*
+
 *   Add assert_in_body/assert_not_in_body as the simplest way to check if a piece of text is in the response body.
 
     *DHH*
diff --git a/actionpack/lib/action_dispatch/http/cache.rb b/actionpack/lib/action_dispatch/http/cache.rb
@@ -63,6 +63,114 @@ def fresh?(response)
             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
diff --git a/actionpack/test/dispatch/request_test.rb b/actionpack/test/dispatch/request_test.rb
@@ -1446,3 +1446,105 @@ def setup
     assert_instance_of(ActionDispatch::Request::Session::Options, ActionDispatch::Request::Session::Options.find(@request))
   end
 end
+
+class RequestCacheControlDirectives < BaseRequestTest
+  test "lazily initializes cache_control_directives" do
+    request = stub_request
+    assert_not_includes request.instance_variables, :@cache_control_directives
+
+    request.cache_control_directives
+    assert_includes request.instance_variables, :@cache_control_directives
+  end
+
+  test "only_if_cached? is true when only-if-cached is the sole directive" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "only-if-cached")
+    assert_predicate request.cache_control_directives, :only_if_cached?
+  end
+
+  test "only_if_cached? is true when only-if-cached appears among multiple directives" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-age=60, only-if-cached")
+    assert_predicate request.cache_control_directives, :only_if_cached?
+  end
+
+  test "only_if_cached? is false when Cache-Control header is missing" do
+    request = stub_request
+    assert_not_predicate request.cache_control_directives, :only_if_cached?
+  end
+
+  test "no_cache? properly detects the no-cache directive" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "no-cache")
+    assert_predicate request.cache_control_directives, :no_cache?
+  end
+
+  test "no_store? properly detects the no-store directive" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "no-store")
+    assert_predicate request.cache_control_directives, :no_store?
+  end
+
+  test "no_transform? properly detects the no-transform directive" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "no-transform")
+    assert_predicate request.cache_control_directives, :no_transform?
+  end
+
+  test "max_age properly returns the max-age directive value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-age=60")
+    assert_equal 60, request.cache_control_directives.max_age
+  end
+
+  test "max_stale properly returns the max-stale directive value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale=300")
+    assert_equal 300, request.cache_control_directives.max_stale
+  end
+
+  test "max_stale returns true when max-stale is present without a value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale")
+    assert_equal true, request.cache_control_directives.max_stale
+  end
+
+  test "max_stale? returns true when max-stale is present with or without a value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale=300")
+    assert_predicate request.cache_control_directives, :max_stale?
+
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale")
+    assert_predicate request.cache_control_directives, :max_stale?
+  end
+
+  test "max_stale? returns false when max-stale is not present" do
+    request = stub_request
+    assert_not_predicate request.cache_control_directives, :max_stale?
+  end
+
+  test "max_stale_unlimited? returns true only when max-stale is present without a value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale")
+    assert_predicate request.cache_control_directives, :max_stale_unlimited?
+
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-stale=300")
+    assert_not_predicate request.cache_control_directives, :max_stale_unlimited?
+
+    request = stub_request
+    assert_not_predicate request.cache_control_directives, :max_stale_unlimited?
+  end
+
+  test "min_fresh properly returns the min-fresh directive value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "min-fresh=120")
+    assert_equal 120, request.cache_control_directives.min_fresh
+  end
+
+  test "stale_if_error properly returns the stale-if-error directive value" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "stale-if-error=600")
+    assert_equal 600, request.cache_control_directives.stale_if_error
+  end
+
+  test "handles Cache-Control header with whitespace and case insensitivity" do
+    request = stub_request("HTTP_CACHE_CONTROL" => " Max-Age=60 , No-Cache ")
+    assert_equal 60, request.cache_control_directives.max_age
+    assert_predicate request.cache_control_directives, :no_cache?
+  end
+
+  test "ignores unrecognized directives" do
+    request = stub_request("HTTP_CACHE_CONTROL" => "max-age=60, unknown-directive, foo=bar")
+    assert_equal 60, request.cache_control_directives.max_age
+    assert_not_predicate request.cache_control_directives, :no_cache?
+    assert_not_predicate request.cache_control_directives, :no_store?
+  end
+end
