Implement RFC 9213 Targeted HTTP Cache Control

doc/admin-guide/configuration/cache-basics.en.rst

@@ -234,6 +234,84 @@ Traffic Server applies ``Cache-Control`` servability criteria after HTTP
 freshness criteria. For example, an object might be considered fresh but will
 not be served if its age is greater than its ``max-age``.
 
+Targeted Cache Control (RFC 9213)
+----------------------------------
+
+Traffic Server supports `RFC 9213 <https://httpwg.org/specs/rfc9213.html>`_
+Targeted HTTP Cache Control, which allows origin servers to provide different
+cache directives for different classes of caches. This is particularly useful in CDN deployments where you want to
+give different caching instructions to CDN caches versus browser caches.
+
+For example, an origin server might send::
+
+    Cache-Control: max-age=60
+    CDN-Cache-Control: max-age=3600
+
+When targeted cache control is enabled (via
+:ts:cv:`proxy.config.http.cache.targeted_cache_control_headers`), Traffic
+Server will use the ``CDN-Cache-Control`` directives instead of the standard
+``Cache-Control`` directives for caching decisions. The browser receiving the
+response will see both headers and use the standard ``Cache-Control``, allowing
+the object to be cached for 60 seconds in the browser but 3600 seconds in the CDN.
+
+Configuration
+~~~~~~~~~~~~~
+
+To enable targeted cache control, set
+:ts:cv:`proxy.config.http.cache.targeted_cache_control_headers` to a
+comma-separated list of header names to check in priority order::
+
+    # In records.yaml:
+    proxy.config.http.cache.targeted_cache_control_headers: CDN-Cache-Control
+
+Or with multiple targeted headers in priority order::
+
+    proxy.config.http.cache.targeted_cache_control_headers: ATS-Cache-Control,CDN-Cache-Control
+
+This configuration is overridable per-remap, allowing different rules for
+different origins::
+
+    # In remap.config:
+    map / https://origin.example.com/ @plugin=conf_remap.so \
+        @pparam=proxy.config.http.cache.targeted_cache_control_headers=CDN-Cache-Control
+
+Behavior
+~~~~~~~~
+
+- When a targeted header is found (first match in the priority list), its
+  directives replace the standard ``Cache-Control`` directives for all caching
+  decisions.
+
+- If no targeted headers are present or they are all empty, Traffic Server falls
+  back to the standard ``Cache-Control`` header.
+
+- Targeted headers are passed through to downstream caches, allowing CDN chains
+  to use the same directives.
+
+- All standard cache control directives are supported in targeted headers:
+  ``max-age``, ``s-maxage``, ``no-cache``, ``no-store``, ``private``,
+  ``must-revalidate``, etc.
+
+Use Cases
+~~~~~~~~~
+
+**CDN with origin cache**: An origin might have its own caching layer but want
+CDNs to cache more aggressively::
+
+    Cache-Control: max-age=60
+    CDN-Cache-Control: max-age=86400
+
+**Different CDN policies**: Using multiple CDN providers with different needs::
+
+    Cache-Control: max-age=300
+    CDN1-Cache-Control: max-age=3600
+    CDN2-Cache-Control: max-age=1800
+
+**Prevent CDN caching while allowing browser caching**::
+
+    Cache-Control: max-age=300
+    CDN-Cache-Control: no-store
+
 Revalidating HTTP Objects
 -------------------------
 

doc/admin-guide/files/records.yaml.en.rst

@@ -2518,6 +2518,31 @@ Cache Control
          ``Cache-Control: max-age``.
    ===== ======================================================================
 
+.. ts:cv:: CONFIG proxy.config.http.cache.targeted_cache_control_headers STRING ""
+   :reloadable:
+   :overridable:
+
+   Comma-separated list of targeted cache control header names to check in priority
+   order before falling back to the standard ``Cache-Control`` header. This implements
+   `RFC 9213 <https://httpwg.org/specs/rfc9213.html>`_ Targeted HTTP Cache Control.
+   When empty (the default), targeted cache control is disabled and only the standard
+   ``Cache-Control`` header is used.
+
+   Example values:
+
+   - ``CDN-Cache-Control`` - Use only CDN-Cache-Control if present
+   - ``ATS-Cache-Control,CDN-Cache-Control`` - Check ATS-Cache-Control first, then
+     CDN-Cache-Control, then fall back to Cache-Control
+
+   When a targeted header is found, its directives are used rather than those in the
+   standard ``Cache-Control`` header for caching decisions. The targeted headers are
+   passed through to downstream caches.
+
+   .. note::
+
+      This implementation uses the existing Cache-Control parser rather than the
+      strict RFC 8941 Structured Fields parser specified in RFC 9213.
+
 .. ts:cv:: CONFIG proxy.config.http.cache.max_stale_age INT 604800
    :reloadable:
    :overridable:

doc/admin-guide/plugins/lua.en.rst

@@ -4743,6 +4743,7 @@ Http config constants
     TS_LUA_CONFIG_NET_SOCK_NOTSENT_LOWAT
     TS_LUA_CONFIG_BODY_FACTORY_RESPONSE_SUPPRESSION_MODE
     TS_LUA_CONFIG_HTTP_CACHE_POST_METHOD
+    TS_LUA_CONFIG_HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS
     TS_LUA_CONFIG_LAST_ENTRY
 
 :ref:`TOP <admin-plugins-ts-lua>`

doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst

@@ -196,6 +196,7 @@ TSOverridableConfigKey Value                                              Config
 :enumerator:`TS_CONFIG_NET_SOCK_NOTSENT_LOWAT`                          :ts:cv:`proxy.config.net.sock_notsent_lowat`
 :enumerator:`TS_CONFIG_BODY_FACTORY_RESPONSE_SUPPRESSION_MODE`          :ts:cv:`proxy.config.body_factory.response_suppression_mode`
 :enumerator:`TS_CONFIG_HTTP_CACHE_POST_METHOD`                          :ts:cv:`proxy.config.http.cache.post_method`
+:enumerator:`TS_CONFIG_HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS`       :ts:cv:`proxy.config.http.cache.targeted_cache_control_headers`
 ======================================================================  ====================================================================
 
 Examples

doc/developer-guide/api/types/TSOverridableConfigKey.en.rst

@@ -163,6 +163,7 @@ Enumeration Members
 .. enumerator:: TS_CONFIG_HTTP_NO_DNS_JUST_FORWARD_TO_PARENT
 .. enumerator:: TS_CONFIG_HTTP_CACHE_IGNORE_QUERY
 .. enumerator:: TS_CONFIG_HTTP_CACHE_POST_METHOD
+.. enumerator:: TS_CONFIG_HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS
 
 
 Description

include/proxy/hdrs/MIME.h

@@ -325,7 +325,8 @@ struct MIMEHdrImpl : public HdrHeapObjImpl {
   void check_strings(HeapCheck *heaps, int num_heaps);
 
   // Cooked values
-  void recompute_cooked_stuff(MIMEField *changing_field_or_null = nullptr);
+  void recompute_cooked_stuff(MIMEField *changing_field_or_null = nullptr, const std::string_view *targeted_headers = nullptr,
+                              size_t targeted_headers_count = 0);
   void recompute_accelerators_and_presence_bits();
 
   // Utility

include/proxy/http/HttpConfig.h

@@ -92,6 +92,44 @@ class HttpStatusCodeList
   HttpStatusBitset _data;
 };
 
+/**
+ * Pre-parsed list of targeted cache control header names (RFC 9213).
+ *
+ * Instead of parsing a comma-separated string on each request, this class
+ * stores the header names as an array of string_views into a stable backing
+ * string. The Converter ensures the string is parsed once at config load time
+ * and whenever the per-transaction override is set.
+ */
+class TargetedCacheControlHeaders
+{
+public:
+  static const MgmtConverter Conv;
+
+  /// Maximum number of targeted headers supported.
+  static constexpr size_t MAX_HEADERS = 8;
+
+  char            *conf_value{nullptr};
+  std::string_view headers[MAX_HEADERS];
+  size_t           count{0};
+
+  /// Parse a comma-separated header list into the headers array.
+  void parse(std::string_view src);
+
+  /// Return a pointer to the parsed headers array.
+  const std::string_view *
+  get_headers() const
+  {
+    return headers;
+  }
+
+  /// Return the number of parsed headers.
+  size_t
+  get_count() const
+  {
+    return count;
+  }
+};
+
 struct HttpStatsBlock {
   // Need two stats for these for counts and times
   Metrics::Counter::AtomicType *background_fill_bytes_aborted;
@@ -550,6 +588,8 @@ struct OverridableHttpConfigParams {
   MgmtByte cache_range_write              = 0;
   MgmtByte allow_multi_range              = 0;
 
+  TargetedCacheControlHeaders targeted_cache_control_headers;
+
   MgmtByte ignore_accept_mismatch          = 0;
   MgmtByte ignore_accept_language_mismatch = 0;
   MgmtByte ignore_accept_encoding_mismatch = 0;
@@ -884,7 +924,9 @@ class ParsedConfigCache
    */
   struct ParsedValue {
     std::string conf_value_storage{}; // Owns the string data.
-    std::variant<std::monostate, HostResData, HttpStatusCodeList, HttpForwarded::OptionBitSet, MgmtByte> parsed{};
+    std::variant<std::monostate, HostResData, HttpStatusCodeList, HttpForwarded::OptionBitSet, MgmtByte,
+                 TargetedCacheControlHeaders>
+      parsed{};
   };
 
   /** Return the parsed value for the configuration.
@@ -985,6 +1027,7 @@ inline HttpConfigParams::~HttpConfigParams()
   ats_free(oride.host_res_data.conf_value);
   ats_free(oride.negative_caching_list.conf_value);
   ats_free(oride.negative_revalidating_list.conf_value);
+  ats_free(oride.targeted_cache_control_headers.conf_value);
 
   delete connect_ports;
   delete redirect_actions_map;

include/proxy/http/OverridableConfigDefs.h

@@ -249,6 +249,7 @@
   X(HTTP_NEGATIVE_CACHING_LIST,                     negative_caching_list,                      "proxy.config.http.negative_caching_list",                        STRING, HttpStatusCodeList_Conv) \
   X(HTTP_CONNECT_ATTEMPTS_RETRY_BACKOFF_BASE,       connect_attempts_retry_backoff_base,        "proxy.config.http.connect_attempts_retry_backoff_base",          INT,    GENERIC) \
   X(HTTP_NEGATIVE_REVALIDATING_LIST,                negative_revalidating_list,                 "proxy.config.http.negative_revalidating_list",                   STRING, HttpStatusCodeList_Conv) \
-  X(HTTP_CACHE_POST_METHOD,                         cache_post_method,                          "proxy.config.http.cache.post_method",                            INT,    GENERIC)
+  X(HTTP_CACHE_POST_METHOD,                         cache_post_method,                          "proxy.config.http.cache.post_method",                            INT,    GENERIC) \
+  X(HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS,      targeted_cache_control_headers,             "proxy.config.http.cache.targeted_cache_control_headers",         STRING, TargetedCacheControlHeaders_Conv)
 
 // clang-format on

include/ts/apidefs.h.in

@@ -908,6 +908,7 @@ enum TSOverridableConfigKey {
   TS_CONFIG_HTTP_CONNECT_ATTEMPTS_RETRY_BACKOFF_BASE,
   TS_CONFIG_HTTP_NEGATIVE_REVALIDATING_LIST,
   TS_CONFIG_HTTP_CACHE_POST_METHOD,
+  TS_CONFIG_HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS,
   TS_CONFIG_LAST_ENTRY,
 };
 

src/api/InkAPI.cc

@@ -7298,6 +7298,10 @@ _memberp_to_generic(MgmtFloat *ptr, MgmtConverter const *&conv) -> typename std:
 #define _CONF_CASE_HttpTransact_HOST_RES_CONV(KEY, MEMBER)                      \
   case TS_CONFIG_##KEY: ret = &overridableHttpConfig->MEMBER; conv = &HttpTransact::HOST_RES_CONV; break;
 
+// Custom converter: Parses/formats targeted cache control header lists.
+#define _CONF_CASE_TargetedCacheControlHeaders_Conv(KEY, MEMBER)                \
+  case TS_CONFIG_##KEY: ret = &overridableHttpConfig->MEMBER; conv = &TargetedCacheControlHeaders::Conv; break;
+
 // Dispatcher: Routes to _CONF_CASE_<CONV> based on the CONV parameter.
 #define _CONF_CASE_DISPATCH(KEY, MEMBER, RECORD_NAME, DATA_TYPE, CONV) _CONF_CASE_##CONV(KEY, MEMBER)
 
@@ -7348,6 +7352,7 @@ _conf_to_memberp(TSOverridableConfigKey conf, OverridableHttpConfigParams *overr
 #undef _CONF_CASE_ConnectionTracker_MAX_SERVER_CONV
 #undef _CONF_CASE_ConnectionTracker_SERVER_MATCH_CONV
 #undef _CONF_CASE_HttpTransact_HOST_RES_CONV
+#undef _CONF_CASE_TargetedCacheControlHeaders_Conv
 #undef _CONF_CASE_DISPATCH
 
 // 2nd little helper function to find the struct member for getting.
@@ -7561,6 +7566,14 @@ TSHttpTxnConfigStringSet(TSHttpTxn txnp, TSOverridableConfigKey conf, const char
       s->t_state.my_txn_conf().host_res_data = std::get<HostResData>(parsed.parsed);
     }
     break;
+  case TS_CONFIG_HTTP_CACHE_TARGETED_CACHE_CONTROL_HEADERS:
+    if (value && length > 0) {
+      auto &parsed                                            = ParsedConfigCache::lookup(conf, std::string_view(value, length));
+      s->t_state.my_txn_conf().targeted_cache_control_headers = std::get<TargetedCacheControlHeaders>(parsed.parsed);
+    } else {
+      s->t_state.my_txn_conf().targeted_cache_control_headers = TargetedCacheControlHeaders{};
+    }
+    break;
   default: {
     if (value && length > 0) {
       return _eval_conv(&(s->t_state.my_txn_conf()), conf, value, length);

src/proxy/hdrs/HdrToken.cc

@@ -125,7 +125,10 @@ const char *const _hdrtoken_strs[] = {
   "br",
 
   // RFC-8878
-  "zstd"};
+  "zstd",
+
+  // RFC-9213 Targeted Cache Control
+  "CDN-Cache-Control"};
 
 HdrTokenTypeBinding _hdrtoken_strs_type_initializers[] = {
   {"file",                 HdrTokenType::SCHEME        },
@@ -267,6 +270,7 @@ HdrTokenFieldInfo _hdrtoken_strs_field_initializers[] = {
   {"Forwarded",                 MIME_SLOTID_NONE,                MIME_PRESENCE_NONE,                (HdrTokenInfoFlags::COMMAS | HdrTokenInfoFlags::MULTVALS)                              },
   {"Sec-WebSocket-Key",         MIME_SLOTID_NONE,                MIME_PRESENCE_NONE,                HdrTokenInfoFlags::NONE                                                                },
   {"Sec-WebSocket-Version",     MIME_SLOTID_NONE,                MIME_PRESENCE_NONE,                HdrTokenInfoFlags::NONE                                                                },
+  {"CDN-Cache-Control",         MIME_SLOTID_NONE,                MIME_PRESENCE_NONE,                (HdrTokenInfoFlags::COMMAS | HdrTokenInfoFlags::MULTVALS)                              },
   {nullptr,                     0,                               0,                                 HdrTokenInfoFlags::NONE                                                                },
 };
 

src/proxy/hdrs/MIME.cc

@@ -3713,7 +3713,8 @@ MIMEHdrImpl::recompute_accelerators_and_presence_bits()
 ////////////////////////////////////////////////////////
 
 void
-MIMEHdrImpl::recompute_cooked_stuff(MIMEField *changing_field_or_null)
+MIMEHdrImpl::recompute_cooked_stuff(MIMEField *changing_field_or_null, const std::string_view *targeted_headers,
+                                    size_t targeted_headers_count)
 {
   int         len, tlen;
   const char *s;
@@ -3725,13 +3726,26 @@ MIMEHdrImpl::recompute_cooked_stuff(MIMEField *changing_field_or_null)
 
   mime_hdr_cooked_stuff_init(this, changing_field_or_null);
 
-  //////////////////////////////////////////////////
-  // (1) cook the Cache-Control header if present //
-  //////////////////////////////////////////////////
+  /////////////////////////////////////////////////////////////////////////////
+  // (1) cook the Cache-Control header (or targeted variant) if present     //
+  /////////////////////////////////////////////////////////////////////////////
 
   // to be safe, recompute unless you know this call is for other cooked field
   if ((changing_field_or_null == nullptr) || (changing_field_or_null->m_wks_idx != MIME_WKSIDX_PRAGMA)) {
-    field = mime_hdr_field_find(this, static_cast<std::string_view>(MIME_FIELD_CACHE_CONTROL));
+    field = nullptr;
+
+    // Check for targeted cache control headers first (in priority order).
+    for (size_t i = 0; i < targeted_headers_count; ++i) {
+      field = mime_hdr_field_find(this, targeted_headers[i]);
+      if (field) {
+        break;
+      }
+    }
+
+    // If no targeted header was found, fall back to standard Cache-Control.
+    if (!field) {
+      field = mime_hdr_field_find(this, static_cast<std::string_view>(MIME_FIELD_CACHE_CONTROL));
+    }
 
     if (field) {
       // try pathpaths first -- unlike most other fastpaths, this one