RFC 9213

Targeted HTTP Cache Control

📅 published June 2022, from ietf

Targeted HTTP Cache Control 🎀

Okay bestie, this is RFC 9213 ✨ It's a Standards Track spec about letting servers aim cache rules at specific kinds of caches, like CDNs, instead of shouting the same instructions at everyone 📣

RFC number and title: RFC 9213, Targeted HTTP Cache Control
Authors: S. Ludin (Akamai), M. Nottingham (Fastly), Y. Wu (Cloudflare)
Category: Standards Track
Stream: Internet Engineering Task Force (IETF)
ISSN: 2070-1721
Date: June 2022
Obsoletes and updates: the header doesn't list either one 🌷

Abstract ✨

This spec gives HTTP response header fields a way to say "this cache rule is only for THIS kind of cache" 🎯 It also defines one such header, the CDN-Cache-Control response header field, which is aimed at content delivery network (CDN) caches 🌈

Status of This Memo 📜

This is an Internet Standards Track doc 💅 It's a product of the Internet Engineering Task Force (IETF), it represents the consensus of the IETF community, it got public review, and it was approved for publication by the Internet Engineering Steering Group (IESG). For more on Internet Standards, check Section 2 of RFC 7841.

Current status, errata, and feedback info live at https://www.rfc-editor.org/info/rfc9213 🔗

Copyright Notice ©️

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication. Please read those carefully, because they describe your rights and restrictions for this doc. Code Components pulled out of this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Revised BSD License 🫶

Table of Contents 🗺️

   1.  Introduction
     1.1.  Notational Conventions
   2.  Targeted Cache-Control Header Fields
     2.1.  Syntax
     2.2.  Cache Behavior
     2.3.  Interaction with HTTP Freshness
     2.4.  Defining Targeted Fields
   3.  The CDN-Cache-Control Targeted Field
     3.1.  Examples
   4.  IANA Considerations
   5.  Security Considerations
   6.  References
     6.1.  Normative References
     6.2.  Informative References
   Authors' Addresses

1. Introduction 🌸

Okay so modern HTTP setups love layers of caching 🥞 A website might have a cache on the origin server itself, a caching layer in the same network as the origin, one or more CDNs spread across the Internet, and even browser caching on top of all that.

Because these different kinds of caches are often managed separately, you need a way to aim cache directives at each one. Like, if a publisher can invalidate content in a cache they have a relationship with (say, a CDN cache), they might feel totally fine giving that cache a more generous policy while still keeping the other caches on a tighter leash 🔐

The HTTP Cache-Control response header field (defined in Section 5.2 of [HTTP-CACHING]) is what everyone uses to steer caching. The problem is it's kind of undifferentiated 😩 Some directives, like s-maxage, are already aimed at a specific class of caches (for s-maxage, shared caches). But targeting isn't consistently available across every directive, like stale-while-revalidate. That gets messier as the number of extensions grows, and the number of possible targets grows too.

Some implementations came up with ad hoc workarounds, but they don't interoperate well 🙃 Section 2 defines a standard framework for targeted cache control using HTTP response headers, and Section 3 defines one such header: the CDN-Cache-Control response header field.

1.1. Notational Conventions 📖

Heads up on the keyword fam 🫶 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Targeted Cache-Control Header Fields 🎯

A Targeted Cache-Control Header Field (hereafter "targeted field") is an HTTP response header field with the same semantics as the Cache-Control response header field ([HTTP-CACHING], Section 5.2). The difference is that it has its own field name, which tells you who the cache directives are for 💖

For example:

CDN-Cache-Control: max-age=60

That's a targeted field that applies to CDNs, as defined in Section 3 🌷

2.1. Syntax 🧩

Targeted fields are Dictionary Structured Fields (Section 3.2 of [STRUCTURED-FIELDS]). Each member of the Dictionary is an HTTP cache response directive (Section 5.2.2 of [HTTP-CACHING]), including extension response directives (as per Section 5.2.3 of [HTTP-CACHING]). Note that even though targeted fields often look just like Cache-Control fields, the error handling is different, so using a Cache-Control parser instead of a Structured Fields parser can cause interop issues 🙈

Cache directives aren't defined in terms of structured data types, so their values have to be mapped onto the right ones 🗺️ Section 5.2 of [HTTP-CACHING] says a cache directive value is either absent, a quoted-string, or a token.

So a directive with no value maps to a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). A quoted-string value maps to a String (Section 3.3.3 of [STRUCTURED-FIELDS]). A token maps to a Token (Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of [STRUCTURED-FIELDS]), or a Decimal (Section 3.3.2 of [STRUCTURED-FIELDS]), depending on what the value looks like.

For example, max-age (Section 5.2.2.1 of [HTTP-CACHING]) has an integer value. no-store (Section 5.2.2.5 of [HTTP-CACHING]) always has a Boolean true value. no-cache (Section 5.2.2.4 of [HTTP-CACHING]) can be either Boolean true or a string with a comma-delimited list of field names 🧃

Here's the big rule for generating values 🚨 Implementations MUST NOT generate values that break these inferred constraints on the cache directive's value. In particular, string values whose first character is not alphabetic or "*" MUST be generated as Strings, so they don't get mistaken for other types.

On the consuming side, implementations SHOULD NOT consume values that break these inferred constraints. For instance, if one implementation coerces a max-age with a decimal value into an integer, it'll behave differently from everyone else, and that can cause interop issues 😬

Parameters received on cache directives are to be ignored, unless some other handling is explicitly specified 🫧

Last one, and it matters: if a targeted field in a given response is empty, or you hit a parsing error, that field MUST be ignored by the cache. In other words, it acts like the field wasn't there at all, and the cache probably falls back to whatever other cache-control mechanisms are present 🔄

2.2. Cache Behavior 🧠

A cache that implements this spec keeps a target list. A target list is an ordered list of the targeted field names the cache uses for caching policy, with the order showing priority from most applicable to least applicable. The target list might be fixed, user configurable, or generated per request, depending on the implementation 🎛️

For example, a CDN cache might support both CDN-Cache-Control and a header specific to that CDN, ExampleCDN-Cache-Control, with the latter overriding the former. Its target list would be:

[ExampleCDN-Cache-Control, CDN-Cache-Control]

Now the main event 🌈✨ When a cache that implements this spec gets a response with one or more of the header field names on its target list, the cache MUST select the first field (in target-list order) that has a valid, non-empty value, and use its value to decide the caching policy for the response. It MUST ignore the Cache-Control and Expires header fields in that response, unless no valid, non-empty value is available from the listed header fields.

Note that this happens on a response-by-response basis. If no member of the cache's target list is present, valid, and non-empty, the cache falls back to other cache control mechanisms as required by HTTP [HTTP-CACHING] 🪜

Targeted fields that aren't on a cache's target list MUST NOT change that cache's behavior, and they MUST be passed through 🚪

Caches that use a targeted field MUST implement the semantics of the following cache directives:

max-age
must-revalidate
no-store
no-cache
private

Furthermore, they SHOULD implement other cache directives (including extension cache directives) that they support in the Cache-Control response header field 💜

The semantics and precedence of cache directives in a targeted field are the same as in Cache-Control. Specifically, no-store and no-cache make max-age inoperative, and unrecognized extension directives are ignored 🙅‍♀️

2.3. Interaction with HTTP Freshness ⏰

HTTP caching has a single, end-to-end freshness model, defined in Section 4.2 of [HTTP-CACHING]. When extra freshness mechanisms are only available to some caches along a request path (like with targeted fields), their interactions need to be carefully thought through 🧐 A targeted cache might have longer freshness lifetimes available to it than other caches. That means it can serve responses that look prematurely (or even immediately) stale to the other caches, which hurts cache efficiency 📉

For example, a response stored by a CDN cache might be served with these headers:

Age: 1800
Cache-Control: max-age=600
CDN-Cache-Control: max-age=3600

From the CDN's perspective, that response is still fresh after sitting in the cache for 30 minutes. From the standpoint of other caches, it's already stale 😭 See [AGE-PENALTY] for more discussion.

When the targeted cache has a strong coherence mechanism (for example, the origin server can proactively invalidate cached responses), it's often a good idea to mitigate these effects. Some techniques seen in deployments include:

Removing the Age header field
Updating the Date header field value to the current time
Updating the Expires header field value to the current time, plus any Cache-Control: max-age value

This specification does not place any specific requirements on implementations to mitigate these effects, but definitions of targeted fields can do so 🌸

2.4. Defining Targeted Fields ✨

okay so if you want a new targeted field for a specific kind of cache, you request registration in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" at https://www.iana.org/assignments/http-fields/ 💅

you can use this document as your specification document for the request 🎀 in that case, the Comments field should clearly say which class of caches the targeted field applies to 🦋 or, if you already wrote other documentation for your field, you can use that as the specification document instead 🌸

by convention, targeted fields end with the suffix "-Cache-Control", like "ExampleCDN-Cache-Control" 💖 but this suffix MUST NOT be used on its own to identify targeted fields 🙈 it's just a naming habit, not the actual rule, bestie

3. The CDN-Cache-Control Targeted Field ✨

the CDN-Cache-Control response header field is a targeted field (Section 2) 🌈 it lets origin servers control how CDN caches sitting between them and clients behave, separately from any other caches that might handle the same response 👑 main character energy, honestly 💅

it applies to caches that are part of a distributed network operating on behalf of an origin server (the ones commonly called a CDN) 🧚

CDN caches that use CDN-Cache-Control will usually forward this header, so that downstream CDN caches can use it too 🫶 however, they MAY remove it when that's undesirable 💀 for example, when they've been configured to do so because it's known not to be used downstream 🍓

3.1. Examples ✨

okay, examples time 🎀 the following header fields would tell a CDN cache (that's a cache with a target list of [CDN-Cache-Control]) to treat the response as fresh for 600 seconds 💜 other shared caches would treat it as fresh for 120 seconds, and any remaining caches would treat it as fresh for 60 seconds 🦋

Cache-Control: max-age=60, s-maxage=120
CDN-Cache-Control: max-age=600

these header fields would tell a CDN cache to consider the response fresh for 600 seconds, while all other caches are blocked from storing it 😭

CDN-Cache-Control: max-age=600
Cache-Control: no-store

because CDN-Cache-Control is not present here, this header field stops all caches from storing the response 🙈

Cache-Control: no-store

and these ones stop all caches except CDN caches from storing the response 🌸

Cache-Control: no-store
CDN-Cache-Control: none

(ngl, 'none' is not a registered cache directive 🤓 it's only there so you don't send a header field with an empty value, because that would get ignored 💅)

4. IANA Considerations ✨

IANA has registered the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" that's defined by [HTTP] 🎀

Field Name:  CDN-Cache-Control
Status:  permanent
Specification Document:  RFC 9213
Comments:  Cache directives targeted at content delivery networks

5. Security Considerations ✨

okay this part is serious, bestie, so listen up 🚨 the security considerations of HTTP caching [HTTP-CACHING] apply here too 🔒

⚠️ the ability to carry multiple caching policies on a single response can cause real confusion about how that response gets cached in different systems 😱 this can potentially lead to unintentional reuse of responses that contain sensitive information 💀 for this reason, care must be exercised, no exceptions 🫶

6. References ✨

6.1. Normative References 💜

[HTTP]     Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Semantics", STD 97, RFC 9110,
           DOI 10.17487/RFC9110, June 2022,
           <https://www.rfc-editor.org/info/rfc9110>.

[HTTP-CACHING]
           Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "HTTP Caching", STD 98, RFC 9111,
           DOI 10.17487/RFC9111, June 2022,
           <https://www.rfc-editor.org/info/rfc9111>.

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[STRUCTURED-FIELDS]
           Nottingham, M. and P-H. Kamp, "Structured Field Values for
           HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
           <https://www.rfc-editor.org/info/rfc8941>.

6.2. Informative References 🌈

[AGE-PENALTY]
           Cohen, E. and H. Kaplan, "The age penalty and its effect
           on cache performance", March 2001,
           <https://dl.acm.org/doi/10.5555/1251440.1251447>.

Authors' Addresses 🦋

Stephen Ludin
Akamai
Email: sludin@ludin.org


Mark Nottingham
Fastly
Prahran
Australia
Email: mnot@mnot.net
URI:   https://www.mnot.net/


Yuchen Wu
Cloudflare
Email: me@yuchenwu.net

and that's a wrap on RFC 9213, bestie 🌈✨ you now know how CDN-Cache-Control works, how to define your own targeted fields, and why the security part is no joke 💖 periodt 💅

📦 where this page comes from

ietf: rfc9213 2022-06
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms