draft-ietf-httpbis-cache-17.txt   draft-ietf-httpbis-cache-18.txt 
HTTP Working Group R. Fielding, Ed. HTTP Working Group R. Fielding, Ed.
Internet-Draft Adobe Internet-Draft Adobe
Obsoletes: 7234 (if approved) M. Nottingham, Ed. Obsoletes: 7234 (if approved) M. Nottingham, Ed.
Intended status: Standards Track Fastly Intended status: Standards Track Fastly
Expires: 27 January 2022 J. Reschke, Ed. Expires: 19 February 2022 J. Reschke, Ed.
greenbytes greenbytes
26 July 2021 18 August 2021
HTTP Caching HTTP Caching
draft-ietf-httpbis-cache-17 draft-ietf-httpbis-cache-18
Abstract Abstract
The Hypertext Transfer Protocol (HTTP) is a stateless application- The Hypertext Transfer Protocol (HTTP) is a stateless application-
level protocol for distributed, collaborative, hypertext information level protocol for distributed, collaborative, hypertext information
systems. This document defines HTTP caches and the associated header systems. This document defines HTTP caches and the associated header
fields that control cache behavior or indicate cacheable response fields that control cache behavior or indicate cacheable response
messages. messages.
This document obsoletes RFC 7234. This document obsoletes RFC 7234.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
Discussion of this draft takes place on the HTTP working group Discussion of this draft takes place on the HTTP working group
mailing list (ietf-http-wg@w3.org), which is archived at mailing list (ietf-http-wg@w3.org), which is archived at
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. <https://lists.w3.org/Archives/Public/ietf-http-wg/>.
Working Group information can be found at <https://httpwg.org/>; Working Group information can be found at <https://httpwg.org/>;
source code and issues list for this draft can be found at source code and issues list for this draft can be found at
<https://github.com/httpwg/http-core>. <https://github.com/httpwg/http-core>.
The changes in this draft are summarized in Appendix C.18. The changes in this draft are summarized in Appendix C.19.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
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 27 January 2022. This Internet-Draft will expire on 19 February 2022.
Copyright Notice Copyright Notice
Copyright (c) 2021 IETF Trust and the persons identified as the Copyright (c) 2021 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 (https://trustee.ietf.org/ Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document. license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
skipping to change at page 3, line 10 skipping to change at page 3, line 10
3.3. Storing Incomplete Responses . . . . . . . . . . . . . . 10 3.3. Storing Incomplete Responses . . . . . . . . . . . . . . 10
3.4. Combining Partial Content . . . . . . . . . . . . . . . . 11 3.4. Combining Partial Content . . . . . . . . . . . . . . . . 11
3.5. Storing Responses to Authenticated Requests . . . . . . . 11 3.5. Storing Responses to Authenticated Requests . . . . . . . 11
4. Constructing Responses from Caches . . . . . . . . . . . . . 11 4. Constructing Responses from Caches . . . . . . . . . . . . . 11
4.1. Calculating Cache Keys with the Vary Header Field . . . . 13 4.1. Calculating Cache Keys with the Vary Header Field . . . . 13
4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 14 4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 14
4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 15 4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 15
4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 16 4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 16
4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 17 4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 17
4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 18 4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 18
4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 19 4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 18
4.3.1. Sending a Validation Request . . . . . . . . . . . . 19 4.3.1. Sending a Validation Request . . . . . . . . . . . . 19
4.3.2. Handling a Received Validation Request . . . . . . . 20 4.3.2. Handling a Received Validation Request . . . . . . . 20
4.3.3. Handling a Validation Response . . . . . . . . . . . 21 4.3.3. Handling a Validation Response . . . . . . . . . . . 21
4.3.4. Freshening Stored Responses upon Validation . . . . . 21 4.3.4. Freshening Stored Responses upon Validation . . . . . 21
4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 22 4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 22
4.4. Invalidating Stored Responses . . . . . . . . . . . . . . 23 4.4. Invalidating Stored Responses . . . . . . . . . . . . . . 23
5. Field Definitions . . . . . . . . . . . . . . . . . . . . . . 24 5. Field Definitions . . . . . . . . . . . . . . . . . . . . . . 24
5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 24 5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 24
5.2.1. Request Cache-Control Directives . . . . . . . . . . 25 5.2.1. Request Cache-Control Directives . . . . . . . . . . 25
skipping to change at page 4, line 22 skipping to change at page 4, line 22
C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 41 C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 41
C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 41 C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 41
C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 41 C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 41
C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 41 C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 41
C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 42 C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 42
C.7. Since draft-ietf-httpbis-cache-05 . . . . . . . . . . . . 42 C.7. Since draft-ietf-httpbis-cache-05 . . . . . . . . . . . . 42
C.8. Since draft-ietf-httpbis-cache-06 . . . . . . . . . . . . 42 C.8. Since draft-ietf-httpbis-cache-06 . . . . . . . . . . . . 42
C.9. Since draft-ietf-httpbis-cache-07 . . . . . . . . . . . . 43 C.9. Since draft-ietf-httpbis-cache-07 . . . . . . . . . . . . 43
C.10. Since draft-ietf-httpbis-cache-08 . . . . . . . . . . . . 43 C.10. Since draft-ietf-httpbis-cache-08 . . . . . . . . . . . . 43
C.11. Since draft-ietf-httpbis-cache-09 . . . . . . . . . . . . 43 C.11. Since draft-ietf-httpbis-cache-09 . . . . . . . . . . . . 43
C.12. Since draft-ietf-httpbis-cache-10 . . . . . . . . . . . . 44 C.12. Since draft-ietf-httpbis-cache-10 . . . . . . . . . . . . 43
C.13. Since draft-ietf-httpbis-cache-11 . . . . . . . . . . . . 44 C.13. Since draft-ietf-httpbis-cache-11 . . . . . . . . . . . . 44
C.14. Since draft-ietf-httpbis-cache-12 . . . . . . . . . . . . 44 C.14. Since draft-ietf-httpbis-cache-12 . . . . . . . . . . . . 44
C.15. Since draft-ietf-httpbis-cache-13 . . . . . . . . . . . . 45 C.15. Since draft-ietf-httpbis-cache-13 . . . . . . . . . . . . 45
C.16. Since draft-ietf-httpbis-cache-14 . . . . . . . . . . . . 45 C.16. Since draft-ietf-httpbis-cache-14 . . . . . . . . . . . . 45
C.17. Since draft-ietf-httpbis-cache-15 . . . . . . . . . . . . 46 C.17. Since draft-ietf-httpbis-cache-15 . . . . . . . . . . . . 46
C.18. Since draft-ietf-httpbis-cache-16 . . . . . . . . . . . . 46 C.18. Since draft-ietf-httpbis-cache-16 . . . . . . . . . . . . 46
C.19. Since draft-ietf-httpbis-cache-17 . . . . . . . . . . . . 46
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 46
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 48
1. Introduction 1. Introduction
The Hypertext Transfer Protocol (HTTP) is a stateless application- The Hypertext Transfer Protocol (HTTP) is a stateless application-
level request/response protocol that uses extensible semantics and level request/response protocol that uses extensible semantics and
self-descriptive messages for flexible interaction with network-based self-descriptive messages for flexible interaction with network-based
hypertext information systems. It is typically used for distributed hypertext information systems. It is typically used for distributed
information systems, where the use of response caches can improve information systems, where the use of response caches can improve
performance. This document defines aspects of HTTP related to performance. This document defines aspects of HTTP related to
skipping to change at page 6, line 50 skipping to change at page 6, line 50
concepts of HTTP. concepts of HTTP.
Although caching is an entirely OPTIONAL feature of HTTP, it can be Although caching is an entirely OPTIONAL feature of HTTP, it can be
assumed that reusing a cached response is desirable and that such assumed that reusing a cached response is desirable and that such
reuse is the default behavior when no requirement or local reuse is the default behavior when no requirement or local
configuration prevents it. Therefore, HTTP cache requirements are configuration prevents it. Therefore, HTTP cache requirements are
focused on preventing a cache from either storing a non-reusable focused on preventing a cache from either storing a non-reusable
response or reusing a stored response inappropriately, rather than response or reusing a stored response inappropriately, rather than
mandating that caches always store and reuse particular responses. mandating that caches always store and reuse particular responses.
The _cache key_ is the information a cache uses to select a response The _cache key_ is the information a cache uses to choose a response
and is composed from, at a minimum, the request method and target URI and is composed from, at a minimum, the request method and target URI
used to retrieve the stored response; the method determines under used to retrieve the stored response; the method determines under
which circumstances that response can be used to satisfy a subsequent which circumstances that response can be used to satisfy a subsequent
request. However, many HTTP caches in common use today only cache request. However, many HTTP caches in common use today only cache
GET responses, and therefore only use the URI as the cache key, GET responses, and therefore only use the URI as the cache key,
forwarding other methods. forwarding other methods.
If a request target is subject to content negotiation, the cache A cache might store multiple responses for a request target that is
might store multiple responses for it. Caches differentiate these subject to content negotiation. Caches differentiate these responses
responses by incorporating values of the original request's selecting by incorporating some of the original request's header fields into
header fields into the cache key as well, using information in the the cache key as well, using information in the Vary response header
Vary response header field, as per Section 4.1. field, as per Section 4.1.
Caches might incorporate additional material into the cache key. For Caches might incorporate additional material into the cache key. For
example, user agent caches might include the referring site's example, user agent caches might include the referring site's
identity, thereby "double keying" the cache to avoid some privacy identity, thereby "double keying" the cache to avoid some privacy
risks (see Section 7.2). risks (see Section 7.2).
Most commonly, caches store the successful result of a retrieval Most commonly, caches store the successful result of a retrieval
request: i.e., a 200 (OK) response to a GET request, which contains a request: i.e., a 200 (OK) response to a GET request, which contains a
representation of the target resource (Section 9.3.1 of [HTTP]). representation of the target resource (Section 9.3.1 of [HTTP]).
However, it is also possible to store redirects, negative results However, it is also possible to store redirects, negative results
skipping to change at page 11, line 44 skipping to change at page 11, line 44
When presented with a request, a cache MUST NOT reuse a stored When presented with a request, a cache MUST NOT reuse a stored
response unless: response unless:
* The presented target URI (Section 7.1 of [HTTP]) and that of the * The presented target URI (Section 7.1 of [HTTP]) and that of the
stored response match, and stored response match, and
* the request method associated with the stored response allows it * the request method associated with the stored response allows it
to be used for the presented request, and to be used for the presented request, and
* selecting header fields nominated by the stored response (if any) * request header fields nominated by the stored response (if any)
match those presented (see Section 4.1), and match those presented (see Section 4.1), and
* the stored response does not contain the no-cache cache directive * the stored response does not contain the no-cache cache directive
(Section 5.2.2.4), unless it is successfully validated (Section 5.2.2.4), unless it is successfully validated
(Section 4.3), and (Section 4.3), and
* the stored response is either: * the stored response is either:
- fresh (see Section 4.2), or - fresh (see Section 4.2), or
skipping to change at page 12, line 42 skipping to change at page 12, line 42
network. However, note that if the response returned is not able to network. However, note that if the response returned is not able to
be used for some or all of the collapsed requests, additional latency be used for some or all of the collapsed requests, additional latency
might be introduced, because they will need to be forwarded to be might be introduced, because they will need to be forwarded to be
satisfied. satisfied.
When more than one suitable response is stored, a cache MUST use the When more than one suitable response is stored, a cache MUST use the
most recent one (as determined by the Date header field). It can most recent one (as determined by the Date header field). It can
also forward the request with "Cache-Control: max-age=0" or "Cache- also forward the request with "Cache-Control: max-age=0" or "Cache-
Control: no-cache" to disambiguate which response to use. Control: no-cache" to disambiguate which response to use.
A cache that does not have a clock available MUST NOT use stored A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate
responses without revalidating them upon every use. stored responses upon every use.
4.1. Calculating Cache Keys with the Vary Header Field 4.1. Calculating Cache Keys with the Vary Header Field
When a cache receives a request that can be satisfied by a stored When a cache receives a request that can be satisfied by a stored
response and that stored response contains a Vary header field response and that stored response contains a Vary header field
(Section 12.5.5 of [HTTP]), the cache MUST NOT use that stored (Section 12.5.5 of [HTTP]), the cache MUST NOT use that stored
response without revalidation unless all the selecting header fields response without revalidation unless all the presented request header
(nominated by that Vary field value) in the present request match fields nominated by that Vary field value match those fields in the
those fields in the original request (i.e., the request that caused original request (i.e., the request that caused the cached response
the cached response to be stored). to be stored).
The selecting header fields from two requests are defined to match if The header fields from two requests are defined to match if and only
and only if those in the first request can be transformed to those in if those in the first request can be transformed to those in the
the second request by applying any of: second request by applying any of:
* adding or removing whitespace, where allowed in the header field's * adding or removing whitespace, where allowed in the header field's
syntax syntax
* combining multiple header field lines with the same field name * combining multiple header field lines with the same field name
(see Section 5.2 of [HTTP]) (see Section 5.2 of [HTTP])
* normalizing both header field values in a way that is known to * normalizing both header field values in a way that is known to
have identical semantics, according to the header field's have identical semantics, according to the header field's
specification (e.g., reordering field values when order is not specification (e.g., reordering field values when order is not
significant; case-normalization, where values are defined to be significant; case-normalization, where values are defined to be
case-insensitive) case-insensitive)
If (after any normalization that might take place) a header field is If (after any normalization that might take place) a header field is
absent from a request, it can only match another request if it is absent from a request, it can only match another request if it is
also absent there. also absent there.
A stored response with a Vary header field value containing a member A stored response with a Vary header field value containing a member
"*" always fails to match. "*" always fails to match.
The stored response with matching selecting header fields is known as If multiple stored responses match, the cache will need to choose one
the _selected response_. to use. When a nominated request header field has a known mechanism
for ranking preference (e.g., qvalues on Accept and similar request
If multiple selected responses are available (potentially including header fields), that mechanism MAY be used to choose a preferred
responses without a Vary header field), the cache will need to choose response. If such a mechanism is not available, or leads to equally
one to use. When a selecting header field has a known mechanism for preferred responses, the most recent response (as determined by the
doing so (e.g., qvalues on Accept and similar request header fields), Date header field) is chosen, as per Section 4.
that mechanism MAY be used to select a preferred response. If such a
mechanism is not available, or leads to equally preferred responses,
the most recent response (as determined by the Date header field) is
used, as per Section 4.
Some resources mistakenly omit the Vary header field from their Some resources mistakenly omit the Vary header field from their
default response (i.e., the one sent when no more preferable response default response (i.e., the one sent when the request does not
is available), with the effect of selecting it for requests to that express any preferences), with the effect of choosing it for
resource even when more preferable responses are available. When a subsequent requests to that resource even when more preferable
cache has multiple responses for a target URI and one or more omits responses are available. When a cache has multiple stored responses
the Vary header field, it SHOULD use the most recent (see for a target URI and one or more omits the Vary header field, the
Section 4.2.3) valid Vary field value available to select an cache SHOULD choose the most recent (see Section 4.2.3) stored
appropriate response for the request. response with a valid Vary field value.
If no selected response is available, the cache cannot satisfy the If no stored response matches, the cache cannot satisfy the presented
presented request. Typically, it is forwarded to the origin server request. Typically, the request is forwarded to the origin server,
in a (possibly conditional; see Section 4.3) request. potentially with preconditions added to describe what responses the
cache has already stored (Section 4.3).
4.2. Freshness 4.2. Freshness
A _fresh_ response is one whose age has not yet exceeded its A _fresh_ response is one whose age has not yet exceeded its
freshness lifetime. Conversely, a _stale_ response is one where it freshness lifetime. Conversely, a _stale_ response is one where it
has. has.
A response's _freshness lifetime_ is the length of time between its A response's _freshness lifetime_ is the length of time between its
generation by the origin server and its expiration time. An generation by the origin server and its expiration time. An
_explicit expiration time_ is the time at which the origin server _explicit expiration time_ is the time at which the origin server
skipping to change at page 15, line 52 skipping to change at page 16, line 8
* If the cache is shared and the s-maxage response directive * If the cache is shared and the s-maxage response directive
(Section 5.2.2.10) is present, use its value, or (Section 5.2.2.10) is present, use its value, or
* If the max-age response directive (Section 5.2.2.1) is present, * If the max-age response directive (Section 5.2.2.1) is present,
use its value, or use its value, or
* If the Expires response header field (Section 5.3) is present, use * If the Expires response header field (Section 5.3) is present, use
its value minus the value of the Date response header field (using its value minus the value of the Date response header field (using
the time the message was received if it is not present, as per the time the message was received if it is not present, as per
Section 10.2.2 of [HTTP]), or Section 6.6.1 of [HTTP]), or
* Otherwise, no explicit expiration time is present in the response. * Otherwise, no explicit expiration time is present in the response.
A heuristic freshness lifetime might be applicable; see A heuristic freshness lifetime might be applicable; see
Section 4.2.2. Section 4.2.2.
Note that this calculation is intended to reduce clock skew by using Note that this calculation is intended to reduce clock skew by using
the clock information provided by the origin server whenever the clock information provided by the origin server whenever
possible. possible.
When there is more than one value present for a given directive When there is more than one value present for a given directive
skipping to change at page 17, line 30 skipping to change at page 17, line 30
been in transit along network paths. been in transit along network paths.
Age calculation uses the following data: Age calculation uses the following data:
_age_value_ The term "age_value" denotes the value of the Age header _age_value_ The term "age_value" denotes the value of the Age header
field (Section 5.1), in a form appropriate for arithmetic field (Section 5.1), in a form appropriate for arithmetic
operation; or 0, if not available. operation; or 0, if not available.
_date_value_ The term "date_value" denotes the value of the Date _date_value_ The term "date_value" denotes the value of the Date
header field, in a form appropriate for arithmetic operations. header field, in a form appropriate for arithmetic operations.
See Section 10.2.2 of [HTTP] for the definition of the Date header See Section 6.6.1 of [HTTP] for the definition of the Date header
field, and for requirements regarding responses without it. field, and for requirements regarding responses without it.
_now_ The term "now" means "the current value of the clock at the _now_ The term "now" means the current value of this
host performing the calculation". A host ought to use NTP implementation's clock (Section 5.6.7 of [HTTP]).
([RFC5905]) or some similar protocol to synchronize its clocks to
Coordinated Universal Time.
_request_time_ The current value of the clock at the host at the _request_time_ The value of the clock at the time of the request
time the request resulting in the stored response was made. that resulted in the stored response.
_response_time_ The current value of the clock at the host at the _response_time_ The value of the clock at the time the response was
time the response was received. received.
A response's age can be calculated in two entirely independent ways: A response's age can be calculated in two entirely independent ways:
1. the "apparent_age": response_time minus date_value, if the local 1. the "apparent_age": response_time minus date_value, if the
clock is reasonably well synchronized to the origin server's implementation's clock is reasonably well synchronized to the
clock. If the result is negative, the result is replaced by origin server's clock. If the result is negative, the result is
zero. replaced by zero.
2. the "corrected_age_value", if all of the caches along the 2. the "corrected_age_value", if all of the caches along the
response path implement HTTP/1.1 or greater. A cache MUST response path implement HTTP/1.1 or greater. A cache MUST
interpret this value relative to the time the request was interpret this value relative to the time the request was
initiated, not the time that the response was received. initiated, not the time that the response was received.
apparent_age = max(0, response_time - date_value); apparent_age = max(0, response_time - date_value);
response_delay = response_time - request_time; response_delay = response_time - request_time;
corrected_age_value = age_value + response_delay; corrected_age_value = age_value + response_delay;
skipping to change at page 19, line 9 skipping to change at page 18, line 46
A cache MUST NOT generate a stale response unless it is disconnected A cache MUST NOT generate a stale response unless it is disconnected
or doing so is explicitly permitted by the client or origin server or doing so is explicitly permitted by the client or origin server
(e.g., by the max-stale request directive in Section 5.2.1, by (e.g., by the max-stale request directive in Section 5.2.1, by
extension directives such as those defined in [RFC5861], or by extension directives such as those defined in [RFC5861], or by
configuration in accordance with an out-of-band contract). configuration in accordance with an out-of-band contract).
4.3. Validation 4.3. Validation
When a cache has one or more stored responses for a requested URI, When a cache has one or more stored responses for a requested URI,
but cannot serve any of them (e.g., because they are not fresh, or but cannot serve any of them (e.g., because they are not fresh, or
one cannot be selected; see Section 4.1), it can use the conditional one cannot be chosen; see Section 4.1), it can use the conditional
request mechanism (Section 13.1 of [HTTP]) in the forwarded request request mechanism (Section 13.1 of [HTTP]) in the forwarded request
to give the next inbound server an opportunity to select a valid to give the next inbound server an opportunity to choose a valid
stored response to use, updating the stored metadata in the process, stored response to use, updating the stored metadata in the process,
or to replace the stored response(s) with a new response. This or to replace the stored response(s) with a new response. This
process is known as _validating_ or _revalidating_ the stored process is known as _validating_ or _revalidating_ the stored
response. response.
4.3.1. Sending a Validation Request 4.3.1. Sending a Validation Request
When generating a conditional request for validation, a cache starts When generating a conditional request for validation, a cache starts
with either a request it is attempting to satisfy, or - if it is with either a request it is attempting to satisfy, or - if it is
initiating the request independently - it synthesises a request using initiating the request independently - it synthesises a request using
a stored response by copying the method, target URI, and request a stored response by copying the method, target URI, and request
header fields identified by the Vary header field (Section 4.1). header fields identified by the Vary header field (Section 4.1).
It then updates that request with one or more precondition header It then updates that request with one or more precondition header
fields. These contain validator metadata sourced from stored fields. These contain validator metadata sourced from stored
response(s) that have the same URI. Typically, this will include response(s) that have the same URI. Typically, this will include
only those stored responses(s) that have the same cache key, although only those stored responses(s) that have the same cache key, although
a cache is allowed to validate a response that it cannot select with a cache is allowed to validate a response that it cannot choose with
the request header fields it is sending (see Section 4.1). the request header fields it is sending (see Section 4.1).
The precondition header fields are then compared by recipients to The precondition header fields are then compared by recipients to
determine whether any stored response is equivalent to a current determine whether any stored response is equivalent to a current
representation of the resource. representation of the resource.
One such validator is the timestamp given in a Last-Modified header One such validator is the timestamp given in a Last-Modified header
field (Section 8.8.2 of [HTTP]), which can be used in an If-Modified- field (Section 8.8.2 of [HTTP]), which can be used in an If-Modified-
Since header field for response validation, or in an If-Unmodified- Since header field for response validation, or in an If-Unmodified-
Since or If-Range header field for representation selection (i.e., Since or If-Range header field for representation selection (i.e.,
skipping to change at page 20, line 5 skipping to change at page 19, line 39
representation with that timestamp). representation with that timestamp).
Another validator is the entity-tag given in an ETag field Another validator is the entity-tag given in an ETag field
(Section 8.8.3 of [HTTP]). One or more entity-tags, indicating one (Section 8.8.3 of [HTTP]). One or more entity-tags, indicating one
or more stored responses, can be used in an If-None-Match header or more stored responses, can be used in an If-None-Match header
field for response validation, or in an If-Match or If-Range header field for response validation, or in an If-Match or If-Range header
field for representation selection (i.e., the client is referring field for representation selection (i.e., the client is referring
specifically to one or more previously obtained representations with specifically to one or more previously obtained representations with
the listed entity-tags). the listed entity-tags).
When generating a conditional request for validation, a cache:
* MUST send the relevant entity-tags (using If-Match, If-None-Match,
or If-Range) if the entity-tags were provided in the stored
response(s) being validated.
* SHOULD send the Last-Modified value (using If-Modified-Since) if
the request is not for a subrange, a single stored response is
being validated, and that response contains a Last-Modified value.
* MAY send the Last-Modified value (using If-Unmodified-Since or If-
Range) if the request is for a subrange, a single stored response
is being validated, and that response contains only a Last-
Modified value (not an entity-tag).
In most cases, both validators are generated in cache validation
requests, even when entity-tags are clearly superior, to allow old
intermediaries that do not understand entity-tag preconditions to
respond appropriately.
4.3.2. Handling a Received Validation Request 4.3.2. Handling a Received Validation Request
Each client in the request chain may have its own cache, so it is Each client in the request chain may have its own cache, so it is
common for a cache at an intermediary to receive conditional requests common for a cache at an intermediary to receive conditional requests
from other (outbound) caches. Likewise, some user agents make use of from other (outbound) caches. Likewise, some user agents make use of
conditional requests to limit data transfers to recently modified conditional requests to limit data transfers to recently modified
representations or to complete the transfer of a partially retrieved representations or to complete the transfer of a partially retrieved
representation. representation.
If a cache receives a request that can be satisfied by reusing a If a cache receives a request that can be satisfied by reusing a
stored 200 (OK) or 206 (Partial Content) response, as per Section 4, stored 200 (OK) or 206 (Partial Content) response, as per Section 4,
the cache SHOULD evaluate any applicable conditional header field the cache SHOULD evaluate any applicable conditional header field
preconditions received in that request with respect to the preconditions received in that request with respect to the
corresponding validators contained within the selected response. corresponding validators contained within the stored response.
A cache MUST NOT evaluate conditional header fields that only apply A cache MUST NOT evaluate conditional header fields that only apply
to an origin server, occur in a request with semantics that cannot be to an origin server, occur in a request with semantics that cannot be
satisfied with a cached response, or occur in a request with a target satisfied with a cached response, or occur in a request with a target
resource for which it has no stored responses; such preconditions are resource for which it has no stored responses; such preconditions are
likely intended for some other (inbound) server. likely intended for some other (inbound) server.
The proper evaluation of conditional requests by a cache depends on The proper evaluation of conditional requests by a cache depends on
the received precondition header fields and their precedence. In the received precondition header fields and their precedence. In
summary, the If-Match and If-Unmodified-Since conditional header summary, the If-Match and If-Unmodified-Since conditional header
fields are not applicable to a cache, and If-None-Match takes fields are not applicable to a cache, and If-None-Match takes
precedence over If-Modified-Since. See Section 13.2.2 of [HTTP] for precedence over If-Modified-Since. See Section 13.2.2 of [HTTP] for
a complete specification of precondition precedence. a complete specification of precondition precedence.
A request containing an If-None-Match header field (Section 13.1.2 of A request containing an If-None-Match header field (Section 13.1.2 of
[HTTP]) indicates that the client wants to validate one or more of [HTTP]) indicates that the client wants to validate one or more of
its own stored responses in comparison to the stored response its own stored responses in comparison to the stored response chosen
selected by the cache (as per Section 4). by the cache (as per Section 4).
If an If-None-Match header field is not present, a request containing If an If-None-Match header field is not present, a request containing
an If-Modified-Since header field (Section 13.1.3 of [HTTP]) an If-Modified-Since header field (Section 13.1.3 of [HTTP])
indicates that the client wants to validate one or more of its own indicates that the client wants to validate one or more of its own
stored responses by modification date. stored responses by modification date.
If a request contains an If-Modified-Since header field and the Last- If a request contains an If-Modified-Since header field and the Last-
Modified header field is not present in a selected stored response, a Modified header field is not present in a stored response, a cache
cache SHOULD use the stored response's Date field value (or, if no SHOULD use the stored response's Date field value (or, if no Date
Date field is present, the time that the stored response was field is present, the time that the stored response was received) to
received) to evaluate the conditional. evaluate the conditional.
A cache that implements partial responses to range requests, as A cache that implements partial responses to range requests, as
defined in Section 14.2 of [HTTP], also needs to evaluate a received defined in Section 14.2 of [HTTP], also needs to evaluate a received
If-Range header field (Section 13.1.5 of [HTTP]) regarding its If-Range header field (Section 13.1.5 of [HTTP]) with respect to the
selected stored response. cache's chosen response.
When a cache decides to forward a request to revalidate its own When a cache decides to forward a request to revalidate its own
stored responses for a request that contains an If-None-Match list of stored responses for a request that contains an If-None-Match list of
entity-tags, the cache MAY combine the received list with a list of entity-tags, the cache MAY combine the received list with a list of
entity-tags from its own stored set of responses (fresh or stale) and entity-tags from its own stored set of responses (fresh or stale) and
send the union of the two lists as a replacement If-None-Match header send the union of the two lists as a replacement If-None-Match header
field value in the forwarded request. If a stored response contains field value in the forwarded request. If a stored response contains
only partial content, the cache MUST NOT include its entity-tag in only partial content, the cache MUST NOT include its entity-tag in
the union unless the request is for a range that would be fully the union unless the request is for a range that would be fully
satisfied by that partial stored response. If the response to the satisfied by that partial stored response. If the response to the
skipping to change at page 21, line 48 skipping to change at page 22, line 6
stored response, subject to its constraints on doing so (see stored response, subject to its constraints on doing so (see
Section 4.2.4), or retry the validation request. Section 4.2.4), or retry the validation request.
4.3.4. Freshening Stored Responses upon Validation 4.3.4. Freshening Stored Responses upon Validation
When a cache receives a 304 (Not Modified) response, it needs to When a cache receives a 304 (Not Modified) response, it needs to
identify stored responses that are suitable for updating with the new identify stored responses that are suitable for updating with the new
information provided, and then do so. information provided, and then do so.
The initial set of stored responses to update are those that could The initial set of stored responses to update are those that could
have been selected for that request - i.e., those that meet the have been chosen for that request - i.e., those that meet the
requirements in Section 4, except the last requirement to be fresh, requirements in Section 4, except the last requirement to be fresh,
able to be served stale or just validated. able to be served stale or just validated.
Then, that initial set of stored response(s) is further filtered by Then, that initial set of stored response(s) is further filtered by
the first match of: the first match of:
* If the new response contains one or more _strong validators_ (see * If the new response contains one or more _strong validators_ (see
Section 8.8.1 of [HTTP]), then each of those strong validators Section 8.8.1 of [HTTP]), then each of those strong validators
identify a selected representation for update. All the stored identify a selected representation for update. All the stored
responses in the initial set with one of those same strong responses in the initial set with one of those same strong
skipping to change at page 22, line 44 skipping to change at page 22, line 49
A response to the HEAD method is identical to what an equivalent A response to the HEAD method is identical to what an equivalent
request made with a GET would have been, without sending the content. request made with a GET would have been, without sending the content.
This property of HEAD responses can be used to invalidate or update a This property of HEAD responses can be used to invalidate or update a
cached GET response if the more efficient conditional GET request cached GET response if the more efficient conditional GET request
mechanism is not available (due to no validators being present in the mechanism is not available (due to no validators being present in the
stored response) or if transmission of the content is not desired stored response) or if transmission of the content is not desired
even if it has changed. even if it has changed.
When a cache makes an inbound HEAD request for a target URI and When a cache makes an inbound HEAD request for a target URI and
receives a 200 (OK) response, the cache SHOULD update or invalidate receives a 200 (OK) response, the cache SHOULD update or invalidate
each of its stored GET responses that could have been selected for each of its stored GET responses that could have been chosen for that
that request (see Section 4.1). request (see Section 4.1).
For each of the stored responses that could have been selected, if For each of the stored responses that could have been chosen, if the
the stored response and HEAD response have matching values for any stored response and HEAD response have matching values for any
received validator fields (ETag and Last-Modified) and, if the HEAD received validator fields (ETag and Last-Modified) and, if the HEAD
response has a Content-Length header field, the value of Content- response has a Content-Length header field, the value of Content-
Length matches that of the stored response, the cache SHOULD update Length matches that of the stored response, the cache SHOULD update
the stored response as described below; otherwise, the cache SHOULD the stored response as described below; otherwise, the cache SHOULD
consider the stored response to be stale. consider the stored response to be stale.
If a cache updates a stored response with the metadata provided in a If a cache updates a stored response with the metadata provided in a
HEAD response, the cache MUST use the header fields provided in the HEAD response, the cache MUST use the header fields provided in the
HEAD response to update the stored response (see Section 3.2). HEAD response to update the stored response (see Section 3.2).
skipping to change at page 33, line 31 skipping to change at page 33, line 31
expired"). expired").
If a response includes a Cache-Control header field with the max-age If a response includes a Cache-Control header field with the max-age
directive (Section 5.2.2.1), a recipient MUST ignore the Expires directive (Section 5.2.2.1), a recipient MUST ignore the Expires
header field. Likewise, if a response includes the s-maxage header field. Likewise, if a response includes the s-maxage
directive (Section 5.2.2.10), a shared cache recipient MUST ignore directive (Section 5.2.2.10), a shared cache recipient MUST ignore
the Expires header field. In both these cases, the value in Expires the Expires header field. In both these cases, the value in Expires
is only intended for recipients that have not yet implemented the is only intended for recipients that have not yet implemented the
Cache-Control header field. Cache-Control header field.
An origin server without a clock MUST NOT generate an Expires header An origin server without a clock (Section 5.6.7 of [HTTP]) MUST NOT
field unless its value represents a fixed time in the past (always generate an Expires header field unless its value represents a fixed
expired) or its value has been associated with the resource by a time in the past (always expired) or its value has been associated
system or user with a reliable clock. with the resource by a system with a clock.
Historically, HTTP required the Expires field value to be no more Historically, HTTP required the Expires field value to be no more
than a year in the future. While longer freshness lifetimes are no than a year in the future. While longer freshness lifetimes are no
longer prohibited, extremely large values have been demonstrated to longer prohibited, extremely large values have been demonstrated to
cause problems (e.g., clock overflows due to use of 32-bit integers cause problems (e.g., clock overflows due to use of 32-bit integers
for time values), and many caches will evict a response far sooner for time values), and many caches will evict a response far sooner
than that. than that.
5.4. Pragma 5.4. Pragma
skipping to change at page 35, line 22 skipping to change at page 35, line 22
Caches expose an additional attack surface, since the contents of the Caches expose an additional attack surface, since the contents of the
cache represent an attractive target for malicious exploitation. cache represent an attractive target for malicious exploitation.
Because cache contents persist after an HTTP request is complete, an Because cache contents persist after an HTTP request is complete, an
attack on the cache can reveal information long after a user believes attack on the cache can reveal information long after a user believes
that the information has been removed from the network. Therefore, that the information has been removed from the network. Therefore,
cache contents need to be protected as sensitive information. cache contents need to be protected as sensitive information.
In particular, because private caches are restricted to a single In particular, because private caches are restricted to a single
user, they can be used to reconstruct a user's activity. As a user, they can be used to reconstruct a user's activity. As a
result, is important for user agents to allow end users to control result, it is important for user agents to allow end users to control
them; for example, allowing stored responses to be removed for some them; for example, allowing stored responses to be removed for some
or all origin servers. or all origin servers.
7.1. Cache Poisoning 7.1. Cache Poisoning
Storing a malicious payload in a cache can extend the reach of an Storing a malicious payload in a cache can extend the reach of an
attacker to affect multiple users. Such "cache poisoning" attacks attacker to affect multiple users. Such "cache poisoning" attacks
happen when an attacker uses implementation flaws, elevated happen when an attacker uses implementation flaws, elevated
privileges, or other techniques to insert a response into a cache. privileges, or other techniques to insert a response into a cache.
This is especially effective when shared caches are used to This is especially effective when shared caches are used to
skipping to change at page 38, line 7 skipping to change at page 38, line 7
Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn
Codes" registry at <https://www.iana.org/assignments/http-warn-codes> Codes" registry at <https://www.iana.org/assignments/http-warn-codes>
to the effect that Warning is obsoleted. to the effect that Warning is obsoleted.
9. References 9. References
9.1. Normative References 9.1. Normative References
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", Work in Progress, Internet-Draft, Ed., "HTTP Semantics", Work in Progress, Internet-Draft,
draft-ietf-httpbis-semantics-17, 26 July 2021, draft-ietf-httpbis-semantics-18, 18 August 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
semantics-17>.
[HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft-
ietf-httpbis-messaging-17, 26 July 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis- <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
messaging-17>. semantics-18>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
skipping to change at page 38, line 41 skipping to change at page 38, line 35
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
9.2. Informative References 9.2. Informative References
[COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265, [COOKIE] Barth, A., "HTTP State Management Mechanism", RFC 6265,
DOI 10.17487/RFC6265, April 2011, DOI 10.17487/RFC6265, April 2011,
<https://www.rfc-editor.org/info/rfc6265>. <https://www.rfc-editor.org/info/rfc6265>.
[HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft-
ietf-httpbis-messaging-18, 18 August 2021,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
messaging-18>.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, Transfer Protocol -- HTTP/1.1", RFC 2616,
DOI 10.17487/RFC2616, June 1999, DOI 10.17487/RFC2616, June 1999,
<https://www.rfc-editor.org/info/rfc2616>. <https://www.rfc-editor.org/info/rfc2616>.
[RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale
Content", RFC 5861, DOI 10.17487/RFC5861, April 2010, Content", RFC 5861, DOI 10.17487/RFC5861, April 2010,
<https://www.rfc-editor.org/info/rfc5861>. <https://www.rfc-editor.org/info/rfc5861>.
[RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
"Network Time Protocol Version 4: Protocol and Algorithms
Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010,
<https://www.rfc-editor.org/info/rfc5905>.
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke,
Ed., "Hypertext Transfer Protocol (HTTP): Caching", Ed., "Hypertext Transfer Protocol (HTTP): Caching",
RFC 7234, DOI 10.17487/RFC7234, June 2014, RFC 7234, DOI 10.17487/RFC7234, June 2014,
<https://www.rfc-editor.org/info/rfc7234>. <https://www.rfc-editor.org/info/rfc7234>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26, Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017, RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>. <https://www.rfc-editor.org/info/rfc8126>.
skipping to change at page 46, line 36 skipping to change at page 46, line 33
issues?q=label%3Acaching+created%3A%3E2021-05-26> for a summary. issues?q=label%3Acaching+created%3A%3E2021-05-26> for a summary.
Furthermore: Furthermore:
* Addressed Genart last call review comments * Addressed Genart last call review comments
(<https://github.com/httpwg/http-core/issues/847>) (<https://github.com/httpwg/http-core/issues/847>)
* In Section 4.3.4, clarify that only selectable responses are * In Section 4.3.4, clarify that only selectable responses are
updated (<https://github.com/httpwg/http-core/issues/839>) updated (<https://github.com/httpwg/http-core/issues/839>)
C.19. Since draft-ietf-httpbis-cache-17
* Made reference to [HTTP/1.1] informative only
(<https://github.com/httpwg/http-core/issues/911>)
* Move cache-related aspects of validator use from [HTTP] into
Section 4.3.1 (<https://github.com/httpwg/http-core/issues/933>)
* Use term "clock" defined in Section 6.6.1 of [HTTP] throughout
(<https://github.com/httpwg/http-core/issues/953>)
* Throughout, disambiguate "selected representation" and "selected
response" (now "chosen response") (<https://github.com/httpwg/
http-core/issues/958>)
Acknowledgements Acknowledgements
See Appendix "Acknowledgements" of [HTTP]. See Appendix "Acknowledgements" of [HTTP].
Index Index
A C E F G H M N O P S V W A C E F G H M N O P S V W
A A
skipping to change at page 48, line 27 skipping to change at page 48, line 39
Pragma header field Section 5.4 Pragma header field Section 5.4
private (cache directive) Section 5.2.2.7 private (cache directive) Section 5.2.2.7
private cache Section 1 private cache Section 1
proxy-revalidate (cache directive) Section 5.2.2.8 proxy-revalidate (cache directive) Section 5.2.2.8
public (cache directive) Section 5.2.2.9 public (cache directive) Section 5.2.2.9
S S
s-maxage (cache directive) Section 5.2.2.10 s-maxage (cache directive) Section 5.2.2.10
selected response Section 4.1
shared cache Section 1 shared cache Section 1
stale Section 4.2 stale Section 4.2
V V
validator Section 4.3.1 validator Section 4.3.1
W W
Warning header field Section 5.5 Warning header field Section 5.5
 End of changes. 43 change blocks. 
95 lines changed or deleted 120 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/