Implement RFC 9213 Targeted HTTP Cache Control #12679

bneradt · 2025-11-20T19:26:31Z

This adds support for targeted Cache-Control headers (like CDN-Cache-Control) that allow cache directives to be targeted at specific caches. The implementation includes a configurable, priority-ordered list of targeted headers via proxy.config.http.cache.targeted_cache_control_headers, which is overridable per-remap rule. When a targeted header is present, it takes precedence over the standard Cache-Control header for caching decisions. Targeted headers are passed through downstream to allow proper cache hierarchy behavior.

Fixes: #9113

Copilot

Pull Request Overview

This PR implements RFC 9213 Targeted HTTP Cache Control, allowing cache directives to be targeted at specific caches through custom headers (e.g., CDN-Cache-Control). When configured, these targeted headers take precedence over standard Cache-Control for caching decisions, while still being passed through to downstream caches.

Key changes:

Added configurable, priority-ordered list of targeted cache control headers via proxy.config.http.cache.targeted_cache_control_headers
Modified cache control parsing logic to check targeted headers first before falling back to standard Cache-Control
Made configuration overridable per-remap rule for flexible deployment scenarios

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`src/proxy/hdrs/MIME.cc`	Core cache control parsing logic updated to check targeted headers in priority order
`src/proxy/http/HttpSM.cc`	Integration point where targeted headers config is passed to cache control recomputation
`include/proxy/hdrs/MIME.h`	Added flag to track if cache control came from targeted header; updated signature
`src/records/RecordsConfig.cc`	Added new configuration record for targeted headers
`src/proxy/http/HttpConfig.cc`	Config initialization and reconfiguration handling with proper memory management
`include/proxy/http/HttpConfig.h`	Added char* field for targeted headers config
`src/shared/overridable_txn_vars.cc`	Made config overridable for per-transaction use
`src/api/InkAPI.cc`	API support for reading/writing targeted headers config; added char** converter
`src/api/InkAPITest.cc`	Added new config key to API test list
`plugins/lua/ts_lua_http_config.cc`	Added Lua plugin support for the new config
`include/ts/apidefs.h.in`	Added enum value for new config key
`tests/gold_tests/cache/targeted-cache-control.test.py`	Test harness for RFC 9213 functionality
`tests/gold_tests/cache/replay/targeted-cache-control.replay.yaml`	Comprehensive test scenarios covering priority, fallback, and per-remap override
`doc/admin-guide/files/records.yaml.en.rst`	Configuration reference documentation
`doc/admin-guide/configuration/cache-basics.en.rst`	User guide with examples and use cases
`doc/developer-guide/api/types/TSOverridableConfigKey.en.rst`	API enum documentation
`doc/developer-guide/api/functions/TSHttpOverridableConfig.en.rst`	API function documentation
`doc/admin-guide/plugins/lua.en.rst`	Lua plugin constant documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/api/InkAPI.cc

bneradt · 2025-11-20T20:10:56Z

src/proxy/hdrs/MIME.cc

+    field = nullptr;
+
+    // Check for targeted cache control headers first (in priority order).
+    if (targeted_headers_str && *targeted_headers_str) {
+      swoc::TextView config_view{targeted_headers_str};
+      while (config_view) {
+        swoc::TextView header_name = config_view.take_prefix_at(',').trim_if(&isspace);
+        if (!header_name.empty()) {
+          field = mime_hdr_field_find(this, std::string_view{header_name.data(), header_name.size()});
+          if (field) {
+            // Found a targeted header! Mark it and stop searching.
+            m_cooked_stuff.m_cache_control.m_from_targeted_header = true;
+            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));
+    }


This is the actualy interesting production change (part 1).

bneradt · 2025-11-20T20:11:15Z

src/proxy/http/HttpSM.cc

+    // Recompute cooked cache control with targeted headers (pass nullptr if not configured).
+    const char *targeted_headers =
+      (t_state.txn_conf->targeted_cache_control_headers && t_state.txn_conf->targeted_cache_control_headers[0] != '\0') ?
+        t_state.txn_conf->targeted_cache_control_headers :
+        nullptr;
+    t_state.hdr_info.server_response.m_mime->recompute_cooked_stuff(nullptr, targeted_headers);
+


This is the other interesting production change (part 2).

This is "recooked" here to avoid intermingling the targeted cache control configuration into the MIME/parser interface. The recompute should be cheap, so I think this is OK. But if wanted, I can look into trying to get the parse to happen initially at parse_resp.

JakeChampion · 2025-12-10T14:38:18Z

@bneradt if you wanted to - you could run this patchset/branch against the tests in cache-tests https://cache-tests.fyi/#cdn-cache-control and see how many ATS is now passing for ☺️

zwoop

I know we suck in the area of overridable string configurations. But if I understand this, it will essentially “parse” this config string on every request, to find the headers that may contain the CC value(s) for this request ?

I know it’s hard, but could we pre-parse this (on load and reload) such that we build WKS for the common headers at least? And for the rest, have an array of TextView’s into the “raw” config string ?

bneradt · 2025-12-11T04:38:06Z

I know we suck in the area of overridable string configurations. But if I understand this, it will essentially “parse” this config string on every request, to find the headers that may contain the CC value(s) for this request ?

I know it’s hard, but could we pre-parse this (on load and reload) such that we build WKS for the common headers at least? And for the rest, have an array of TextView’s into the “raw” config string ?

These are good observations. I think I addressed these both - but let me know if I misunderstood something. I added CDN-Cache-Control to the WKS list and configured custom parsing to the possible targeted header list so that the parse is done once and cached from there as a string_view list.

This adds support for targeted Cache-Control headers (like CDN-Cache-Control) that allow cache directives to be targeted at specific caches. The implementation includes a configurable, priority-ordered list of targeted headers via proxy.config.http.cache.targeted_cache_control_headers, which is overridable per-remap rule. When a targeted header is present, it takes precedence over the standard Cache-Control header for caching decisions. Targeted headers are passed through downstream to allow proper cache hierarchy behavior. Fixes: apache#9113

bneradt · 2026-02-07T00:06:54Z

Hi @JakeChampion

@bneradt if you wanted to - you could run this patchset/branch against the tests in cache-tests https://cache-tests.fyi/#cdn-cache-control and see how many ATS is now passing for ☺️

I ran the tests and no tests change. Note that this patch adds targeted cache control header support, which I don't think the cache-tests have tests for.

But it's good to verify that no new tests fail at least. :)

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-07T03:21:05Z

src/proxy/http/HttpSM.cc

+    // Recompute cooked cache control with targeted headers.
+    t_state.hdr_info.server_response.m_mime->recompute_cooked_stuff(nullptr,
+                                                                    t_state.txn_conf->targeted_cache_control_headers.get_headers(),
+                                                                    t_state.txn_conf->targeted_cache_control_headers.get_count());
+


The targeted Cache-Control recompute happens before do_api_callout() for API_READ_RESPONSE_HDR. If a plugin (e.g. header_rewrite) modifies Cache-Control / targeted headers during that hook, the header mutation paths will call recompute_cooked_stuff(field) without the targeted header list, which can revert the cooked cache-control mask back to standard Cache-Control semantics for later caching decisions. Consider recomputing with the targeted header list after response-header hooks complete (or otherwise ensuring any subsequent recompute uses the same targeted header list) so plugin-driven header changes are reflected correctly.

Copilot · 2026-02-07T03:21:05Z

src/proxy/hdrs/MIME.cc

+    // If no targeted header was found, fall back to standard Cache-Control.
+    if (!field) {


recompute_cooked_stuff now selects a targeted cache-control header based on the targeted_headers parameters, but most existing callers (including the automatic recompute paths triggered by header field mutations) will use the defaults and therefore ignore targeted headers. This means any later modification to Cache-Control / targeted headers can recook using only the standard header and override the targeted behavior. Consider making targeted-header selection part of the header object’s state (or otherwise ensuring all recook call sites that can run before cache decisions provide the transaction’s targeted header list).

Suggested change

// If no targeted header was found, fall back to standard Cache-Control.

if (!field) {

// If no targeted header was found, fall back to standard Cache-Control

// only when no targeted headers were requested.

if (!field && (targeted_headers_count == 0 || targeted_headers == nullptr)) {

Copilot · 2026-02-07T03:21:05Z

src/proxy/http/HttpConfig.cc

+    TargetedCacheControlHeaders *hdrs = static_cast<TargetedCacheControlHeaders *>(data);
+    // The string_views in headers[] point into conf_value, so conf_value must
+    // remain stable for the lifetime of the parsed headers.
+    hdrs->parse(src);


The TargetedCacheControlHeaders::Conv store lambda comments that headers[] points into conf_value and therefore requires conf_value to remain stable, but the implementation only calls parse(src) and never updates conf_value. This is misleading as written and also makes headers[] point into the caller-provided src buffer, whose lifetime may not be stable if this converter is ever used directly. Consider either updating conf_value consistently (and parsing from it) or adjusting the comment/implementation so the referenced backing storage and its required lifetime are unambiguous.

Suggested change

hdrs->parse(src);

hdrs->conf_value = src.data();

hdrs->parse(std::string_view{hdrs->conf_value, src.size()});

JakeChampion · 2026-02-08T08:32:05Z

Hi @JakeChampion

@bneradt if you wanted to - you could run this patchset/branch against the tests in cache-tests https://cache-tests.fyi/#cdn-cache-control and see how many ATS is now passing for ☺️

I ran the tests and no tests change. Note that this patch adds targeted cache control header support, which I don't think the cache-tests have tests for.

But it's good to verify that no new tests fail at least. :)

The section I linked too includes cdn-cache-control which I think is what you are also adding in this patch set, did those tests begin to pass?

bneradt · 2026-02-09T17:53:09Z

src/proxy/hdrs/MIME.cc

-    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).


assert that targeted_headers is non-nullptr.

zwoop · 2026-02-09T19:06:48Z

src/proxy/http/HttpConfig.cc

+  count = 0;
+  swoc::TextView config_view{src};
+
+  while (config_view && count < MAX_HEADERS) {


What happens if the config has more than MAX_HEADERS? Silent ignored it seems? Should we throw a warning at least (seems like that would indicate a configuration error).

zwoop · 2026-02-09T19:09:20Z

include/proxy/http/HttpConfig.h

+class TargetedCacheControlHeaders
+{
+public:
+  static const MgmtConverter Conv;


I know we don't do this consistently, but if the copy constructor / assignment constructor shouldn't be used (seems iffy with the raw pointer), should we = delete; them here ?

bneradt added this to the 10.2.0 milestone Nov 20, 2025

bneradt self-assigned this Nov 20, 2025

bneradt added Cache HTTP New Feature labels Nov 20, 2025

zwoop requested review from Copilot and zwoop November 20, 2025 20:06

Copilot started reviewing on behalf of zwoop November 20, 2025 20:07 View session

Copilot finished reviewing on behalf of zwoop November 20, 2025 20:09

Copilot AI reviewed Nov 20, 2025

View reviewed changes

src/api/InkAPI.cc Outdated Show resolved Hide resolved

bneradt commented Nov 20, 2025

View reviewed changes

bneradt force-pushed the targeted_cache_control branch 3 times, most recently from 57898a7 to c82d967 Compare November 24, 2025 19:55

zwoop reviewed Dec 10, 2025

View reviewed changes

bneradt force-pushed the targeted_cache_control branch from c82d967 to 1c6ae8a Compare December 11, 2025 03:17

bneradt added 2 commits February 6, 2026 20:05

WKS and custom config parsing updates

b2ee1ed

bneradt force-pushed the targeted_cache_control branch from 2a305ec to b2ee1ed Compare February 6, 2026 23:44

avoid <span> for old compilers

cb13f3d

zwoop requested review from Copilot and zwoop February 7, 2026 03:13

Copilot started reviewing on behalf of zwoop February 7, 2026 03:13 View session

Copilot AI reviewed Feb 7, 2026

View reviewed changes

bneradt commented Feb 9, 2026

View reviewed changes

zwoop reviewed Feb 9, 2026

View reviewed changes

		// If no targeted header was found, fall back to standard Cache-Control.
		if (!field) {

	hdrs->parse(src);
	hdrs->conf_value = src.data();
	hdrs->parse(std::string_view{hdrs->conf_value, src.size()});

Implement RFC 9213 Targeted HTTP Cache Control #12679

Are you sure you want to change the base?

Implement RFC 9213 Targeted HTTP Cache Control #12679

Uh oh!

Conversation

bneradt commented Nov 20, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

bneradt Nov 20, 2025

Choose a reason for hiding this comment

Uh oh!

bneradt Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JakeChampion commented Dec 10, 2025

Uh oh!

zwoop left a comment

Choose a reason for hiding this comment

Uh oh!

bneradt commented Dec 11, 2025

Uh oh!

bneradt commented Feb 7, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 7, 2026

Choose a reason for hiding this comment

Uh oh!

JakeChampion commented Feb 8, 2026

Uh oh!

bneradt Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

zwoop Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

zwoop Feb 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bneradt Nov 20, 2025 •

edited

Loading