HTTP Cache Groups
Tag HTTP responses with group names so a cache can drop related stored responses together.
Nottingham, M., "HTTP Cache Groups", RFC 9875, DOI 10.17487/RFC9875, October 2025, <https://www.rfc-editor.org/info/rfc9875>.
@misc{rfc9875,
series = {Request for Comments},
number = 9875,
howpublished = {RFC 9875},
publisher = {RFC Editor},
doi = {10.17487/RFC9875},
url = {https://www.rfc-editor.org/info/rfc9875},
author = {M. Nottingham},
title = {{HTTP Cache Groups}},
pagetotal = 6,
year = 2025,
month = oct,
} RFC text
Contents
Internet Engineering Task Force (IETF) M. Nottingham
Request for Comments: 9875 Cloudflare
Category: Standards Track October 2025
ISSN: 2070-1721
HTTP Cache Groups
Abstract
This specification introduces a means of describing the relationships
between stored responses in HTTP caches, grouping them by associating
a stored response with one or more strings.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9875.
Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved.
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 of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Revised BSD License text as described in Section 4.e of the
Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents
1. Introduction
1.1. Notational Conventions
2. The Cache-Groups Response Header Field
2.1. Identifying Grouped Responses
2.2. Cache Behaviour
2.2.1. Invalidation
3. The Cache-Group-Invalidation Response Header Field
4. IANA Considerations
5. Security Considerations
6. References
6.1. Normative References
6.2. Informative References
Acknowledgements
Author's Address
1. Introduction
HTTP caching [HTTP-CACHING] operates at the granularity of a single
resource; the freshness of one stored response does not affect that
of others. This granularity can make caching more efficient -- for
example, when a page is composed of many assets that have different
requirements for caching.
However, there are also cases where the relationship between stored
responses could be used to improve cache efficiency.
For example, it is often necessary to invalidate a set of related
resources. This might be because a state-changing request has side
effects on other resources, or it might be purely for administrative
convenience (e.g., "invalidate this part of the site"). Grouping
responses together provides a dedicated way to express these
relationships, instead of relying on things like URL structure.
In addition to sharing invalidation events, the relationships
indicated by grouping can also be used by caches to optimise their
operation (e.g., to inform the operation of cache eviction
algorithms).
Section 2 introduces a means of describing the relationships between
stored responses in HTTP caches, by associating those responses with
one or more groups that reflect those relationships. It also
describes how caches can use that information to apply invalidation
events to members of a group.
Section 3 introduces one new source of such events: an HTTP response
header field that allows a state-changing response to trigger a group
invalidation.
These mechanisms operate within a single cache, across the stored
responses associated with a single origin server (see Section 2.1).
They do not address the issues of synchronising state between
multiple caches (e.g., in a hierarchy or mesh), nor do they
facilitate association of stored responses from disparate origins.
1.1. Notational Conventions
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.
This specification uses the following terminology from
[STRUCTURED-FIELDS]: List, String, and Parameter.
2. The Cache-Groups Response Header Field
The Cache-Groups response header field is a List of Strings (Sections
3.1 and 3.3.3 of [STRUCTURED-FIELDS]). Each member of the List is a
value that identifies a group that the response belongs to. These
Strings are opaque -- while they might have some meaning to the
server that creates them, the cache does not have any insight into
their structure or content (beyond uniquely identifying a group).
HTTP/1.1 200 OK
Content-Type: application/javascript
Cache-Control: max-age=3600
Cache-Groups: "scripts"
The ordering of members is not significant. Unrecognised Parameters
are to be ignored.
Implementations MUST support at least 32 groups in a field value,
with up to at least 32 characters in each member. Note that generic
limitations on HTTP field lengths may constrain the size of this
field value in practice.
2.1. Identifying Grouped Responses
Two responses stored in the same cache are considered to belong to
the same group when all of the following conditions are met:
1. They both contain a Cache-Groups response header field that
contains the same String (in any position in the List), when
compared character-by-character (case sensitive).
2. They both share the same URI origin (per Section 4.3.1 of
[HTTP]).
2.2. Cache Behaviour
2.2.1. Invalidation
A cache that invalidates a stored response MAY invalidate any stored
responses that share groups (per Section 2.1) with that response.
Note that further grouped invalidations are not triggered by a
grouped invalidation; i.e., this mechanism does not cascade.
Cache extensions can explicitly strengthen the requirement above.
For example, a targeted cache control header field [TARGETED] might
specify that caches processing it are required to invalidate such
responses.
3. The Cache-Group-Invalidation Response Header Field
The Cache-Group-Invalidation response header field is a List of
Strings (Sections 3.1 and 3.3.3 of [STRUCTURED-FIELDS]). Each member
of the List is a value that identifies a group that the response
invalidates, per Section 2.2.1.
For example, following a POST request that has side effects on two
cache groups, the corresponding response could indicate that stored
responses associated with either or both of those groups should be
invalidated with:
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Group-Invalidation: "eurovision-results", "australia"
The Cache-Group-Invalidation header field MUST be ignored on
responses to requests that have a safe method (e.g., GET; see
Section 9.2.1 of [HTTP]).
A cache that receives a Cache-Group-Invalidation header field on a
response to an unsafe request MAY invalidate any stored responses
that share groups (per Section 2.1) with any of the listed groups.
Cache extensions can explicitly strengthen the requirement above.
For example, a targeted cache control header field [TARGETED] might
specify that caches processing it are required to respect the Cache-
Group-Invalidation signal.
The ordering of members is not significant. Unrecognised Parameters
are to be ignored.
Implementations MUST support at least 32 groups in a field value,
with up to at least 32 characters in each member. Note that generic
limitations on HTTP field lengths may constrain the size of this
field value in practice.
4. IANA Considerations
IANA has added the following entries to the "Hypertext Transfer
Protocol (HTTP) Field Name Registry":
Field Name: Cache-Groups
Status: permanent
Reference: RFC 9875
Field Name: Cache-Group-Invalidation
Status: permanent
Reference: RFC 9875
5. Security Considerations
This mechanism allows resources that share an origin to invalidate
each other. Because of this, origins that represent multiple parties
(sometimes referred to as "shared hosting") might allow one party to
group its resources with those of others or to send signals that have
side effects upon them.
Shared hosts that wish to mitigate these risks can control access to
the header fields defined in this specification.
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. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/info/rfc9651>.
6.2. Informative References
[TARGETED] Ludin, S., Nottingham, M., and Y. Wu, "Targeted HTTP Cache
Control", RFC 9213, DOI 10.17487/RFC9213, June 2022,
<https://www.rfc-editor.org/info/rfc9213>.
Acknowledgements
Thanks to Stephen Ludin for his review and suggestions.
Author's Address
Mark Nottingham
Cloudflare
Melbourne
Australia
Email: mnot@mnot.net
URI: https://www.mnot.net/
AI ELI5
On this page
§1Why Group Cached Responses
HTTP caching, defined in RFC 9111, works on one resource at a time. The freshness of one stored response does not affect any other. That is efficient when a page is built from many assets with different caching needs.
Sometimes the relationship between responses matters. A state-changing request can have side effects on other resources, or an operator may just want to "invalidate this part of the site". Cache groups give a dedicated way to express those relationships instead of relying on URL structure. The RFC also notes that groups could inform cache eviction algorithms.
The scope is narrow. The mechanisms work within a single cache, across the stored responses of a single origin server. They do not synchronise state between caches in a hierarchy or mesh, and they do not link responses from different origins.
A web cache keeps copies of pages, but each copy is on its own. This idea lets the website say which copies belong together so they can be cleaned out together.
§2The Cache-Groups Header Field
The Cache-Groups response header field is a List of Strings in the Structured Fields format. Each member names a group the response belongs to. The strings are opaque: they may mean something to the server that creates them, but the cache cannot see any structure in them beyond using them to identify a group.
An example from the RFC is a script response carrying Cache-Groups: "scripts" next to Cache-Control: max-age=3600.
The order of members does not matter, and unrecognised Parameters are ignored. Implementations MUST support at least 32 groups in a field value, with up to at least 32 characters in each member. General limits on HTTP field length may restrict the field in practice.
The website writes one or more label words on each page it sends. The cache does not need to understand the words. It only needs to know which pages have the same word.
§3Who Is in the Same Group
Two responses stored in the same cache are in the same group only when both of these are true:
- Both have a
Cache-Groupsfield containing the same String, in any position, compared character by character and case sensitive. - Both share the same URI origin.
The origin condition means a group name is scoped to one origin. The string "scripts" on one site never ties together responses from another.
Two saved pages are in the same club only if they wear the exact same label and also come from the same website.
§4Invalidation Behaviour
When a cache invalidates a stored response, it MAY also invalidate any stored responses that share a group with it. The word is MAY, so a cache is allowed but not forced to do this. The mechanism does not cascade: an invalidation caused by grouping does not trigger further grouped invalidations.
Cache extensions can make this stricter. The RFC gives the example of a targeted cache control header field (RFC 9213) that requires caches processing it to invalidate such responses.
The second header, Cache-Group-Invalidation, is also a List of Strings. Each member names a group that the response invalidates. For instance, the response to a POST with side effects on two groups could carry Cache-Group-Invalidation: "eurovision-results", "australia".
The field MUST be ignored on responses to requests with a safe method such as GET. A cache that receives it on a response to an unsafe request MAY invalidate stored responses sharing any of the listed groups. Extensions can strengthen that too. The same minimums apply as for the other field: at least 32 groups, with at least 32 characters per member.
When one saved page is thrown out, the cache may throw out its label-mates too. A website can also shout the label names after changing something, so the cache clears them. Only changes count, not simple looking.
| Field | Says | Cache action |
|---|---|---|
| Cache-Groups | These groups contain this response | Used to find group members; cache MAY invalidate them when one is invalidated |
| Cache-Group-Invalidation | This response invalidates these groups | Ignored for safe methods; for unsafe requests the cache MAY invalidate members |
§5Shared Hosting Risk
Because resources that share an origin can invalidate each other, an origin that serves several parties (shared hosting) could let one party put its resources in another's groups or send signals that affect them.
The RFC's advice is that shared hosts wishing to reduce these risks can control access to the two header fields.
If many people share one notice board, one of them could use your label to make your notes get taken down. The board owner can decide who may use the labels.
§6IANA Registrations
IANA has added two entries to the Hypertext Transfer Protocol (HTTP) Field Name Registry: Cache-Groups and Cache-Group-Invalidation. Both have status permanent and reference RFC 9875.
The official list of header names now includes the two new ones, so nobody else will use those names for something different.