draft-ietf-httpbis-targeted-cache-control-04.txt   draft-ietf-httpbis-targeted-cache-control-latest.txt 
HTTP Working Group S. Ludin HTTP Working Group S. Ludin
Internet-Draft Akamai Internet-Draft Akamai
Intended status: Standards Track M. Nottingham Intended status: Standards Track M. Nottingham
Expires: July 27, 2022 Fastly Expires: November 3, 2022 Fastly
Y. Wu Y. Wu
Cloudflare Cloudflare
January 23, 2022 May 2, 2022
Targeted HTTP Cache Control Targeted HTTP Cache Control
draft-ietf-httpbis-targeted-cache-control-04 draft-ietf-httpbis-targeted-cache-control-latest
Abstract Abstract
This specification defines a convention for HTTP response header This specification defines a convention for HTTP response header
fields that allow cache directives to be targeted at specific caches fields that allow cache directives to be targeted at specific caches
or classes of caches. It also defines one such header field, or classes of caches. It also defines one such header field, the
targeted at Content Delivery Network (CDN) caches. CDN-Cache-Control response header field, which is targeted at content
delivery network (CDN) caches.
About This Document About This Document
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
Status information for this document may be found at Status information for this document may be found at
<https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache- <https://datatracker.ietf.org/doc/draft-ietf-httpbis-targeted-cache-
control/>. control/>.
Discussion of this document takes place on the HTTP Working Group Discussion of this document takes place on the HTTP Working Group
skipping to change at page 2, line 7 skipping to change at page 2, line 7
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 27, 2022. This Internet-Draft will expire on November 3, 2022.
Copyright Notice Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 29 skipping to change at page 2, line 29
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3 2. Targeted Cache-Control Header Fields . . . . . . . . . . . . 3
2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.2. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 5 2.2. Cache Behavior . . . . . . . . . . . . . . . . . . . . . 5
2.3. Interaction with HTTP Freshness . . . . . . . . . . . . . 6 2.3. Interaction with HTTP Freshness . . . . . . . . . . . . . 6
2.4. Defining Targeted Fields . . . . . . . . . . . . . . . . 7 2.4. Defining Targeted Fields . . . . . . . . . . . . . . . . 7
3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 7 3. The CDN-Cache-Control Targeted Field . . . . . . . . . . . . 7
3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 7
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.1. Normative References . . . . . . . . . . . . . . . . . . 8 6.1. Normative References . . . . . . . . . . . . . . . . . . 8
6.2. Informative References . . . . . . . . . . . . . . . . . 9 6.2. Informative References . . . . . . . . . . . . . . . . . 9
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction 1. Introduction
Modern deployments of HTTP often use multiple layers of caching. For Modern deployments of HTTP often use multiple layers of caching. For
example, a website might use a cache on the origin server itself; it example, a website might use a cache on the origin server itself; it
might deploy a caching layer in the same network as the origin might deploy a caching layer in the same network as the origin
server, it might use one or more Content Delivery Networks (CDNs) server, it might use one or more CDNs that are distributed throughout
that are distributed throughout the Internet, and it might benefit the Internet, and it might benefit from browser caching as well.
from browser caching as well.
Because it is often desirable to control these different classes of Because it is often desirable to control these different classes of
caches separately, some means of targeting cache directives at them caches separately, some means of targeting cache directives at them
is necessary. For example, if a publisher has a mechanism to is necessary. For example, if a publisher has a mechanism to
invalidate the contents of a cache that it has a relationship with invalidate the contents of a cache that it has a relationship with
(such as a CDN cache), they might be more comfortable assigning a (such as a CDN cache), they might be more comfortable assigning a
more generous caching policy to it, while still wanting to restrict more generous caching policy to it while still wanting to restrict
the behavior of other caches. the behavior of other caches.
The HTTP Cache-Control response header field (defined in Section 5.2 The HTTP Cache-Control response header field (defined in Section 5.2
of [HTTP-CACHING]) is widely used to direct caching behavior. of [HTTP-CACHING]) is widely used to direct caching behavior.
However, it is relatively undifferentiated; while some cache However, it is relatively undifferentiated; while some cache
directives (e.g., s-maxage) are targeted at a specific class of directives (e.g., s-maxage) are targeted at a specific class of
caches (for s-maxage, shared caches), targeting is not consistently caches (for s-maxage, shared caches), targeting is not consistently
available across all existing cache directives (e.g., stale-while- available across all existing cache directives (e.g., stale-while-
revalidate). This is problematic, especially as the number of revalidate). This is problematic especially as the number of caching
caching extensions grows, along with the number of potential targets. extensions grows along with the number of potential targets.
Some implementations have defined ad hoc control mechanisms to Some implementations have defined ad hoc control mechanisms to
overcome this issue, but their interoperability is low. Section 2 overcome this issue, but their interoperability is low. Section 2
defines a standard framework for targeted cache control using HTTP defines a standard framework for targeted cache control using HTTP
response headers, and Section 3 defines one such header: the CDN- response headers, and Section 3 defines one such header: the CDN-
Cache-Control response header field. Cache-Control response header field.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP "OPTIONAL" in this document are to be interpreted as described in
14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
2. Targeted Cache-Control Header Fields 2. Targeted Cache-Control Header Fields
A Targeted Cache-Control Header Field (hereafter, "targeted field") A Targeted Cache-Control Header Field (hereafter "targeted field") is
is an HTTP response header field that has the same semantics as the an HTTP response header field that has the same semantics as the
Cache-Control response header field ([HTTP-CACHING], Section 5.2). Cache-Control response header field ([HTTP-CACHING], Section 5.2).
However, it has a distinct field name that indicates the target for However, it has a distinct field name that indicates the target for
its cache directives. its cache directives.
For example: For example:
CDN-Cache-Control: max-age=60 CDN-Cache-Control: max-age=60
is a targeted field that applies to Content Delivery Networks (CDNs), is a targeted field that applies to CDNs, as defined in Section 3.
as defined in Section 3.
2.1. Syntax 2.1. Syntax
Targeted fields are Dictionary Structured Fields (Section 3.2 of Targeted fields are Dictionary Structured Fields (Section 3.2 of
[STRUCTURED-FIELDS]). Each member of the dictionary is an HTTP cache [STRUCTURED-FIELDS]). Each member of the Dictionary is an HTTP cache
response directive (Section 5.2.2 of [HTTP-CACHING]) including response directive (Section 5.2.2 of [HTTP-CACHING]) including
extension response directives (as per Section 5.2.3 of extension response directives (as per Section 5.2.3 of
[HTTP-CACHING]). Note that while targeted fields often have the same [HTTP-CACHING]). Note that while targeted fields often have the same
syntax as Cache-Control fields, differences in error handling mean syntax as Cache-Control fields, differences in error handling mean
that using a Cache-Control parser rather than a Structured Fields that using a Cache-Control parser rather than a Structured Fields
parser can introduce interoperability issues. parser can introduce interoperability issues.
Because cache directives are not defined in terms of structured data Because cache directives are not defined in terms of structured data
types, it is necessary to map their values into the appropriate types, it is necessary to map their values into the appropriate
types. Section 5.2 of [HTTP-CACHING] defines cache directive values types. Section 5.2 of [HTTP-CACHING] defines cache directive values
to be either absent, a quoted-string, or a token. to be either absent, a quoted-string, or a token.
This means that cache directives that have no value will be mapped to This means that cache directives that have no value will be mapped to
a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). When the value is a Boolean (Section 3.3.6 of [STRUCTURED-FIELDS]). When the value is
a quoted-string, it will be mapped to a String (Section 3.3.3 of a quoted-string, it will be mapped to a String (Section 3.3.3 of
[STRUCTURED-FIELDS]), and when it is a token, it will map to a Token [STRUCTURED-FIELDS]), and when it is a token, it will map to a Token
(Section 3.3.4 of [STRUCTURED-FIELDS]), an Integer (Section 3.3.1 of (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]), or a Decimal (Section 3.3.2 of
[STRUCTURED-FIELDS]), depending on the content of the value. [STRUCTURED-FIELDS]), depending on the content of the value.
For example, the max-age directive (Section 5.2.2.1 of For example, the max-age directive (Section 5.2.2.1 of
[HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of [HTTP-CACHING]) has an integer value; no-store (Section 5.2.2.5 of
[HTTP-CACHING]) always has a boolean true value, and no-cache [HTTP-CACHING]) always has a Boolean true value, and no-cache
(Section 5.2.2.4 of [HTTP-CACHING]) has a value that can either be (Section 5.2.2.4 of [HTTP-CACHING]) has a value that can be either
boolean true or a string containing a comma-delimited list of field Boolean true or a string containing a comma-delimited list of field
names. names.
Implementations MUST NOT generate values that violate these inferred Implementations MUST NOT generate values that violate these inferred
constraints on the cache directive's value. In particular, string constraints on the cache directive's value. In particular, string
values whose first character is not alphabetic or "*" MUST be values whose first character is not alphabetic or "*" MUST be
generated as structured Strings, so they are not mistaken for other generated as Strings so that they are not mistaken for other types.
types.
Implementations SHOULD NOT consume values that violate these inferred Implementations SHOULD NOT consume values that violate these inferred
constraints. For example, a consuming implementation that coerces a constraints. For example, a consuming implementation that coerces a
max-age with a decimal value into an integer would behave differently max-age with a decimal value into an integer would behave differently
than other implementations, potentially causing interoperability than other implementations, potentially causing interoperability
issues. issues.
Parameters received on cache directives are to be ignored, unless Parameters received on cache directives are to be ignored, unless
other handling is explicitly specified. other handling is explicitly specified.
If a targeted field in a given response is empty, or a parsing error If a targeted field in a given response is empty, or a parsing error
is encountered, that field MUST be ignored by the cache (i.e., it is encountered, that field MUST be ignored by the cache (i.e., it
behaves as if the field were not present, likely falling back to behaves as if the field were not present, likely falling back to
other cache-control mechanisms present). other cache-control mechanisms present).
2.2. Cache Behavior 2.2. Cache Behavior
A cache that implements this specification maintains a _target list_ A cache that implements this specification maintains a target list.
- an ordered list of the targeted field names that it uses for A target list is an ordered list of the targeted field names that it
caching policy, with the order reflecting priority from most uses for caching policy, with the order reflecting priority from most
applicable to least. The target list might be fixed, user- applicable to least. The target list might be fixed, user
configurable, or generated per request, depending upon the configurable, or generated per request, depending upon the
implementation. implementation.
For example, a CDN cache might support both CDN-Cache-Control and a For example, a CDN cache might support both CDN-Cache-Control and a
header specific to that CDN, ExampleCDN-Cache-Control, with the header specific to that CDN, ExampleCDN-Cache-Control, with the
latter overriding the former. Its target list would be: latter overriding the former. Its target list would be:
[ExampleCDN-Cache-Control, CDN-Cache-Control] [ExampleCDN-Cache-Control, CDN-Cache-Control]
When a cache that implements this specification receives a response When a cache that implements this specification receives a response
with one or more of the header field names on its target list, the with one or more of the header field names on its target list, the
cache MUST select the first (in target list order) field with a cache MUST select the first (in target-list order) field with a
valid, non-empty value and use its value to determine the caching valid, non-empty value and use its value to determine the caching
policy for the response, and MUST ignore the Cache-Control and policy for the response, and it MUST ignore the Cache-Control and
Expires header fields in that response, unless no valid, non-empty Expires header fields in that response, unless no valid, non-empty
value is available from the listed header fields. value is available from the listed header fields.
Note that this occurs on a response-by-response basis; if no member Note that this occurs on a response-by-response basis; if no member
of the cache's target list is present, valid and non-empty, a cache of the cache's target list is present, valid, and non-empty, a cache
falls back to other cache control mechanisms as required by HTTP falls back to other cache control mechanisms as required by HTTP
[HTTP-CACHING]. [HTTP-CACHING].
Targeted fields that are not on a cache's target list MUST NOT change Targeted fields that are not on a cache's target list MUST NOT change
that cache's behaviour, and MUST be passed through. that cache's behavior and MUST be passed through.
Caches that use a targeted field MUST implement the semantics of the Caches that use a targeted field MUST implement the semantics of the
following cache directives: following cache directives:
o max-age o max-age
o must-revalidate o must-revalidate
o no-store o no-store
skipping to change at page 6, line 4 skipping to change at page 5, line 48
o max-age o max-age
o must-revalidate o must-revalidate
o no-store o no-store
o no-cache o no-cache
o private o private
Furthermore, they SHOULD implement other cache directives (including Furthermore, they SHOULD implement other cache directives (including
extension cache directives) that they support in the Cache-Control extension cache directives) that they support in the Cache-Control
response header field. response header field.
The semantics and precedence of cache directives in a targeted field The semantics and precedence of cache directives in a targeted field
are the same as those in Cache-Control. In particular, no-store and are the same as those in Cache-Control. In particular, no-store and
no-cache make max-age inoperative, and unrecognised extension no-cache make max-age inoperative, and unrecognized extension
directives are ignored. directives are ignored.
2.3. Interaction with HTTP Freshness 2.3. Interaction with HTTP Freshness
HTTP caching has a single, end-to-end freshness model defined in HTTP caching has a single, end-to-end freshness model defined in
Section 4.2 of [HTTP-CACHING]. When additional freshness mechanisms Section 4.2 of [HTTP-CACHING]. When additional freshness mechanisms
are only available to some caches along a request path (for example, are only available to some caches along a request path (for example,
using targeted fields), their interactions need to be carefully using targeted fields), their interactions need to be carefully
considered. In particular, a targeted cache might have longer considered. In particular, a targeted cache might have longer
freshness lifetimes available to it than other caches, causing it to freshness lifetimes available to it than other caches, causing it to
skipping to change at page 6, line 32 skipping to change at page 6, line 29
stale to those other caches, negatively impacting cache efficiency. stale to those other caches, negatively impacting cache efficiency.
For example, a response stored by a CDN cache might be served with For example, a response stored by a CDN cache might be served with
the following headers: the following headers:
Age: 1800 Age: 1800
Cache-Control: max-age=600 Cache-Control: max-age=600
CDN-Cache-Control: max-age=3600 CDN-Cache-Control: max-age=3600
From the CDN's perspective, this response is still fresh after being From the CDN's perspective, this response is still fresh after being
cached for 30 minutes, while from other caches' standpoint, this cached for 30 minutes, while from the standpoint of other caches,
response is already stale. See [AGE-PENALTY] for more discussion. this response is already stale. See [AGE-PENALTY] for more
discussion.
When the targeted cache has a strong coherence mechanism (e.g., the When the targeted cache has a strong coherence mechanism (e.g., the
origin server has the ability to proactively invalidate cached origin server has the ability to proactively invalidate cached
responses), it is often desirable to mitigate these effects. Some responses), it is often desirable to mitigate these effects. Some
techniques seen in deployments include: techniques seen in deployments include:
o Removing the Age header field o Removing the Age header field
o Updating the Date header field value to the current time o Updating the Date header field value to the current time
o Updating the Expires header field value to the current time, plus o Updating the Expires header field value to the current time, plus
any Cache-Control: max-age value any Cache-Control: max-age value
This specification does not place any specific requirements on This specification does not place any specific requirements on
implementations to mitigate these effects, but definitions of implementations to mitigate these effects, but definitions of
targeted fields can do so. targeted fields can do so.
2.4. Defining Targeted Fields 2.4. Defining Targeted Fields
A targeted field for a particular class of cache can be defined by A targeted field for a particular class of cache can be defined by
requesting registration in the Hypertext Transfer Protocol (HTTP) requesting registration in the "Hypertext Transfer Protocol (HTTP)
Field Name Registry (<https://www.iana.org/assignments/http- Field Name Registry" (<https://www.iana.org/assignments/http-
fields/>). fields/>).
Registration requests can use this document as the specification Registration requests can use this document as the specification
document, in which case the Comments field should clearly define the document; in which case, the Comments field should clearly define the
class of caches that the targeted field applies to. Alternatively, class of caches that the targeted field applies to. Alternatively,
if other documentation for the field has been created, it can be used if other documentation for the field has been created, it can be used
as the specification document. as the specification document.
By convention, targeted fields have the suffix "-Cache-Control": By convention, targeted fields have the suffix "-Cache-Control",
e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be e.g., "ExampleCDN-Cache-Control". However, this suffix MUST NOT be
used on its own to identify targeted fields; it is only a convention. used on its own to identify targeted fields; it is only a convention.
3. The CDN-Cache-Control Targeted Field 3. The CDN-Cache-Control Targeted Field
The CDN-Cache-Control response header field is a targeted field The CDN-Cache-Control response header field is a targeted field
(Section 2) that allows origin servers to control the behaviour of (Section 2) that allows origin servers to control the behavior of CDN
CDN caches interposed between them and clients, separately from other caches interposed between them and clients separately from other
caches that might handle the response. caches that might handle the response.
It applies to caches that are part of a distributed network that It applies to caches that are part of a distributed network that
operate on behalf of an origin server (commonly called a Content operate on behalf of an origin server (commonly called a CDN).
Delivery Network or CDN).
CDN caches that use CDN-Cache-Control will typically forward this CDN caches that use CDN-Cache-Control will typically forward this
header so that downstream CDN caches can use it as well. However, header so that downstream CDN caches can use it as well. However,
they MAY remove it when this is undesirable (for example, when they MAY remove it when this is undesirable (for example, when
configured to do so because it is known not to be used downstream). configured to do so because it is known not to be used downstream).
3.1. Examples 3.1. Examples
For example, the following header fields would instruct a CDN cache For example, the following header fields would instruct a CDN cache
(i.e., a cache with a target list of "[CDN-Cache-Control]") to (i.e., a cache with a target list of "[CDN-Cache-Control]") to
skipping to change at page 8, line 19 skipping to change at page 8, line 19
prevent all caches from storing the response: prevent all caches from storing the response:
Cache-Control: no-store Cache-Control: no-store
Whereas these would prevent all caches except for CDN caches from Whereas these would prevent all caches except for CDN caches from
storing the response: storing the response:
Cache-Control: no-store Cache-Control: no-store
CDN-Cache-Control: none CDN-Cache-Control: none
(note that 'none' is not a registered cache directive; it is here to (Note that 'none' is not a registered cache directive; it is here to
avoid sending a header field with an empty value, which would be avoid sending a header field with an empty value, which would be
ignored) ignored.)
4. IANA Considerations 4. IANA Considerations
Please register the following entry in the Hypertext Transfer IANA has registered the following entry in the "Hypertext Transfer
Protocol (HTTP) Field Name Registry defined by [HTTP]: Protocol (HTTP) Field Name Registry" defined by [HTTP]:
o Field Name: CDN-Cache-Control Field Name: CDN-Cache-Control
o Status: permanent Status: permanent
o Specification Document: [this document] Specification Document: RFC 9213
o Comments: Cache directives targeted at Content Delivery Networks Comments: Cache directives targeted at content delivery networks
5. Security Considerations 5. Security Considerations
The security considerations of HTTP caching [HTTP-CACHING] apply. The security considerations of HTTP caching [HTTP-CACHING] apply.
The ability to carry multiple caching policies on a response can The ability to carry multiple caching policies on a response can
result in confusion about how a response will be cached in different result in confusion about how a response will be cached in different
systems, potentially resulting in unintentional reuse of responses systems, potentially resulting in unintentional reuse of responses
with sensitive information. For this reason, care must be exercised. with sensitive information. For this reason, care must be exercised.
 End of changes. 36 change blocks. 
53 lines changed or deleted 52 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/