rfc9111.original | rfc9111.txt | |||
---|---|---|---|---|
HTTP Working Group R. Fielding, Ed. | Internet Engineering Task Force (IETF) R. Fielding, Ed. | |||
Internet-Draft Adobe | Request for Comments: 9111 Adobe | |||
Obsoletes: 7234 (if approved) M. Nottingham, Ed. | STD: 98 M. Nottingham, Ed. | |||
Intended status: Standards Track Fastly | Obsoletes: 7234 Fastly | |||
Expires: 14 March 2022 J. Reschke, Ed. | Category: Standards Track J. Reschke, Ed. | |||
greenbytes | ISSN: 2070-1721 greenbytes | |||
10 September 2021 | June 2022 | |||
HTTP Caching | HTTP Caching | |||
draft-ietf-httpbis-cache-19 | ||||
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. | |||
Editorial Note | ||||
This note is to be removed before publishing as an RFC. | ||||
Discussion of this draft takes place on the HTTP working group | ||||
mailing list (ietf-http-wg@w3.org), which is archived at | ||||
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. | ||||
Working Group information can be found at <https://httpwg.org/>; | ||||
source code and issues list for this draft can be found at | ||||
<https://github.com/httpwg/http-core>. | ||||
The changes in this draft are summarized in Appendix C.20. | ||||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This is an Internet Standards Track document. | |||
provisions of BCP 78 and BCP 79. | ||||
Internet-Drafts are working documents of the Internet Engineering | ||||
Task Force (IETF). Note that other groups may also distribute | ||||
working documents as Internet-Drafts. The list of current Internet- | ||||
Drafts is at https://datatracker.ietf.org/drafts/current/. | ||||
Internet-Drafts are draft documents valid for a maximum of six months | This document is a product of the Internet Engineering Task Force | |||
and may be updated, replaced, or obsoleted by other documents at any | (IETF). It represents the consensus of the IETF community. It has | |||
time. It is inappropriate to use Internet-Drafts as reference | received public review and has been approved for publication by the | |||
material or to cite them other than as "work in progress." | Internet Engineering Steering Group (IESG). Further information on | |||
Internet Standards is available in Section 2 of RFC 7841. | ||||
This Internet-Draft will expire on 14 March 2022. | 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/rfc9111. | ||||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2021 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 (https://trustee.ietf.org/ | Provisions Relating to IETF Documents | |||
license-info) in effect on the date of publication of this document. | (https://trustee.ietf.org/license-info) in effect on the date of | |||
Please review these documents carefully, as they describe your rights | publication of this document. Please review these documents | |||
and restrictions with respect to this document. Code Components | carefully, as they describe your rights and restrictions with respect | |||
extracted from this document must include Simplified BSD License text | to this document. Code Components extracted from this document must | |||
as described in Section 4.e of the Trust Legal Provisions and are | include Revised BSD License text as described in Section 4.e of the | |||
provided without warranty as described in the Simplified BSD License. | Trust Legal Provisions and are provided without warranty as described | |||
in the Revised BSD License. | ||||
This document may contain material from IETF Documents or IETF | This document may contain material from IETF Documents or IETF | |||
Contributions published or made publicly available before November | Contributions published or made publicly available before November | |||
10, 2008. The person(s) controlling the copyright in some of this | 10, 2008. The person(s) controlling the copyright in some of this | |||
material may not have granted the IETF Trust the right to allow | material may not have granted the IETF Trust the right to allow | |||
modifications of such material outside the IETF Standards Process. | modifications of such material outside the IETF Standards Process. | |||
Without obtaining an adequate license from the person(s) controlling | Without obtaining an adequate license from the person(s) controlling | |||
the copyright in such materials, this document may not be modified | the copyright in such materials, this document may not be modified | |||
outside the IETF Standards Process, and derivative works of it may | outside the IETF Standards Process, and derivative works of it may | |||
not be created outside the IETF Standards Process, except to format | not be created outside the IETF Standards Process, except to format | |||
it for publication as an RFC or to translate it into languages other | it for publication as an RFC or to translate it into languages other | |||
than English. | than English. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction | |||
1.1. Requirements Notation . . . . . . . . . . . . . . . . . . 5 | 1.1. Requirements Notation | |||
1.2. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 5 | 1.2. Syntax Notation | |||
1.2.1. Imported Rules . . . . . . . . . . . . . . . . . . . 5 | 1.2.1. Imported Rules | |||
1.2.2. Delta Seconds . . . . . . . . . . . . . . . . . . . . 6 | 1.2.2. Delta Seconds | |||
2. Overview of Cache Operation . . . . . . . . . . . . . . . . . 6 | 2. Overview of Cache Operation | |||
3. Storing Responses in Caches . . . . . . . . . . . . . . . . . 7 | 3. Storing Responses in Caches | |||
3.1. Storing Header and Trailer Fields . . . . . . . . . . . . 8 | 3.1. Storing Header and Trailer Fields | |||
3.2. Updating Stored Header Fields . . . . . . . . . . . . . . 9 | 3.2. Updating Stored Header Fields | |||
3.3. Storing Incomplete Responses . . . . . . . . . . . . . . 10 | 3.3. Storing Incomplete Responses | |||
3.4. Combining Partial Content . . . . . . . . . . . . . . . . 11 | 3.4. Combining Partial Content | |||
3.5. Storing Responses to Authenticated Requests . . . . . . . 11 | 3.5. Storing Responses to Authenticated Requests | |||
4. Constructing Responses from Caches . . . . . . . . . . . . . 11 | 4. Constructing Responses from Caches | |||
4.1. Calculating Cache Keys with the Vary Header Field . . . . 13 | 4.1. Calculating Cache Keys with the Vary Header Field | |||
4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 14 | 4.2. Freshness | |||
4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 15 | 4.2.1. Calculating Freshness Lifetime | |||
4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 16 | 4.2.2. Calculating Heuristic Freshness | |||
4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 17 | 4.2.3. Calculating Age | |||
4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 18 | 4.2.4. Serving Stale Responses | |||
4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 18 | 4.3. Validation | |||
4.3.1. Sending a Validation Request . . . . . . . . . . . . 19 | 4.3.1. Sending a Validation Request | |||
4.3.2. Handling a Received Validation Request . . . . . . . 20 | 4.3.2. Handling a Received Validation Request | |||
4.3.3. Handling a Validation Response . . . . . . . . . . . 21 | 4.3.3. Handling a Validation Response | |||
4.3.4. Freshening Stored Responses upon Validation . . . . . 21 | 4.3.4. Freshening Stored Responses upon Validation | |||
4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 22 | 4.3.5. Freshening Responses with HEAD | |||
4.4. Invalidating Stored Responses . . . . . . . . . . . . . . 23 | 4.4. Invalidating Stored Responses | |||
5. Field Definitions . . . . . . . . . . . . . . . . . . . . . . 24 | 5. Field Definitions | |||
5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 | 5.1. Age | |||
5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 24 | 5.2. Cache-Control | |||
5.2.1. Request Cache-Control Directives . . . . . . . . . . 25 | 5.2.1. Request Directives | |||
5.2.1.1. max-age . . . . . . . . . . . . . . . . . . . . . 25 | 5.2.1.1. max-age | |||
5.2.1.2. max-stale . . . . . . . . . . . . . . . . . . . . 25 | 5.2.1.2. max-stale | |||
5.2.1.3. min-fresh . . . . . . . . . . . . . . . . . . . . 26 | 5.2.1.3. min-fresh | |||
5.2.1.4. no-cache . . . . . . . . . . . . . . . . . . . . 26 | 5.2.1.4. no-cache | |||
5.2.1.5. no-store . . . . . . . . . . . . . . . . . . . . 26 | 5.2.1.5. no-store | |||
5.2.1.6. no-transform . . . . . . . . . . . . . . . . . . 27 | 5.2.1.6. no-transform | |||
5.2.1.7. only-if-cached . . . . . . . . . . . . . . . . . 27 | 5.2.1.7. only-if-cached | |||
5.2.2. Response Cache-Control Directives . . . . . . . . . . 27 | 5.2.2. Response Directives | |||
5.2.2.1. max-age . . . . . . . . . . . . . . . . . . . . . 27 | 5.2.2.1. max-age | |||
5.2.2.2. must-revalidate . . . . . . . . . . . . . . . . . 27 | 5.2.2.2. must-revalidate | |||
5.2.2.3. must-understand . . . . . . . . . . . . . . . . . 28 | 5.2.2.3. must-understand | |||
5.2.2.4. no-cache . . . . . . . . . . . . . . . . . . . . 28 | 5.2.2.4. no-cache | |||
5.2.2.5. no-store . . . . . . . . . . . . . . . . . . . . 29 | 5.2.2.5. no-store | |||
5.2.2.6. no-transform . . . . . . . . . . . . . . . . . . 29 | 5.2.2.6. no-transform | |||
5.2.2.7. private . . . . . . . . . . . . . . . . . . . . . 29 | 5.2.2.7. private | |||
5.2.2.8. proxy-revalidate . . . . . . . . . . . . . . . . 30 | 5.2.2.8. proxy-revalidate | |||
5.2.2.9. public . . . . . . . . . . . . . . . . . . . . . 30 | 5.2.2.9. public | |||
5.2.2.10. s-maxage . . . . . . . . . . . . . . . . . . . . 31 | 5.2.2.10. s-maxage | |||
5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 31 | 5.2.3. Extension Directives | |||
5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 32 | 5.2.4. Cache Directive Registry | |||
5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 32 | 5.3. Expires | |||
5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 33 | 5.4. Pragma | |||
5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 34 | 5.5. Warning | |||
6. Relationship to Applications and Other Caches . . . . . . . . 34 | 6. Relationship to Applications and Other Caches | |||
7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 | 7. Security Considerations | |||
7.1. Cache Poisoning . . . . . . . . . . . . . . . . . . . . . 35 | 7.1. Cache Poisoning | |||
7.2. Timing Attacks . . . . . . . . . . . . . . . . . . . . . 35 | 7.2. Timing Attacks | |||
7.3. Caching of Sensitive Information . . . . . . . . . . . . 36 | 7.3. Caching of Sensitive Information | |||
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 | 8. IANA Considerations | |||
8.1. Field Name Registration . . . . . . . . . . . . . . . . . 36 | 8.1. Field Name Registration | |||
8.2. Cache Directive Registration . . . . . . . . . . . . . . 37 | 8.2. Cache Directive Registration | |||
8.3. Warn Code Registry . . . . . . . . . . . . . . . . . . . 37 | 8.3. Warn Code Registry | |||
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 | 9. References | |||
9.1. Normative References . . . . . . . . . . . . . . . . . . 37 | 9.1. Normative References | |||
9.2. Informative References . . . . . . . . . . . . . . . . . 38 | 9.2. Informative References | |||
Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 39 | Appendix A. Collected ABNF | |||
Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 39 | Appendix B. Changes from RFC 7234 | |||
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 40 | Acknowledgements | |||
C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 40 | Index | |||
C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 41 | Authors' Addresses | |||
C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 41 | ||||
C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 41 | ||||
C.5. Since draft-ietf-httpbis-cache-03 . . . . . . . . . . . . 41 | ||||
C.6. Since draft-ietf-httpbis-cache-04 . . . . . . . . . . . . 42 | ||||
C.7. Since draft-ietf-httpbis-cache-05 . . . . . . . . . . . . 42 | ||||
C.8. Since draft-ietf-httpbis-cache-06 . . . . . . . . . . . . 42 | ||||
C.9. Since draft-ietf-httpbis-cache-07 . . . . . . . . . . . . 43 | ||||
C.10. Since draft-ietf-httpbis-cache-08 . . . . . . . . . . . . 43 | ||||
C.11. Since draft-ietf-httpbis-cache-09 . . . . . . . . . . . . 43 | ||||
C.12. Since draft-ietf-httpbis-cache-10 . . . . . . . . . . . . 43 | ||||
C.13. Since draft-ietf-httpbis-cache-11 . . . . . . . . . . . . 44 | ||||
C.14. Since draft-ietf-httpbis-cache-12 . . . . . . . . . . . . 44 | ||||
C.15. Since draft-ietf-httpbis-cache-13 . . . . . . . . . . . . 45 | ||||
C.16. Since draft-ietf-httpbis-cache-14 . . . . . . . . . . . . 45 | ||||
C.17. Since draft-ietf-httpbis-cache-15 . . . . . . . . . . . . 46 | ||||
C.18. Since draft-ietf-httpbis-cache-16 . . . . . . . . . . . . 46 | ||||
C.19. Since draft-ietf-httpbis-cache-17 . . . . . . . . . . . . 46 | ||||
C.20. Since draft-ietf-httpbis-cache-18 . . . . . . . . . . . . 46 | ||||
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 47 | ||||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 49 | ||||
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 | |||
caching and reusing response messages. | caching and reusing response messages. | |||
An HTTP _cache_ is a local store of response messages and the | An HTTP "cache" is a local store of response messages and the | |||
subsystem that controls storage, retrieval, and deletion of messages | subsystem that controls storage, retrieval, and deletion of messages | |||
in it. A cache stores cacheable responses to reduce the response | in it. A cache stores cacheable responses to reduce the response | |||
time and network bandwidth consumption on future equivalent requests. | time and network bandwidth consumption on future equivalent requests. | |||
Any client or server MAY use a cache, though not when acting as a | Any client or server MAY use a cache, though not when acting as a | |||
tunnel (Section 3.7 of [HTTP]). | tunnel (Section 3.7 of [HTTP]). | |||
A _shared cache_ is a cache that stores responses for reuse by more | A "shared cache" is a cache that stores responses for reuse by more | |||
than one user; shared caches are usually (but not always) deployed as | than one user; shared caches are usually (but not always) deployed as | |||
a part of an intermediary. A _private cache_, in contrast, is | a part of an intermediary. A "private cache", in contrast, is | |||
dedicated to a single user; often, they are deployed as a component | dedicated to a single user; often, they are deployed as a component | |||
of a user agent. | of a user agent. | |||
The goal of HTTP caching is significantly improving performance by | The goal of HTTP caching is significantly improving performance by | |||
reusing a prior response message to satisfy a current request. A | reusing a prior response message to satisfy a current request. A | |||
cache considers a stored response "fresh", as defined in Section 4.2, | cache considers a stored response "fresh", as defined in Section 4.2, | |||
if it can be reused without "validation" (checking with the origin | if it can be reused without "validation" (checking with the origin | |||
server to see if the cached response remains valid for this request). | server to see if the cached response remains valid for this request). | |||
A fresh response can therefore reduce both latency and network | A fresh response can therefore reduce both latency and network | |||
overhead each time the cache reuses it. When a cached response is | overhead each time the cache reuses it. When a cached response is | |||
not fresh, it might still be reusable if validation can freshen it | not fresh, it might still be reusable if validation can freshen it | |||
(Section 4.3) or if the origin is unavailable (Section 4.2.4). | (Section 4.3) or if the origin is unavailable (Section 4.2.4). | |||
This document obsoletes RFC 7234, with the changes being summarized | This document obsoletes RFC 7234, with the changes being summarized | |||
in Appendix B. | in Appendix B. | |||
1.1. Requirements Notation | 1.1. Requirements Notation | |||
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. | |||
Section 2 of [HTTP] defines conformance criteria and contains | Section 2 of [HTTP] defines conformance criteria and contains | |||
considerations regarding error handling. | considerations regarding error handling. | |||
1.2. Syntax Notation | 1.2. Syntax Notation | |||
This specification uses the Augmented Backus-Naur Form (ABNF) | This specification uses the Augmented Backus-Naur Form (ABNF) | |||
notation of [RFC5234], extended with the notation for case- | notation of [RFC5234], extended with the notation for case- | |||
sensitivity in strings defined in [RFC7405]. | sensitivity in strings defined in [RFC7405]. | |||
It also uses a list extension, defined in Section 5.6.1 of [HTTP], | It also uses a list extension, defined in Section 5.6.1 of [HTTP], | |||
that allows for compact definition of comma-separated lists using a | that allows for compact definition of comma-separated lists using a | |||
'#' operator (similar to how the '*' operator indicates repetition). | "#" operator (similar to how the "*" operator indicates repetition). | |||
Appendix A shows the collected grammar with all list operators | Appendix A shows the collected grammar with all list operators | |||
expanded to standard ABNF notation. | expanded to standard ABNF notation. | |||
1.2.1. Imported Rules | 1.2.1. Imported Rules | |||
The following core rule is included by reference, as defined in | The following core rule is included by reference, as defined in | |||
[RFC5234], Appendix B.1: DIGIT (decimal 0-9). | [RFC5234], Appendix B.1: DIGIT (decimal 0-9). | |||
[HTTP] defines the following rules: | [HTTP] defines the following rules: | |||
skipping to change at page 6, line 50 ¶ | skipping to change at line 247 ¶ | |||
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 choose 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. | ||||
A cache might store multiple responses for a request target that is | A cache might store multiple responses for a request target that is | |||
subject to content negotiation. Caches differentiate these responses | subject to content negotiation. Caches differentiate these responses | |||
by incorporating some of the original request's header fields into | by incorporating some of the original request's header fields into | |||
the cache key as well, using information in the Vary response header | the cache key as well, using information in the 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 | |||
skipping to change at page 7, line 29 ¶ | skipping to change at line 274 ¶ | |||
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 | |||
(e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial | (e.g., 404 (Not Found)), incomplete results (e.g., 206 (Partial | |||
Content)), and responses to methods other than GET if the method's | Content)), and responses to methods other than GET if the method's | |||
definition allows such caching and defines something suitable for use | definition allows such caching and defines something suitable for use | |||
as a cache key. | as a cache key. | |||
A cache is _disconnected_ when it cannot contact the origin server or | A cache is "disconnected" when it cannot contact the origin server or | |||
otherwise find a forward path for a request. A disconnected cache | otherwise find a forward path for a request. A disconnected cache | |||
can serve stale responses in some circumstances (Section 4.2.4). | can serve stale responses in some circumstances (Section 4.2.4). | |||
3. Storing Responses in Caches | 3. Storing Responses in Caches | |||
A cache MUST NOT store a response to a request unless: | A cache MUST NOT store a response to a request unless: | |||
* the request method is understood by the cache; | * the request method is understood by the cache; | |||
* the response status code is final (see Section 15 of [HTTP]); | * the response status code is final (see Section 15 of [HTTP]); | |||
* if the response status code is 206 or 304, or the "must- | * if the response status code is 206 or 304, or the must-understand | |||
understand" cache directive (see Section 5.2.2.3) is present: the | cache directive (see Section 5.2.2.3) is present: the cache | |||
cache understands the response status code; | understands the response status code; | |||
* the "no-store" cache directive is not present in the response (see | * the no-store cache directive is not present in the response (see | |||
Section 5.2.2.5); | Section 5.2.2.5); | |||
* if the cache is shared: the "private" response directive is either | * if the cache is shared: the private response directive is either | |||
not present or allows a shared cache to store a modified response; | not present or allows a shared cache to store a modified response; | |||
see Section 5.2.2.7); | see Section 5.2.2.7); | |||
* if the cache is shared: the Authorization header field is not | * if the cache is shared: the Authorization header field is not | |||
present in the request (see Section 11.6.2 of [HTTP]) or a | present in the request (see Section 11.6.2 of [HTTP]) or a | |||
response directive is present that explicitly allows shared | response directive is present that explicitly allows shared | |||
caching (see Section 3.5); and, | caching (see Section 3.5); and | |||
* the response contains at least one of: | * the response contains at least one of the following: | |||
- a public response directive (see Section 5.2.2.9); | - a public response directive (see Section 5.2.2.9); | |||
- a private response directive, if the cache is not shared (see | - a private response directive, if the cache is not shared (see | |||
Section 5.2.2.7); | Section 5.2.2.7); | |||
- an Expires header field (see Section 5.3); | - an Expires header field (see Section 5.3); | |||
- a max-age response directive (see Section 5.2.2.1); | - a max-age response directive (see Section 5.2.2.1); | |||
- if the cache is shared: an s-maxage response directive (see | - if the cache is shared: an s-maxage response directive (see | |||
Section 5.2.2.10); | Section 5.2.2.10); | |||
- a Cache Control Extension that allows it to be cached (see | - a cache extension that allows it to be cached (see | |||
Section 5.2.3); or, | Section 5.2.3); or | |||
- a status code that is defined as heuristically cacheable (see | - a status code that is defined as heuristically cacheable (see | |||
Section 4.2.2). | Section 4.2.2). | |||
Note that a cache-control extension can override any of the | Note that a cache extension can override any of the requirements | |||
requirements listed; see Section 5.2.3. | listed; see Section 5.2.3. | |||
In this context, a cache has "understood" a request method or a | In this context, a cache has "understood" a request method or a | |||
response status code if it recognizes it and implements all specified | response status code if it recognizes it and implements all specified | |||
caching-related behavior. | caching-related behavior. | |||
Note that, in normal operation, some caches will not store a response | Note that, in normal operation, some caches will not store a response | |||
that has neither a cache validator nor an explicit expiration time, | that has neither a cache validator nor an explicit expiration time, | |||
as such responses are not usually useful to store. However, caches | as such responses are not usually useful to store. However, caches | |||
are not prohibited from storing such responses. | are not prohibited from storing such responses. | |||
3.1. Storing Header and Trailer Fields | 3.1. Storing Header and Trailer Fields | |||
Caches MUST include all received response header fields - including | Caches MUST include all received response header fields -- including | |||
unrecognised ones - when storing a response; this assures that new | unrecognized ones -- when storing a response; this assures that new | |||
HTTP header fields can be successfully deployed. However, the | HTTP header fields can be successfully deployed. However, the | |||
following exceptions are made: | following exceptions are made: | |||
* The Connection header field and fields whose names are listed in | * The Connection header field and fields whose names are listed in | |||
it are required by Section 7.6.1 of [HTTP] to be removed before | it are required by Section 7.6.1 of [HTTP] to be removed before | |||
forwarding the message. This MAY be implemented by doing so | forwarding the message. This MAY be implemented by doing so | |||
before storage. | before storage. | |||
* Likewise, some fields' semantics require them to be removed before | * Likewise, some fields' semantics require them to be removed before | |||
forwarding the message, and this MAY be implemented by doing so | forwarding the message, and this MAY be implemented by doing so | |||
skipping to change at page 9, line 20 ¶ | skipping to change at line 361 ¶ | |||
directives can have arguments that prevent storage of header | directives can have arguments that prevent storage of header | |||
fields by all caches and shared caches, respectively. | fields by all caches and shared caches, respectively. | |||
* Header fields that are specific to the proxy that a cache uses | * Header fields that are specific to the proxy that a cache uses | |||
when forwarding a request MUST NOT be stored, unless the cache | when forwarding a request MUST NOT be stored, unless the cache | |||
incorporates the identity of the proxy into the cache key. | incorporates the identity of the proxy into the cache key. | |||
Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 | Effectively, this is limited to Proxy-Authenticate (Section 11.7.1 | |||
of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), | of [HTTP]), Proxy-Authentication-Info (Section 11.7.3 of [HTTP]), | |||
and Proxy-Authorization (Section 11.7.2 of [HTTP]). | and Proxy-Authorization (Section 11.7.2 of [HTTP]). | |||
Caches MAY either store trailer fields separate from header fields, | Caches MAY either store trailer fields separate from header fields or | |||
or discard them. Caches MUST NOT combine trailer fields with header | discard them. Caches MUST NOT combine trailer fields with header | |||
fields. | fields. | |||
3.2. Updating Stored Header Fields | 3.2. Updating Stored Header Fields | |||
Caches are required to update a stored response's header fields from | Caches are required to update a stored response's header fields from | |||
another (typically newer) response in several situations; for | another (typically newer) response in several situations; for | |||
example, see Section 3.4, Section 4.3.4 and Section 4.3.5. | example, see Sections 3.4, 4.3.4, and 4.3.5. | |||
When doing so, the cache MUST add each header field in the provided | When doing so, the cache MUST add each header field in the provided | |||
response to the stored response, replacing field values that are | response to the stored response, replacing field values that are | |||
already present, with the following exceptions: | already present, with the following exceptions: | |||
* Header fields excepted from storage in Section 3.1, | * Header fields excepted from storage in Section 3.1, | |||
* Header fields that the cache's stored response depends upon, as | * Header fields that the cache's stored response depends upon, as | |||
described below, | described below, | |||
* Header fields that are automatically processed and removed by the | * Header fields that are automatically processed and removed by the | |||
recipient, as described below, and | recipient, as described below, and | |||
* The Content-Length header field. | * The Content-Length header field. | |||
In some cases, caches (especially in user agents) store the results | In some cases, caches (especially in user agents) store the results | |||
of processing the received response, rather than the response itself, | of processing the received response, rather than the response itself, | |||
and updating header fields that affect that processing can result in | and updating header fields that affect that processing can result in | |||
inconsistent behavior and security issues. Caches in this situation | inconsistent behavior and security issues. Caches in this situation | |||
MAY omit these header fields from updating stored responses on an | MAY omit these header fields from updating stored responses on an | |||
exceptional basis, but SHOULD limit such omission to those fields | exceptional basis but SHOULD limit such omission to those fields | |||
necessary to assure integrity of the stored response. | necessary to assure integrity of the stored response. | |||
For example, a browser might decode the content coding of a response | For example, a browser might decode the content coding of a response | |||
while it is being received, creating a disconnect between the data it | while it is being received, creating a disconnect between the data it | |||
has stored and the response's original metadata. Updating that | has stored and the response's original metadata. Updating that | |||
stored metadata with a different Content-Encoding header field would | stored metadata with a different Content-Encoding header field would | |||
be problematic. Likewise, a browser might store a post-parse HTML | be problematic. Likewise, a browser might store a post-parse HTML | |||
tree, rather than the content received in the response; updating the | tree rather than the content received in the response; updating the | |||
Content-Type header field would not be workable in this case, because | Content-Type header field would not be workable in this case because | |||
any assumptions about the format made in parsing would now be | any assumptions about the format made in parsing would now be | |||
invalid. | invalid. | |||
Furthermore, some fields are automatically processed and removed by | Furthermore, some fields are automatically processed and removed by | |||
the HTTP implementation; for example, the Content-Range header field. | the HTTP implementation, such as the Content-Range header field. | |||
Implementations MAY automatically omit such header fields from | Implementations MAY automatically omit such header fields from | |||
updates, even when the processing does not actually occur. | updates, even when the processing does not actually occur. | |||
Note that the Content-* prefix is not a signal that a header field is | Note that the Content-* prefix is not a signal that a header field is | |||
omitted from update; it is a convention for MIME header fields, not | omitted from update; it is a convention for MIME header fields, not | |||
HTTP. | HTTP. | |||
3.3. Storing Incomplete Responses | 3.3. Storing Incomplete Responses | |||
If the request method is GET, the response status code is 200 (OK), | If the request method is GET, the response status code is 200 (OK), | |||
and the entire response header section has been received, a cache MAY | and the entire response header section has been received, a cache MAY | |||
store a response body that is not complete (Section 3.4 of [HTTP]) if | store a response that is not complete (Section 6.1 of [HTTP]) | |||
the stored response is recorded as being incomplete. Likewise, a 206 | provided that the stored response is recorded as being incomplete. | |||
(Partial Content) response MAY be stored as if it were an incomplete | Likewise, a 206 (Partial Content) response MAY be stored as if it | |||
200 (OK) response. However, a cache MUST NOT store incomplete or | were an incomplete 200 (OK) response. However, a cache MUST NOT | |||
partial-content responses if it does not support the Range and | store incomplete or partial-content responses if it does not support | |||
Content-Range header fields or if it does not understand the range | the Range and Content-Range header fields or if it does not | |||
units used in those fields. | understand the range units used in those fields. | |||
A cache MAY complete a stored incomplete response by making a | A cache MAY complete a stored incomplete response by making a | |||
subsequent range request (Section 14.2 of [HTTP]) and combining the | subsequent range request (Section 14.2 of [HTTP]) and combining the | |||
successful response with the stored response, as defined in | successful response with the stored response, as defined in | |||
Section 3.4. A cache MUST NOT use an incomplete response to answer | Section 3.4. A cache MUST NOT use an incomplete response to answer | |||
requests unless the response has been made complete, or the request | requests unless the response has been made complete, or the request | |||
is partial and specifies a range wholly within the incomplete | is partial and specifies a range wholly within the incomplete | |||
response. A cache MUST NOT send a partial response to a client | response. A cache MUST NOT send a partial response to a client | |||
without explicitly marking it using the 206 (Partial Content) status | without explicitly marking it using the 206 (Partial Content) status | |||
code. | code. | |||
skipping to change at page 11, line 26 ¶ | skipping to change at line 455 ¶ | |||
When combining the new response with one or more stored responses, a | When combining the new response with one or more stored responses, a | |||
cache MUST update the stored response header fields using the header | cache MUST update the stored response header fields using the header | |||
fields provided in the new response, as per Section 3.2. | fields provided in the new response, as per Section 3.2. | |||
3.5. Storing Responses to Authenticated Requests | 3.5. Storing Responses to Authenticated Requests | |||
A shared cache MUST NOT use a cached response to a request with an | A shared cache MUST NOT use a cached response to a request with an | |||
Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any | Authorization header field (Section 11.6.2 of [HTTP]) to satisfy any | |||
subsequent request unless the response contains a Cache-Control field | subsequent request unless the response contains a Cache-Control field | |||
with a response directive (Section 5.2.2) that allows it to be stored | with a response directive (Section 5.2.2) that allows it to be stored | |||
by a shared cache and the cache conforms to the requirements of that | by a shared cache, and the cache conforms to the requirements of that | |||
directive for that response. | directive for that response. | |||
In this specification, the following response directives have such an | In this specification, the following response directives have such an | |||
effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), | effect: must-revalidate (Section 5.2.2.2), public (Section 5.2.2.9), | |||
and s-maxage (Section 5.2.2.10). | and s-maxage (Section 5.2.2.10). | |||
4. Constructing Responses from Caches | 4. Constructing Responses from Caches | |||
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 | |||
* request 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 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 one of the following: | |||
- fresh (see Section 4.2), or | - fresh (see Section 4.2), or | |||
- allowed to be served stale (see Section 4.2.4), or | - allowed to be served stale (see Section 4.2.4), or | |||
- successfully validated (see Section 4.3). | - successfully validated (see Section 4.3). | |||
Note that a cache-control extension can override any of the | Note that a cache extension can override any of the requirements | |||
requirements listed; see Section 5.2.3. | listed; see Section 5.2.3. | |||
When a stored response is used to satisfy a request without | When a stored response is used to satisfy a request without | |||
validation, a cache MUST generate an Age header field (Section 5.1), | validation, a cache MUST generate an Age header field (Section 5.1), | |||
replacing any present in the response with a value equal to the | replacing any present in the response with a value equal to the | |||
stored response's current_age; see Section 4.2.3. | stored response's current_age; see Section 4.2.3. | |||
A cache MUST write through requests with methods that are unsafe | A cache MUST write through requests with methods that are unsafe | |||
(Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not | (Section 9.2.1 of [HTTP]) to the origin server; i.e., a cache is not | |||
allowed to generate a reply to such a request before having forwarded | allowed to generate a reply to such a request before having forwarded | |||
the request and having received a corresponding response. | the request and having received a corresponding response. | |||
Also, note that unsafe requests might invalidate already-stored | Also, note that unsafe requests might invalidate already-stored | |||
responses; see Section 4.4. | responses; see Section 4.4. | |||
A response that is stored or storable can be used to satisfy multiple | A cache can use a response that is stored or storable to satisfy | |||
requests, provided that it is allowed to reuse that response for the | multiple requests, provided that it is allowed to reuse that response | |||
requests in question. This enables caches to _collapse requests_ - | for the requests in question. This enables a cache to "collapse | |||
or combine multiple incoming requests into a single forward request | requests" -- or combine multiple incoming requests into a single | |||
upon a cache miss - thereby reducing load on the origin server and | forward request upon a cache miss -- thereby reducing load on the | |||
network. However, note that if the response returned is not able to | origin server and network. Note, however, that if the cache cannot | |||
be used for some or all of the collapsed requests, additional latency | use the returned response for some or all of the collapsed requests, | |||
might be introduced, because they will need to be forwarded to be | it will need to forward the requests in order to satisfy them, | |||
satisfied. | potentially introducing additional latency. | |||
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 without a clock (Section 5.6.7 of [HTTP]) MUST revalidate | A cache without a clock (Section 5.6.7 of [HTTP]) MUST revalidate | |||
stored responses 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 | |||
skipping to change at page 13, line 17 ¶ | skipping to change at line 534 ¶ | |||
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 presented request header | response without revalidation unless all the presented request header | |||
fields nominated by that Vary field value match those fields in the | fields nominated by that Vary field value match those fields in the | |||
original request (i.e., the request that caused the cached response | original request (i.e., the request that caused the cached response | |||
to be stored). | to be stored). | |||
The header fields from two requests are defined to match if and only | The header fields from two requests are defined to match if and only | |||
if those in the first request can be transformed to those in the | if those in the first request can be transformed to those in the | |||
second request by applying any of: | second request by applying any of the following: | |||
* 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 | |||
skipping to change at page 14, line 21 ¶ | skipping to change at line 579 ¶ | |||
cache SHOULD choose the most recent (see Section 4.2.3) stored | cache SHOULD choose the most recent (see Section 4.2.3) stored | |||
response with a valid Vary field value. | response with a valid Vary field value. | |||
If no stored response matches, the cache cannot satisfy the presented | If no stored response matches, the cache cannot satisfy the presented | |||
request. Typically, the request is forwarded to the origin server, | request. Typically, the request is forwarded to the origin server, | |||
potentially with preconditions added to describe what responses the | potentially with preconditions added to describe what responses the | |||
cache has already stored (Section 4.3). | 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 | |||
intends that a stored response can no longer be used by a cache | intends that a stored response can no longer be used by a cache | |||
without further validation, whereas a _heuristic expiration time_ is | without further validation, whereas a "heuristic expiration time" is | |||
assigned by a cache when no explicit expiration time is available. | assigned by a cache when no explicit expiration time is available. | |||
A response's _age_ is the time that has passed since it was generated | A response's "age" is the time that has passed since it was generated | |||
by, or successfully validated with, the origin server. | by, or successfully validated with, the origin server. | |||
When a response is fresh, it can be used to satisfy subsequent | When a response is fresh, it can be used to satisfy subsequent | |||
requests without contacting the origin server, thereby improving | requests without contacting the origin server, thereby improving | |||
efficiency. | efficiency. | |||
The primary mechanism for determining freshness is for an origin | The primary mechanism for determining freshness is for an origin | |||
server to provide an explicit expiration time in the future, using | server to provide an explicit expiration time in the future, using | |||
either the Expires header field (Section 5.3) or the max-age response | either the Expires header field (Section 5.3) or the max-age response | |||
directive (Section 5.2.2.1). Generally, origin servers will assign | directive (Section 5.2.2.1). Generally, origin servers will assign | |||
skipping to change at page 15, line 45 ¶ | skipping to change at line 651 ¶ | |||
other than "GMT" to be invalid for calculating expiration. | other than "GMT" to be invalid for calculating expiration. | |||
Note that freshness applies only to cache operation; it cannot be | Note that freshness applies only to cache operation; it cannot be | |||
used to force a user agent to refresh its display or reload a | used to force a user agent to refresh its display or reload a | |||
resource. See Section 6 for an explanation of the difference between | resource. See Section 6 for an explanation of the difference between | |||
caches and history mechanisms. | caches and history mechanisms. | |||
4.2.1. Calculating Freshness Lifetime | 4.2.1. Calculating Freshness Lifetime | |||
A cache can calculate the freshness lifetime (denoted as | A cache can calculate the freshness lifetime (denoted as | |||
freshness_lifetime) of a response by using the first match of: | freshness_lifetime) of a response by evaluating the following rules | |||
and using the first match: | ||||
* 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 | |||
skipping to change at page 16, line 20 ¶ | skipping to change at line 675 ¶ | |||
* 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 | |||
(e.g., two Expires header field lines or multiple Cache-Control: max- | (e.g., two Expires header field lines or multiple Cache-Control: max- | |||
age directives), either the first occurrence should be used, or the | age directives), either the first occurrence should be used or the | |||
response should be considered stale. If directives conflict (e.g., | response should be considered stale. If directives conflict (e.g., | |||
both max-age and no-cache are present), the most restrictive | both max-age and no-cache are present), the most restrictive | |||
directive should be honored. Caches are encouraged to consider | directive should be honored. Caches are encouraged to consider | |||
responses that have invalid freshness information (e.g., a max-age | responses that have invalid freshness information (e.g., a max-age | |||
directive with non-integer content) to be stale. | directive with non-integer content) to be stale. | |||
4.2.2. Calculating Heuristic Freshness | 4.2.2. Calculating Heuristic Freshness | |||
Since origin servers do not always provide explicit expiration times, | Since origin servers do not always provide explicit expiration times, | |||
a cache MAY assign a heuristic expiration time when an explicit time | a cache MAY assign a heuristic expiration time when an explicit time | |||
is not specified, employing algorithms that use other field values | is not specified, employing algorithms that use other field values | |||
(such as the Last-Modified time) to estimate a plausible expiration | (such as the Last-Modified time) to estimate a plausible expiration | |||
time. This specification does not provide specific algorithms, but | time. This specification does not provide specific algorithms, but | |||
does impose worst-case constraints on their results. | it does impose worst-case constraints on their results. | |||
A cache MUST NOT use heuristics to determine freshness when an | A cache MUST NOT use heuristics to determine freshness when an | |||
explicit expiration time is present in the stored response. Because | explicit expiration time is present in the stored response. Because | |||
of the requirements in Section 3, this means that heuristics can only | of the requirements in Section 3, heuristics can only be used on | |||
be used on responses without explicit freshness whose status codes | responses without explicit freshness whose status codes are defined | |||
are defined as _heuristically cacheable_ (e.g., see Section 15.1 of | as "heuristically cacheable" (e.g., see Section 15.1 of [HTTP]) and | |||
[HTTP]), and those responses without explicit freshness that have | on responses without explicit freshness that have been marked as | |||
been marked as explicitly cacheable (e.g., with a "public" response | explicitly cacheable (e.g., with a public response directive). | |||
directive). | ||||
Note that in previous specifications heuristically cacheable response | Note that in previous specifications, heuristically cacheable | |||
status codes were called "cacheable by default." | response status codes were called "cacheable by default". | |||
If the response has a Last-Modified header field (Section 8.8.2 of | If the response has a Last-Modified header field (Section 8.8.2 of | |||
[HTTP]), caches are encouraged to use a heuristic expiration value | [HTTP]), caches are encouraged to use a heuristic expiration value | |||
that is no more than some fraction of the interval since that time. | that is no more than some fraction of the interval since that time. | |||
A typical setting of this fraction might be 10%. | A typical setting of this fraction might be 10%. | |||
| *Note:* Section 13.9 of [RFC2616] prohibited caches from | | *Note:* A previous version of the HTTP specification | |||
| calculating heuristic freshness for URIs with query components | | (Section 13.9 of [RFC2616]) prohibited caches from calculating | |||
| (i.e., those containing '?'). In practice, this has not been | | heuristic freshness for URIs with query components (i.e., those | |||
| widely implemented. Therefore, origin servers are encouraged | | containing "?"). In practice, this has not been widely | |||
| to send explicit directives (e.g., Cache-Control: no-cache) if | | implemented. Therefore, origin servers are encouraged to send | |||
| they wish to prevent caching. | | explicit directives (e.g., Cache-Control: no-cache) if they | |||
| wish to prevent caching. | ||||
4.2.3. Calculating Age | 4.2.3. Calculating Age | |||
The Age header field is used to convey an estimated age of the | The Age header field is used to convey an estimated age of the | |||
response message when obtained from a cache. The Age field value is | response message when obtained from a cache. The Age field value is | |||
the cache's estimate of the number of seconds since the origin server | the cache's estimate of the number of seconds since the origin server | |||
generated or validated the response. The Age value is therefore the | generated or validated the response. The Age value is therefore the | |||
sum of the time that the response has been resident in each of the | sum of the time that the response has been resident in each of the | |||
caches along the path from the origin server, plus the time it has | caches along the path from the origin server, plus the time it has | |||
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" | |||
field (Section 5.1), in a form appropriate for arithmetic | The term "age_value" denotes the value of the Age header field | |||
operation; or 0, if not available. | (Section 5.1), in a form appropriate for arithmetic operation; or | |||
0, if not available. | ||||
_date_value_ The term "date_value" denotes the value of the Date | "date_value" | |||
header field, in a form appropriate for arithmetic operations. | The term "date_value" denotes the value of the Date header field, | |||
See Section 6.6.1 of [HTTP] for the definition of the Date header | in a form appropriate for arithmetic operations. See | |||
field, and for requirements regarding responses without it. | Section 6.6.1 of [HTTP] for the definition of the Date header | |||
field and for requirements regarding responses without it. | ||||
_now_ The term "now" means the current value of this | "now" | |||
implementation's clock (Section 5.6.7 of [HTTP]). | The term "now" means the current value of this implementation's | |||
clock (Section 5.6.7 of [HTTP]). | ||||
_request_time_ The value of the clock at the time of the request | "request_time" | |||
that resulted in the stored response. | The value of the clock at the time of the request that resulted in | |||
the stored response. | ||||
_response_time_ The value of the clock at the time the response was | "response_time" | |||
received. | The value of the clock at the time the response was 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 | 1. the "apparent_age": response_time minus date_value, if the | |||
implementation's clock is reasonably well synchronized to the | implementation's clock is reasonably well synchronized to the | |||
origin server's clock. If the result is negative, the result is | origin server's clock. If the result is negative, the result is | |||
replaced by 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 | |||
skipping to change at page 18, line 31 ¶ | skipping to change at line 787 ¶ | |||
resident_time = now - response_time; | resident_time = now - response_time; | |||
current_age = corrected_initial_age + resident_time; | current_age = corrected_initial_age + resident_time; | |||
4.2.4. Serving Stale Responses | 4.2.4. Serving Stale Responses | |||
A "stale" response is one that either has explicit expiry information | A "stale" response is one that either has explicit expiry information | |||
or is allowed to have heuristic expiry calculated, but is not fresh | or is allowed to have heuristic expiry calculated, but is not fresh | |||
according to the calculations in Section 4.2. | according to the calculations in Section 4.2. | |||
A cache MUST NOT generate a stale response if it is prohibited by an | A cache MUST NOT generate a stale response if it is prohibited by an | |||
explicit in-protocol directive (e.g., by a "no-cache" cache | explicit in-protocol directive (e.g., by a no-cache response | |||
directive, a "must-revalidate" cache-response-directive, or an | directive, a must-revalidate response directive, or an applicable | |||
applicable "s-maxage" or "proxy-revalidate" cache-response-directive; | s-maxage or proxy-revalidate response directive; see Section 5.2.2). | |||
see Section 5.2.2). | ||||
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, extension | |||
extension directives such as those defined in [RFC5861], or by | directives such as those defined in [RFC5861], or configuration in | |||
configuration in accordance with an out-of-band contract). | 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 chosen; 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 of [HTTP]) in the forwarded request to | |||
to give the next inbound server an opportunity to choose a valid | give the next inbound server an opportunity to choose a valid stored | |||
stored response to use, updating the stored metadata in the process, | response to use, updating the stored metadata in the process, or to | |||
or to replace the stored response(s) with a new response. This | replace the stored response(s) with a new response. This process is | |||
process is known as _validating_ or _revalidating_ the stored | 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 either | |||
with either a request it is attempting to satisfy, or - if it is | starts with a request it is attempting to satisfy or -- if it is | |||
initiating the request independently - it synthesises a request using | initiating the request independently -- synthesizes a request using a | |||
a stored response by copying the method, target URI, and request | stored response by copying the method, target URI, and request header | |||
header fields identified by the Vary header field (Section 4.1). | 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 a stored | |||
response(s) that have the same URI. Typically, this will include | response(s) that has the same URI. Typically, this will include only | |||
only those stored responses(s) that have the same cache key, although | the stored response(s) that has the same cache key, although a cache | |||
a cache is allowed to validate a response that it cannot choose with | is allowed to validate a response that it cannot choose with the | |||
the request header fields it is sending (see Section 4.1). | 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., | |||
the client is referring specifically to a previously obtained | the client is referring specifically to a previously obtained | |||
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: | When generating a conditional request for validation, a cache: | |||
* MUST send the relevant entity-tags (using If-Match, If-None-Match, | * MUST send the relevant entity tags (using If-Match, If-None-Match, | |||
or If-Range) if the entity-tags were provided in the stored | or If-Range) if the entity tags were provided in the stored | |||
response(s) being validated. | response(s) being validated. | |||
* SHOULD send the Last-Modified value (using If-Modified-Since) if | * SHOULD send the Last-Modified value (using If-Modified-Since) if | |||
the request is not for a subrange, a single stored response is | the request is not for a subrange, a single stored response is | |||
being validated, and that response contains a Last-Modified value. | being validated, and that response contains a Last-Modified value. | |||
* MAY send the Last-Modified value (using If-Unmodified-Since or If- | * MAY send the Last-Modified value (using If-Unmodified-Since or If- | |||
Range) if the request is for a subrange, a single stored response | Range) if the request is for a subrange, a single stored response | |||
is being validated, and that response contains only a Last- | is being validated, and that response contains only a Last- | |||
Modified value (not an entity-tag). | Modified value (not an entity tag). | |||
In most cases, both validators are generated in cache validation | In most cases, both validators are generated in cache validation | |||
requests, even when entity-tags are clearly superior, to allow old | requests, even when entity tags are clearly superior, to allow old | |||
intermediaries that do not understand entity-tag preconditions to | intermediaries that do not understand entity tag preconditions to | |||
respond appropriately. | 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. | |||
skipping to change at page 21, line 12 ¶ | skipping to change at line 913 ¶ | |||
field is present, the time that the stored response was received) to | field is present, the time that the stored response was 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]) with respect to the | If-Range header field (Section 13.1.5 of [HTTP]) with respect to the | |||
cache's chosen 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 | |||
forwarded request is 304 (Not Modified) and has an ETag field value | forwarded request is 304 (Not Modified) and has an ETag field value | |||
with an entity-tag that is not in the client's list, the cache MUST | with an entity tag that is not in the client's list, the cache MUST | |||
generate a 200 (OK) response for the client by reusing its | generate a 200 (OK) response for the client by reusing its | |||
corresponding stored response, as updated by the 304 response | corresponding stored response, as updated by the 304 response | |||
metadata (Section 4.3.4). | metadata (Section 4.3.4). | |||
4.3.3. Handling a Validation Response | 4.3.3. Handling a Validation Response | |||
Cache handling of a response to a conditional request depends upon | Cache handling of a response to a conditional request depends upon | |||
its status code: | its status code: | |||
* A 304 (Not Modified) response status code indicates that the | * A 304 (Not Modified) response status code indicates that the | |||
stored response can be updated and reused; see Section 4.3.4. | stored response can be updated and reused; see Section 4.3.4. | |||
* A full response (i.e., one containing content) indicates that none | * A full response (i.e., one containing content) indicates that none | |||
of the stored responses nominated in the conditional request is | of the stored responses nominated in the conditional request are | |||
suitable. Instead, the cache MUST use the full response to | suitable. Instead, the cache MUST use the full response to | |||
satisfy the request. The cache MAY store such a full response, | satisfy the request. The cache MAY store such a full response, | |||
subject to its constraints (see Section 3). | subject to its constraints (see Section 3). | |||
* However, if a cache receives a 5xx (Server Error) response while | * However, if a cache receives a 5xx (Server Error) response while | |||
attempting to validate a response, it can either forward this | attempting to validate a response, it can either forward this | |||
response to the requesting client, or act as if the server failed | response to the requesting client or act as if the server failed | |||
to respond. In the latter case, the cache can send a previously | to respond. In the latter case, the cache can send a previously | |||
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 chosen 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 responses is further filtered by the | |||
the first match of: | 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 | identifies 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 | |||
validators are identified for update. If none of the initial set | validators are identified for update. If none of the initial set | |||
contain at least one of the same strong validators, then the cache | contains at least one of the same strong validators, then the | |||
MUST NOT use the new response to update any stored responses. | cache MUST NOT use the new response to update any stored | |||
responses. | ||||
* If the new response contains no strong validators but does contain | * If the new response contains no strong validators but does contain | |||
one or more _weak validators_, and those validators correspond to | one or more "weak validators", and those validators correspond to | |||
one of the initial set's stored responses, then the most recent of | one of the initial set's stored responses, then the most recent of | |||
those matching stored responses is identified for update. | those matching stored responses is identified for update. | |||
* If the new response does not include any form of validator (such | * If the new response does not include any form of validator (such | |||
as where a client generates an If-Modified-Since request from a | as where a client generates an If-Modified-Since request from a | |||
source other than the Last-Modified response header field), and | source other than the Last-Modified response header field), and | |||
there is only one stored response in the initial set, and that | there is only one stored response in the initial set, and that | |||
stored response also lacks a validator, then that stored response | stored response also lacks a validator, then that stored response | |||
is identified for update. | is identified for update. | |||
skipping to change at page 23, line 20 ¶ | skipping to change at line 1016 ¶ | |||
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). | |||
4.4. Invalidating Stored Responses | 4.4. Invalidating Stored Responses | |||
Because unsafe request methods (Section 9.2.1 of [HTTP]) such as PUT, | Because unsafe request methods (Section 9.2.1 of [HTTP]) such as PUT, | |||
POST or DELETE have the potential for changing state on the origin | POST, or DELETE have the potential for changing state on the origin | |||
server, intervening caches are required to invalidate stored | server, intervening caches are required to invalidate stored | |||
responses to keep their contents up to date. | responses to keep their contents up to date. | |||
A cache MUST invalidate the target URI (Section 7.1 of [HTTP]) when | A cache MUST invalidate the target URI (Section 7.1 of [HTTP]) when | |||
it receives a non-error status code in response to an unsafe request | it receives a non-error status code in response to an unsafe request | |||
method (including methods whose safety is unknown). | method (including methods whose safety is unknown). | |||
A cache MAY invalidate other URIs when it receives a non-error status | A cache MAY invalidate other URIs when it receives a non-error status | |||
code in response to an unsafe request method (including methods whose | code in response to an unsafe request method (including methods whose | |||
safety is unknown). In particular, the URI(s) in the Location and | safety is unknown). In particular, the URI(s) in the Location and | |||
Content-Location response header fields (if present) are candidates | Content-Location response header fields (if present) are candidates | |||
for invalidation; other URIs might be discovered through mechanisms | for invalidation; other URIs might be discovered through mechanisms | |||
not specified in this document. However, a cache MUST NOT trigger an | not specified in this document. However, a cache MUST NOT trigger an | |||
invalidation under these conditions if the origin (Section 4.3.1 of | invalidation under these conditions if the origin (Section 4.3.1 of | |||
[HTTP]) of the URI to be invalidated differs from that of the target | [HTTP]) of the URI to be invalidated differs from that of the target | |||
URI (Section 7.1 of [HTTP]). This helps prevent denial-of-service | URI (Section 7.1 of [HTTP]). This helps prevent denial-of-service | |||
attacks. | attacks. | |||
_Invalidate_ means that the cache will either remove all stored | "Invalidate" means that the cache will either remove all stored | |||
responses whose target URI matches the given URI, or will mark them | responses whose target URI matches the given URI or mark them as | |||
as "invalid" and in need of a mandatory validation before they can be | "invalid" and in need of a mandatory validation before they can be | |||
sent in response to a subsequent request. | sent in response to a subsequent request. | |||
A "non-error response" is one with a 2xx (Successful) or 3xx | A "non-error response" is one with a 2xx (Successful) or 3xx | |||
(Redirection) status code. | (Redirection) status code. | |||
Note that this does not guarantee that all appropriate responses are | Note that this does not guarantee that all appropriate responses are | |||
invalidated globally; a state-changing request would only invalidate | invalidated globally; a state-changing request would only invalidate | |||
responses in the caches it travels through. | responses in the caches it travels through. | |||
5. Field Definitions | 5. Field Definitions | |||
skipping to change at page 24, line 38 ¶ | skipping to change at line 1080 ¶ | |||
negative integer), a cache SHOULD ignore the field. | negative integer), a cache SHOULD ignore the field. | |||
The presence of an Age header field implies that the response was not | The presence of an Age header field implies that the response was not | |||
generated or validated by the origin server for this request. | generated or validated by the origin server for this request. | |||
However, lack of an Age header field does not imply the origin was | However, lack of an Age header field does not imply the origin was | |||
contacted. | contacted. | |||
5.2. Cache-Control | 5.2. Cache-Control | |||
The "Cache-Control" header field is used to list directives for | The "Cache-Control" header field is used to list directives for | |||
caches along the request/response chain. Such cache directives are | caches along the request/response chain. Cache directives are | |||
unidirectional in that the presence of a directive in a request does | unidirectional, in that the presence of a directive in a request does | |||
not imply that the same directive is present in the response, or to | not imply that the same directive is present or copied in the | |||
be repeated in it. | response. | |||
See Section 5.2.3 for information about how Cache-Control directives | See Section 5.2.3 for information about how Cache-Control directives | |||
defined elsewhere are handled. | defined elsewhere are handled. | |||
A proxy, whether or not it implements a cache, MUST pass cache | A proxy, whether or not it implements a cache, MUST pass cache | |||
directives through in forwarded messages, regardless of their | directives through in forwarded messages, regardless of their | |||
significance to that application, since the directives might apply to | significance to that application, since the directives might apply to | |||
all recipients along the request/response chain. It is not possible | all recipients along the request/response chain. It is not possible | |||
to target a directive to a specific cache. | to target a directive to a specific cache. | |||
skipping to change at page 25, line 18 ¶ | skipping to change at line 1107 ¶ | |||
define arguments, recipients ought to accept both forms, even if a | define arguments, recipients ought to accept both forms, even if a | |||
specific form is required for generation. | specific form is required for generation. | |||
Cache-Control = #cache-directive | Cache-Control = #cache-directive | |||
cache-directive = token [ "=" ( token / quoted-string ) ] | cache-directive = token [ "=" ( token / quoted-string ) ] | |||
For the cache directives defined below, no argument is defined (nor | For the cache directives defined below, no argument is defined (nor | |||
allowed) unless stated otherwise. | allowed) unless stated otherwise. | |||
5.2.1. Request Cache-Control Directives | 5.2.1. Request Directives | |||
This section defines cache request directives. They are advisory; | This section defines cache request directives. They are advisory; | |||
caches MAY implement them, but are not required to. | caches MAY implement them, but are not required to. | |||
5.2.1.1. max-age | 5.2.1.1. max-age | |||
Argument syntax: | Argument syntax: | |||
delta-seconds (see Section 1.2.2) | delta-seconds (see Section 1.2.2) | |||
The "max-age" request directive indicates that the client prefers a | The max-age request directive indicates that the client prefers a | |||
response whose age is less than or equal to the specified number of | response whose age is less than or equal to the specified number of | |||
seconds. Unless the max-stale request directive is also present, the | seconds. Unless the max-stale request directive is also present, the | |||
client does not wish to receive a stale response. | client does not wish to receive a stale response. | |||
This directive uses the token form of the argument syntax: e.g., | This directive uses the token form of the argument syntax: e.g., | |||
'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the | 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the | |||
quoted-string form. | quoted-string form. | |||
5.2.1.2. max-stale | 5.2.1.2. max-stale | |||
Argument syntax: | Argument syntax: | |||
delta-seconds (see Section 1.2.2) | delta-seconds (see Section 1.2.2) | |||
The "max-stale" request directive indicates that the client will | The max-stale request directive indicates that the client will accept | |||
accept a response that has exceeded its freshness lifetime. If a | a response that has exceeded its freshness lifetime. If a value is | |||
value is present, then the client is willing to accept a response | present, then the client is willing to accept a response that has | |||
that has exceeded its freshness lifetime by no more than the | exceeded its freshness lifetime by no more than the specified number | |||
specified number of seconds. If no value is assigned to max-stale, | of seconds. If no value is assigned to max-stale, then the client | |||
then the client will accept a stale response of any age. | will accept a stale response of any age. | |||
This directive uses the token form of the argument syntax: e.g., | This directive uses the token form of the argument syntax: e.g., | |||
'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the | 'max-stale=10' not 'max-stale="10"'. A sender MUST NOT generate the | |||
quoted-string form. | quoted-string form. | |||
5.2.1.3. min-fresh | 5.2.1.3. min-fresh | |||
Argument syntax: | Argument syntax: | |||
delta-seconds (see Section 1.2.2) | delta-seconds (see Section 1.2.2) | |||
The "min-fresh" request directive indicates that the client prefers a | The min-fresh request directive indicates that the client prefers a | |||
response whose freshness lifetime is no less than its current age | response whose freshness lifetime is no less than its current age | |||
plus the specified time in seconds. That is, the client wants a | plus the specified time in seconds. That is, the client wants a | |||
response that will still be fresh for at least the specified number | response that will still be fresh for at least the specified number | |||
of seconds. | of seconds. | |||
This directive uses the token form of the argument syntax: e.g., | This directive uses the token form of the argument syntax: e.g., | |||
'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the | 'min-fresh=20' not 'min-fresh="20"'. A sender MUST NOT generate the | |||
quoted-string form. | quoted-string form. | |||
5.2.1.4. no-cache | 5.2.1.4. no-cache | |||
The "no-cache" request directive indicates that the client prefers | The no-cache request directive indicates that the client prefers a | |||
stored response not be used to satisfy the request without successful | stored response not be used to satisfy the request without successful | |||
validation on the origin server. | validation on the origin server. | |||
5.2.1.5. no-store | 5.2.1.5. no-store | |||
The "no-store" request directive indicates that a cache MUST NOT | The no-store request directive indicates that a cache MUST NOT store | |||
store any part of either this request or any response to it. This | any part of either this request or any response to it. This | |||
directive applies to both private and shared caches. "MUST NOT | directive applies to both private and shared caches. "MUST NOT | |||
store" in this context means that the cache MUST NOT intentionally | store" in this context means that the cache MUST NOT intentionally | |||
store the information in non-volatile storage, and MUST make a best- | store the information in non-volatile storage and MUST make a best- | |||
effort attempt to remove the information from volatile storage as | effort attempt to remove the information from volatile storage as | |||
promptly as possible after forwarding it. | promptly as possible after forwarding it. | |||
This directive is _not_ a reliable or sufficient mechanism for | This directive is not a reliable or sufficient mechanism for ensuring | |||
ensuring privacy. In particular, malicious or compromised caches | privacy. In particular, malicious or compromised caches might not | |||
might not recognize or obey this directive, and communications | recognize or obey this directive, and communications networks might | |||
networks might be vulnerable to eavesdropping. | be vulnerable to eavesdropping. | |||
Note that if a request containing this directive is satisfied from a | Note that if a request containing this directive is satisfied from a | |||
cache, the no-store request directive does not apply to the already | cache, the no-store request directive does not apply to the already | |||
stored response. | stored response. | |||
5.2.1.6. no-transform | 5.2.1.6. no-transform | |||
The "no-transform" request directive indicates that the client is | The no-transform request directive indicates that the client is | |||
asking for intermediaries to avoid transforming the content, as | asking for intermediaries to avoid transforming the content, as | |||
defined in Section 7.7 of [HTTP]. | defined in Section 7.7 of [HTTP]. | |||
5.2.1.7. only-if-cached | 5.2.1.7. only-if-cached | |||
The "only-if-cached" request directive indicates that the client only | The only-if-cached request directive indicates that the client only | |||
wishes to obtain a stored response. Caches that honor this request | wishes to obtain a stored response. Caches that honor this request | |||
directive SHOULD, upon receiving it, either respond using a stored | directive SHOULD, upon receiving it, respond with either a stored | |||
response consistent with the other constraints of the request, or | response consistent with the other constraints of the request or a | |||
respond with a 504 (Gateway Timeout) status code. | 504 (Gateway Timeout) status code. | |||
5.2.2. Response Cache-Control Directives | 5.2.2. Response Directives | |||
This section defines cache response directives. A cache MUST obey | This section defines cache response directives. A cache MUST obey | |||
the Cache-Control directives defined in this section. | the Cache-Control directives defined in this section. | |||
5.2.2.1. max-age | 5.2.2.1. max-age | |||
Argument syntax: | Argument syntax: | |||
delta-seconds (see Section 1.2.2) | delta-seconds (see Section 1.2.2) | |||
The "max-age" response directive indicates that the response is to be | The max-age response directive indicates that the response is to be | |||
considered stale after its age is greater than the specified number | considered stale after its age is greater than the specified number | |||
of seconds. | of seconds. | |||
This directive uses the token form of the argument syntax: e.g., | This directive uses the token form of the argument syntax: e.g., | |||
'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the | 'max-age=5' not 'max-age="5"'. A sender MUST NOT generate the | |||
quoted-string form. | quoted-string form. | |||
5.2.2.2. must-revalidate | 5.2.2.2. must-revalidate | |||
The "must-revalidate" response directive indicates that once the | The must-revalidate response directive indicates that once the | |||
response has become stale, a cache MUST NOT reuse that response to | response has become stale, a cache MUST NOT reuse that response to | |||
satisfy another request until it has been successfully validated by | satisfy another request until it has been successfully validated by | |||
the origin, as defined by Section 4.3. | the origin, as defined by Section 4.3. | |||
The must-revalidate directive is necessary to support reliable | The must-revalidate directive is necessary to support reliable | |||
operation for certain protocol features. In all circumstances a | operation for certain protocol features. In all circumstances, a | |||
cache MUST NOT ignore the must-revalidate directive; in particular, | cache MUST NOT ignore the must-revalidate directive; in particular, | |||
if a cache is disconnected, the cache MUST generate an error response | if a cache is disconnected, the cache MUST generate an error response | |||
rather than reuse the stale response. The generated status code | rather than reuse the stale response. The generated status code | |||
SHOULD be 504 (Gateway Timeout) unless another error status code is | SHOULD be 504 (Gateway Timeout) unless another error status code is | |||
more applicable. | more applicable. | |||
The must-revalidate directive ought to be used by servers if and only | The must-revalidate directive ought to be used by servers if and only | |||
if failure to validate a request could cause incorrect operation, | if failure to validate a request could cause incorrect operation, | |||
such as a silently unexecuted financial transaction. | such as a silently unexecuted financial transaction. | |||
The must-revalidate directive also permits a shared cache to reuse a | The must-revalidate directive also permits a shared cache to reuse a | |||
response to a request containing an Authorization header field | response to a request containing an Authorization header field | |||
(Section 11.6.2 of [HTTP]), subject to the above requirement on | (Section 11.6.2 of [HTTP]), subject to the above requirement on | |||
revalidation (Section 3.5). | revalidation (Section 3.5). | |||
5.2.2.3. must-understand | 5.2.2.3. must-understand | |||
The "must-understand" response directive limits caching of the | The must-understand response directive limits caching of the response | |||
response to a cache that understands and conforms to the requirements | to a cache that understands and conforms to the requirements for that | |||
for that response's status code. | response's status code. | |||
Responses containing "must-understand" SHOULD also contain the "no- | A response that contains the must-understand directive SHOULD also | |||
store" directive; caches that implement "must-understand" SHOULD | contain the no-store directive. When a cache that implements the | |||
ignore the "no-store" directive in responses that contain both | must-understand directive receives a response that includes it, the | |||
directives and a status code that the cache understands and conforms | cache SHOULD ignore the no-store directive if it understands and | |||
to any related caching requirements. | implements the status code's caching requirements. | |||
5.2.2.4. no-cache | 5.2.2.4. no-cache | |||
Argument syntax: | Argument syntax: | |||
#field-name | #field-name | |||
The "no-cache" response directive, in its unqualified form (without | The no-cache response directive, in its unqualified form (without an | |||
an argument), indicates that the response MUST NOT be used to satisfy | argument), indicates that the response MUST NOT be used to satisfy | |||
any other request without forwarding it for validation and receiving | any other request without forwarding it for validation and receiving | |||
a successful response; see Section 4.3. | a successful response; see Section 4.3. | |||
This allows an origin server to prevent a cache from using the | This allows an origin server to prevent a cache from using the | |||
response to satisfy a request without contacting it, even by caches | response to satisfy a request without contacting it, even by caches | |||
that have been configured to send stale responses. | that have been configured to send stale responses. | |||
The qualified form of no-cache response directive, with an argument | The qualified form of the no-cache response directive, with an | |||
that lists one or more field names, indicates that a cache MAY use | argument that lists one or more field names, indicates that a cache | |||
the response to satisfy a subsequent request, subject to any other | MAY use the response to satisfy a subsequent request, subject to any | |||
restrictions on caching, if the listed header fields are excluded | other restrictions on caching, if the listed header fields are | |||
from the subsequent response or the subsequent response has been | excluded from the subsequent response or the subsequent response has | |||
successfully revalidated with the origin server (updating or removing | been successfully revalidated with the origin server (updating or | |||
those fields). This allows an origin server to prevent the re-use of | removing those fields). This allows an origin server to prevent the | |||
certain header fields in a response, while still allowing caching of | reuse of certain header fields in a response, while still allowing | |||
the rest of the response. | caching of the rest of the response. | |||
The field names given are not limited to the set of header fields | The field names given are not limited to the set of header fields | |||
defined by this specification. Field names are case-insensitive. | defined by this specification. Field names are case-insensitive. | |||
This directive uses the quoted-string form of the argument syntax. A | This directive uses the quoted-string form of the argument syntax. A | |||
sender SHOULD NOT generate the token form (even if quoting appears | sender SHOULD NOT generate the token form (even if quoting appears | |||
not to be needed for single-entry lists). | not to be needed for single-entry lists). | |||
| *Note:* The qualified form of the directive is often handled by | | *Note:* The qualified form of the directive is often handled by | |||
| caches as if an unqualified no-cache directive was received; | | caches as if an unqualified no-cache directive was received; | |||
| i.e., the special handling for the qualified form is not widely | | that is, the special handling for the qualified form is not | |||
| implemented. | | widely implemented. | |||
5.2.2.5. no-store | 5.2.2.5. no-store | |||
The "no-store" response directive indicates that a cache MUST NOT | The no-store response directive indicates that a cache MUST NOT store | |||
store any part of either the immediate request or response, and MUST | any part of either the immediate request or the response and MUST NOT | |||
NOT use the response to satisfy any other request. | use the response to satisfy any other request. | |||
This directive applies to both private and shared caches. "MUST NOT | This directive applies to both private and shared caches. "MUST NOT | |||
store" in this context means that the cache MUST NOT intentionally | store" in this context means that the cache MUST NOT intentionally | |||
store the information in non-volatile storage, and MUST make a best- | store the information in non-volatile storage and MUST make a best- | |||
effort attempt to remove the information from volatile storage as | effort attempt to remove the information from volatile storage as | |||
promptly as possible after forwarding it. | promptly as possible after forwarding it. | |||
This directive is _not_ a reliable or sufficient mechanism for | This directive is not a reliable or sufficient mechanism for ensuring | |||
ensuring privacy. In particular, malicious or compromised caches | privacy. In particular, malicious or compromised caches might not | |||
might not recognize or obey this directive, and communications | recognize or obey this directive, and communications networks might | |||
networks might be vulnerable to eavesdropping. | be vulnerable to eavesdropping. | |||
Note that the "must-understand" cache directive overrides "no-store" | Note that the must-understand cache directive overrides no-store in | |||
in certain circumstances; see Section 5.2.2.3. | certain circumstances; see Section 5.2.2.3. | |||
5.2.2.6. no-transform | 5.2.2.6. no-transform | |||
The "no-transform" response directive indicates that an intermediary | The no-transform response directive indicates that an intermediary | |||
(regardless of whether it implements a cache) MUST NOT transform the | (regardless of whether it implements a cache) MUST NOT transform the | |||
content, as defined in Section 7.7 of [HTTP]. | content, as defined in Section 7.7 of [HTTP]. | |||
5.2.2.7. private | 5.2.2.7. private | |||
Argument syntax: | Argument syntax: | |||
#field-name | #field-name | |||
The unqualified "private" response directive indicates that a shared | The unqualified private response directive indicates that a shared | |||
cache MUST NOT store the response (i.e., the response is intended for | cache MUST NOT store the response (i.e., the response is intended for | |||
a single user). It also indicates that a private cache MAY store the | a single user). It also indicates that a private cache MAY store the | |||
response, subject the constraints defined in Section 3, even if the | response, subject to the constraints defined in Section 3, even if | |||
response would not otherwise be heuristically cacheable by a private | the response would not otherwise be heuristically cacheable by a | |||
cache. | private cache. | |||
If a qualified private response directive is present, with an | If a qualified private response directive is present, with an | |||
argument that lists one or more field names, then only the listed | argument that lists one or more field names, then only the listed | |||
header fields are limited to a single user: a shared cache MUST NOT | header fields are limited to a single user: a shared cache MUST NOT | |||
store the listed header fields if they are present in the original | store the listed header fields if they are present in the original | |||
response, but MAY store the remainder of the response message without | response but MAY store the remainder of the response message without | |||
those header fields, subject the constraints defined in Section 3. | those header fields, subject the constraints defined in Section 3. | |||
The field names given are not limited to the set of header fields | The field names given are not limited to the set of header fields | |||
defined by this specification. Field names are case-insensitive. | defined by this specification. Field names are case-insensitive. | |||
This directive uses the quoted-string form of the argument syntax. A | This directive uses the quoted-string form of the argument syntax. A | |||
sender SHOULD NOT generate the token form (even if quoting appears | sender SHOULD NOT generate the token form (even if quoting appears | |||
not to be needed for single-entry lists). | not to be needed for single-entry lists). | |||
| *Note:* This usage of the word "private" only controls where | | *Note:* This usage of the word "private" only controls where | |||
| the response can be stored; it cannot ensure the privacy of the | | the response can be stored; it cannot ensure the privacy of the | |||
| message content. Also, the qualified form of the directive is | | message content. Also, the qualified form of the directive is | |||
| often handled by caches as if an unqualified private directive | | often handled by caches as if an unqualified private directive | |||
| was received; i.e., the special handling for the qualified form | | was received; that is, the special handling for the qualified | |||
| is not widely implemented. | | form is not widely implemented. | |||
5.2.2.8. proxy-revalidate | 5.2.2.8. proxy-revalidate | |||
The "proxy-revalidate" response directive indicates that once the | The proxy-revalidate response directive indicates that once the | |||
response has become stale, a shared cache MUST NOT reuse that | response has become stale, a shared cache MUST NOT reuse that | |||
response to satisfy another request until it has been successfully | response to satisfy another request until it has been successfully | |||
validated by the origin, as defined by Section 4.3. This is | validated by the origin, as defined by Section 4.3. This is | |||
analogous to must-revalidate (Section 5.2.2.2), except that proxy- | analogous to must-revalidate (Section 5.2.2.2), except that proxy- | |||
revalidate does not apply to private caches. | revalidate does not apply to private caches. | |||
Note that "proxy-revalidate" on its own does not imply that a | Note that proxy-revalidate on its own does not imply that a response | |||
response is cacheable. For example, it might be combined with the | is cacheable. For example, it might be combined with the public | |||
public directive (Section 5.2.2.9), allowing the response to be | directive (Section 5.2.2.9), allowing the response to be cached while | |||
cached while requiring only a shared cache to revalidate when stale. | requiring only a shared cache to revalidate when stale. | |||
5.2.2.9. public | 5.2.2.9. public | |||
The "public" response directive indicates that a cache MAY store the | The public response directive indicates that a cache MAY store the | |||
response even if it would otherwise be prohibited, subject to the | response even if it would otherwise be prohibited, subject to the | |||
constraints defined in Section 3. In other words, public explicitly | constraints defined in Section 3. In other words, public explicitly | |||
marks the response as cacheable. For example, public permits a | marks the response as cacheable. For example, public permits a | |||
shared cache to reuse a response to a request containing an | shared cache to reuse a response to a request containing an | |||
Authorization header field (Section 3.5). | Authorization header field (Section 3.5). | |||
Note that it is unnecessary to add the public directive to a response | Note that it is unnecessary to add the public directive to a response | |||
that is already cacheable according to Section 3. | that is already cacheable according to Section 3. | |||
If a response with the public directive has no explicit freshness | If a response with the public directive has no explicit freshness | |||
information, it is heuristically cacheable (Section 4.2.2). | information, it is heuristically cacheable (Section 4.2.2). | |||
5.2.2.10. s-maxage | 5.2.2.10. s-maxage | |||
Argument syntax: | Argument syntax: | |||
delta-seconds (see Section 1.2.2) | delta-seconds (see Section 1.2.2) | |||
The "s-maxage" response directive indicates that, for a shared cache, | The s-maxage response directive indicates that, for a shared cache, | |||
the maximum age specified by this directive overrides the maximum age | the maximum age specified by this directive overrides the maximum age | |||
specified by either the max-age directive or the Expires header | specified by either the max-age directive or the Expires header | |||
field. | field. | |||
The s-maxage directive incorporates the proxy-revalidate | The s-maxage directive incorporates the semantics of the | |||
(Section 5.2.2.8) response directive's semantics for a shared cache. | proxy-revalidate response directive (Section 5.2.2.8) for a shared | |||
A shared cache MUST NOT reuse a stale response with s-maxage to | cache. A shared cache MUST NOT reuse a stale response with s-maxage | |||
satisfy another request until it has been successfully validated by | to satisfy another request until it has been successfully validated | |||
the origin, as defined by Section 4.3. This directive also permits a | by the origin, as defined by Section 4.3. This directive also | |||
shared cache to reuse a response to a request containing an | permits a shared cache to reuse a response to a request containing an | |||
Authorization header field, subject to the above requirements on | Authorization header field, subject to the above requirements on | |||
maximum age and revalidation (Section 3.5). | maximum age and revalidation (Section 3.5). | |||
This directive uses the token form of the argument syntax: e.g., | This directive uses the token form of the argument syntax: e.g., | |||
's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the | 's-maxage=10' not 's-maxage="10"'. A sender MUST NOT generate the | |||
quoted-string form. | quoted-string form. | |||
5.2.3. Cache Control Extensions | 5.2.3. Extension Directives | |||
The Cache-Control header field can be extended through the use of one | The Cache-Control header field can be extended through the use of one | |||
or more extension cache directives. A cache MUST ignore unrecognized | or more extension cache directives. A cache MUST ignore unrecognized | |||
cache directives. | cache directives. | |||
Informational extensions (those that do not require a change in cache | Informational extensions (those that do not require a change in cache | |||
behavior) can be added without changing the semantics of other | behavior) can be added without changing the semantics of other | |||
directives. | directives. | |||
Behavioral extensions are designed to work by acting as modifiers to | Behavioral extensions are designed to work by acting as modifiers to | |||
the existing base of cache directives. Both the new directive and | the existing base of cache directives. Both the new directive and | |||
the old directive are supplied, such that applications that do not | the old directive are supplied, such that applications that do not | |||
understand the new directive will default to the behavior specified | understand the new directive will default to the behavior specified | |||
by the old directive, and those that understand the new directive | by the old directive, and those that understand the new directive | |||
will recognize it as modifying the requirements associated with the | will recognize it as modifying the requirements associated with the | |||
old directive. In this way, extensions to the existing cache-control | old directive. In this way, extensions to the existing cache | |||
directives can be made without breaking deployed caches. | directives can be made without breaking deployed caches. | |||
For example, consider a hypothetical new response directive called | For example, consider a hypothetical new response directive called | |||
"community" that acts as a modifier to the private directive: in | "community" that acts as a modifier to the private directive: in | |||
addition to private caches, any cache that is shared only by members | addition to private caches, only a cache that is shared by members of | |||
of the named community is allowed to cache the response. An origin | the named community is allowed to cache the response. An origin | |||
server wishing to allow the UCI community to use an otherwise private | server wishing to allow the UCI community to use an otherwise private | |||
response in their shared cache(s) could do so by including | response in their shared cache(s) could do so by including | |||
Cache-Control: private, community="UCI" | Cache-Control: private, community="UCI" | |||
A cache that recognizes such a community cache directive could | A cache that recognizes such a community cache directive could | |||
broaden its behavior in accordance with that extension. A cache that | broaden its behavior in accordance with that extension. A cache that | |||
does not recognize the community cache directive would ignore it and | does not recognize the community cache directive would ignore it and | |||
adhere to the private directive. | adhere to the private directive. | |||
New extension directives ought to consider defining: | New extension directives ought to consider defining: | |||
* What it means for a directive to be specified multiple times, | * What it means for a directive to be specified multiple times, | |||
* When the directive does not take an argument, what it means when | * When the directive does not take an argument, what it means when | |||
an argument is present, | an argument is present, | |||
* When the directive requires an argument, what it means when it is | * When the directive requires an argument, what it means when it is | |||
missing, | missing, and | |||
* Whether the directive is specific to requests, responses, or able | * Whether the directive is specific to requests, specific to | |||
to be used in either. | responses, or able to be used in either. | |||
5.2.4. Cache Directive Registry | 5.2.4. Cache Directive Registry | |||
The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" | The "Hypertext Transfer Protocol (HTTP) Cache Directive Registry" | |||
defines the namespace for the cache directives. It has been created | defines the namespace for the cache directives. It has been created | |||
and is now maintained at <https://www.iana.org/assignments/http- | and is now maintained at <https://www.iana.org/assignments/http- | |||
cache-directives>. | cache-directives>. | |||
A registration MUST include the following fields: | A registration MUST include the following fields: | |||
skipping to change at page 34, line 43 ¶ | skipping to change at line 1557 ¶ | |||
cached data in other ways beyond its freshness lifetime. | cached data in other ways beyond its freshness lifetime. | |||
This specification does not prohibit the application from taking HTTP | This specification does not prohibit the application from taking HTTP | |||
caching into account; for example, a history mechanism might tell the | caching into account; for example, a history mechanism might tell the | |||
user that a view is stale, or it might honor cache directives (e.g., | user that a view is stale, or it might honor cache directives (e.g., | |||
Cache-Control: no-store). | Cache-Control: no-store). | |||
However, when an application caches data and does not make this | However, when an application caches data and does not make this | |||
apparent to or easily controllable by the user, it is strongly | apparent to or easily controllable by the user, it is strongly | |||
encouraged to define its operation with respect to HTTP cache | encouraged to define its operation with respect to HTTP cache | |||
directives, so as not to surprise authors who expect caching | directives so as not to surprise authors who expect caching semantics | |||
semantics to be honoured. For example, while it might be reasonable | to be honored. For example, while it might be reasonable to define | |||
to define an application cache "above" HTTP that allows a response | an application cache "above" HTTP that allows a response containing | |||
containing Cache-Control: no-store to be reused for requests that are | Cache-Control: no-store to be reused for requests that are directly | |||
directly related to the request that fetched it (such as those | related to the request that fetched it (such as those created during | |||
created during the same page load), it would likely be surprising and | the same page load), it would likely be surprising and confusing to | |||
confusing to users and authors if it were allowed to be reused for | users and authors if it were allowed to be reused for requests | |||
requests unrelated in any way to the one from which it was obtained. | unrelated in any way to the one from which it was obtained. | |||
7. Security Considerations | 7. Security Considerations | |||
This section is meant to inform developers, information providers, | This section is meant to inform developers, information providers, | |||
and users of known security concerns specific to HTTP caching. More | and users of known security concerns specific to HTTP caching. More | |||
general security considerations are addressed in "HTTP/1.1" | general security considerations are addressed in "HTTP/1.1" | |||
(Section 11 of [HTTP/1.1]) and "HTTP Semantics" (Section 17 of | (Section 11 of [HTTP/1.1]) and "HTTP Semantics" (Section 17 of | |||
[HTTP]). | [HTTP]). | |||
Caches expose an additional attack surface, since the contents of the | Caches expose an additional attack surface because the contents of | |||
cache represent an attractive target for malicious exploitation. | the cache represent an attractive target for malicious exploitation. | |||
Because cache contents persist after an HTTP request is complete, an | Since 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, it 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, by allowing stored responses to be removed for | |||
or all origin servers. | some 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 malicious content 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 | |||
distribute malicious content to many clients. | distribute malicious content to many clients. | |||
One common attack vector for cache poisoning is to exploit | One common attack vector for cache poisoning is to exploit | |||
differences in message parsing on proxies and in user agents; see | differences in message parsing on proxies and in user agents; see | |||
Section 6.3 of [HTTP/1.1] for the relevant requirements regarding | Section 6.3 of [HTTP/1.1] for the relevant requirements regarding | |||
HTTP/1.1. | HTTP/1.1. | |||
7.2. Timing Attacks | 7.2. Timing Attacks | |||
Because one of the primary uses of a cache is to optimise | Because one of the primary uses of a cache is to optimize | |||
performance, its use can "leak" information about what resources have | performance, its use can "leak" information about which resources | |||
been previously requested. | have been previously requested. | |||
For example, if a user visits a site and their browser caches some of | For example, if a user visits a site and their browser caches some of | |||
its responses, and then navigates to a second site, that site can | its responses and then navigates to a second site, that site can | |||
attempt to load responses it knows exists on the first site. If they | attempt to load responses it knows exist on the first site. If they | |||
load quickly, it can be assumed that the user has visited that site, | load quickly, it can be assumed that the user has visited that site, | |||
or even a specific page on it. | or even a specific page on it. | |||
Such "timing attacks" can be mitigated by adding more information to | Such "timing attacks" can be mitigated by adding more information to | |||
the cache key, such as the identity of the referring site (to prevent | the cache key, such as the identity of the referring site (to prevent | |||
the attack described above). This is sometimes called "double | the attack described above). This is sometimes called "double | |||
keying." | keying". | |||
7.3. Caching of Sensitive Information | 7.3. Caching of Sensitive Information | |||
Implementation and deployment flaws (as well as misunderstanding of | Implementation and deployment flaws (often led to by the | |||
cache operation) might lead to caching of sensitive information | misunderstanding of cache operation) might lead to the caching of | |||
(e.g., authentication credentials) that is thought to be private, | sensitive information (e.g., authentication credentials) that is | |||
exposing it to unauthorized parties. | thought to be private, exposing it to unauthorized parties. | |||
Note that the Set-Cookie response header field [COOKIE] does not | Note that the Set-Cookie response header field [COOKIE] does not | |||
inhibit caching; a cacheable response with a Set-Cookie header field | inhibit caching; a cacheable response with a Set-Cookie header field | |||
can be (and often is) used to satisfy subsequent requests to caches. | can be (and often is) used to satisfy subsequent requests to caches. | |||
Servers who wish to control caching of these responses are encouraged | Servers that wish to control caching of these responses are | |||
to emit appropriate Cache-Control response header fields. | encouraged to emit appropriate Cache-Control response header fields. | |||
8. IANA Considerations | 8. IANA Considerations | |||
The change controller for the following registrations is: "IETF | The change controller for the following registrations is: "IETF | |||
(iesg@ietf.org) - Internet Engineering Task Force". | (iesg@ietf.org) - Internet Engineering Task Force". | |||
8.1. Field Name Registration | 8.1. Field Name Registration | |||
First, introduce the new "Hypertext Transfer Protocol (HTTP) Field | IANA has updated the "Hypertext Transfer Protocol (HTTP) Field Name | |||
Name Registry" at <https://www.iana.org/assignments/http-fields> as | Registry" at <https://www.iana.org/assignments/http-fields>, as | |||
described in Section 18.4 of [HTTP]. | described in Section 18.4 of [HTTP], with the field names listed in | |||
the table below: | ||||
Then, please update the registry with the field names listed in the | ||||
table below: | ||||
+===============+===========+======+==========+ | +===============+============+=========+==========+ | |||
| Field Name | Status | Ref. | Comments | | | Field Name | Status | Section | Comments | | |||
+===============+===========+======+==========+ | +===============+============+=========+==========+ | |||
| Age | standard | 5.1 | | | | Age | permanent | 5.1 | | | |||
+---------------+-----------+------+----------+ | +---------------+------------+---------+----------+ | |||
| Cache-Control | standard | 5.2 | | | | Cache-Control | permanent | 5.2 | | | |||
+---------------+-----------+------+----------+ | +---------------+------------+---------+----------+ | |||
| Expires | standard | 5.3 | | | | Expires | permanent | 5.3 | | | |||
+---------------+-----------+------+----------+ | +---------------+------------+---------+----------+ | |||
| Pragma | standard | 5.4 | | | | Pragma | deprecated | 5.4 | | | |||
+---------------+-----------+------+----------+ | +---------------+------------+---------+----------+ | |||
| Warning | obsoleted | 5.5 | | | | Warning | obsoleted | 5.5 | | | |||
+---------------+-----------+------+----------+ | +---------------+------------+---------+----------+ | |||
Table 1 | Table 1 | |||
8.2. Cache Directive Registration | 8.2. Cache Directive Registration | |||
Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive | IANA has updated the "Hypertext Transfer Protocol (HTTP) Cache | |||
Registry" at <https://www.iana.org/assignments/http-cache-directives> | Directive Registry" at <https://www.iana.org/assignments/http-cache- | |||
with the registration procedure of Section 5.2.4 and the cache | directives> with the registration procedure per Section 5.2.4 and the | |||
directive names summarized in the table below. | cache directive names summarized in the table below. | |||
+==================+==================================+ | +==================+==================+ | |||
| Cache Directive | Reference | | | Cache Directive | Section | | |||
+==================+==================================+ | +==================+==================+ | |||
| max-age | Section 5.2.1.1, Section 5.2.2.1 | | | max-age | 5.2.1.1, 5.2.2.1 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| max-stale | Section 5.2.1.2 | | | max-stale | 5.2.1.2 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| min-fresh | Section 5.2.1.3 | | | min-fresh | 5.2.1.3 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| must-revalidate | Section 5.2.2.2 | | | must-revalidate | 5.2.2.2 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| must-understand | Section 5.2.2.3 | | | must-understand | 5.2.2.3 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| no-cache | Section 5.2.1.4, Section 5.2.2.4 | | | no-cache | 5.2.1.4, 5.2.2.4 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| no-store | Section 5.2.1.5, Section 5.2.2.5 | | | no-store | 5.2.1.5, 5.2.2.5 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| no-transform | Section 5.2.1.6, Section 5.2.2.6 | | | no-transform | 5.2.1.6, 5.2.2.6 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| only-if-cached | Section 5.2.1.7 | | | only-if-cached | 5.2.1.7 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| private | Section 5.2.2.7 | | | private | 5.2.2.7 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| proxy-revalidate | Section 5.2.2.8 | | | proxy-revalidate | 5.2.2.8 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| public | Section 5.2.2.9 | | | public | 5.2.2.9 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
| s-maxage | Section 5.2.2.10 | | | s-maxage | 5.2.2.10 | | |||
+------------------+----------------------------------+ | +------------------+------------------+ | |||
Table 2 | Table 2 | |||
8.3. Warn Code Registry | 8.3. Warn Code Registry | |||
Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn | IANA has added the following note to the "Hypertext Transfer Protocol | |||
Codes" registry at <https://www.iana.org/assignments/http-warn-codes> | (HTTP) Warn Codes" registry at <https://www.iana.org/assignments/ | |||
to the effect that Warning is obsoleted. | http-warn-codes> stating that "Warning" has been obsoleted: | |||
| The Warning header field (and the warn codes that it uses) has | ||||
| been obsoleted for HTTP per [RFC9111]. | ||||
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", STD 97, RFC 9110, | |||
draft-ietf-httpbis-semantics-19, 10 September 2021, | DOI 10.17487/RFC9110, June 2022, | |||
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis- | <https://www.rfc-editor.org/info/rfc9110>. | |||
semantics-19>. | ||||
[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 36 ¶ | skipping to change at line 1741 ¶ | |||
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, | [HTTP/1.1] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "HTTP/1.1", Work in Progress, Internet-Draft, draft- | Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, | |||
ietf-httpbis-messaging-19, 10 September 2021, | June 2022, <https://www.rfc-editor.org/info/rfc9112>. | |||
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis- | ||||
messaging-19>. | ||||
[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, May 2010, | |||
<https://www.rfc-editor.org/info/rfc5861>. | <https://www.rfc-editor.org/info/rfc5861>. | |||
[RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke, | [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "Hypertext Transfer Protocol (HTTP): Caching", | Ed., "Hypertext Transfer Protocol (HTTP/1.1): 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>. | |||
Appendix A. Collected ABNF | Appendix A. Collected ABNF | |||
In the collected ABNF below, list rules are expanded as per | In the collected ABNF below, list rules are expanded per | |||
Section 5.6.1 of [HTTP]. | Section 5.6.1 of [HTTP]. | |||
Age = delta-seconds | Age = delta-seconds | |||
Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] | Cache-Control = [ cache-directive *( OWS "," OWS cache-directive ) ] | |||
Expires = HTTP-date | Expires = HTTP-date | |||
HTTP-date = <HTTP-date, see [HTTP], Section 5.6.7> | HTTP-date = <HTTP-date, see [HTTP], Section 5.6.7> | |||
skipping to change at page 39, line 46 ¶ | skipping to change at line 1795 ¶ | |||
quoted-string = <quoted-string, see [HTTP], Section 5.6.4> | quoted-string = <quoted-string, see [HTTP], Section 5.6.4> | |||
token = <token, see [HTTP], Section 5.6.2> | token = <token, see [HTTP], Section 5.6.2> | |||
Appendix B. Changes from RFC 7234 | Appendix B. Changes from RFC 7234 | |||
Handling of duplicate and conflicting cache directives has been | Handling of duplicate and conflicting cache directives has been | |||
clarified. (Section 4.2.1) | clarified. (Section 4.2.1) | |||
Cache invalidation of the URIs in the Location and Content-Location | Cache invalidation of the URIs in the Location and Content-Location | |||
header fields is no longer required, but still allowed. | header fields is no longer required but is still allowed. | |||
(Section 4.4) | (Section 4.4) | |||
Cache invalidation of the URIs in the Location and Content-Location | Cache invalidation of the URIs in the Location and Content-Location | |||
header fields is disallowed when the origin is different; previously, | header fields is disallowed when the origin is different; previously, | |||
it was the host. (Section 4.4) | it was the host. (Section 4.4) | |||
Handling invalid and multiple Age header field values has been | Handling invalid and multiple Age header field values has been | |||
clarified. (Section 5.1) | clarified. (Section 5.1) | |||
Some cache directives defined by this specification now have stronger | Some cache directives defined by this specification now have stronger | |||
prohibitions against generating the quoted form of their values, | prohibitions against generating the quoted form of their values, | |||
since this has been found to create interoperability problems. | since this has been found to create interoperability problems. | |||
Consumers of extension cache directives are no longer required to | Consumers of extension cache directives are no longer required to | |||
accept both token and quoted-string forms, but they still need to | accept both token and quoted-string forms, but they still need to | |||
parse them properly for unknown extensions. (Section 5.2) | parse them properly for unknown extensions. (Section 5.2) | |||
The "public" and "private" cache directives were clarified, so that | The public and private cache directives were clarified, so that they | |||
they do not make responses reusable under any condition. | do not make responses reusable under any condition. (Section 5.2.2) | |||
(Section 5.2.2) | ||||
The "must-understand" cache directive was introduced; caches are no | The must-understand cache directive was introduced; caches are no | |||
longer required to understand the semantics of new response status | longer required to understand the semantics of new response status | |||
codes unless it is present. (Section 5.2.2.3) | codes unless it is present. (Section 5.2.2.3) | |||
The Warning response header was obsoleted. Much of the information | The Warning response header was obsoleted. Much of the information | |||
supported by Warning could be gleaned by examining the response, and | supported by Warning could be gleaned by examining the response, and | |||
the remaining warn-codes - although potentially useful - were | the remaining information -- although potentially useful -- was | |||
entirely advisory. In practice, Warning was not added by caches or | entirely advisory. In practice, Warning was not added by caches or | |||
intermediaries. (Section 5.5) | intermediaries. (Section 5.5) | |||
Appendix C. Change Log | ||||
This section is to be removed before publishing as an RFC. | ||||
C.1. Between RFC7234 and draft 00 | ||||
The changes were purely editorial: | ||||
* Change boilerplate and abstract to indicate the "draft" status, | ||||
and update references to ancestor specifications. | ||||
* Remove version "1.1" from document title, indicating that this | ||||
specification applies to all HTTP versions. | ||||
* Adjust historical notes. | ||||
* Update links to sibling specifications. | ||||
* Replace sections listing changes from RFC 2616 by new empty | ||||
sections referring to RFC 723x. | ||||
* Remove acknowledgements specific to RFC 723x. | ||||
* Move "Acknowledgements" to the very end and make them unnumbered. | ||||
C.2. Since draft-ietf-httpbis-cache-00 | ||||
The changes are purely editorial: | ||||
* Moved all extensibility tips, registration procedures, and | ||||
registry tables from the IANA considerations to normative | ||||
sections, reducing the IANA considerations to just instructions | ||||
that will be removed prior to publication as an RFC. | ||||
C.3. Since draft-ietf-httpbis-cache-01 | ||||
* Cite RFC 8126 instead of RFC 5226 (<https://github.com/httpwg/ | ||||
http-core/issues/75>) | ||||
* In Section 5.4, misleading statement about the relation between | ||||
Pragma and Cache-Control (<https://github.com/httpwg/http-core/ | ||||
issues/92>, <https://www.rfc-editor.org/errata/eid4674>) | ||||
C.4. Since draft-ietf-httpbis-cache-02 | ||||
* In Section 3, explain that only final responses are cacheable | ||||
(<https://github.com/httpwg/http-core/issues/29>) | ||||
* In Section 5.2.2, clarify what responses various directives apply | ||||
to (<https://github.com/httpwg/http-core/issues/52>) | ||||
* In Section 4.3.1, clarify the source of validators in conditional | ||||
requests (<https://github.com/httpwg/http-core/issues/110>) | ||||
* Revise Section 6 to apply to more than just History Lists | ||||
(<https://github.com/httpwg/http-core/issues/126>) | ||||
* In Section 5.5, deprecated "Warning" header field | ||||
(<https://github.com/httpwg/http-core/issues/139>) | ||||
* In Section 3.5, remove a spurious note | ||||
(<https://github.com/httpwg/http-core/issues/141>) | ||||
C.5. Since draft-ietf-httpbis-cache-03 | ||||
* In Section 2, define what a disconnected cache is | ||||
(<https://github.com/httpwg/http-core/issues/5>) | ||||
* In Section 4, clarify language around how to select a response | ||||
when more than one matches (<https://github.com/httpwg/http-core/ | ||||
issues/23>) | ||||
* in Section 4.2.4, mention stale-while-revalidate and stale-if- | ||||
error (<https://github.com/httpwg/http-core/issues/122>) | ||||
* Remove requirements around cache request directives | ||||
(<https://github.com/httpwg/http-core/issues/129>) | ||||
* Deprecate Pragma (<https://github.com/httpwg/http-core/ | ||||
issues/140>) | ||||
* In Section 3.5 and Section 5.2.2, note effect of some directives | ||||
on authenticated requests (<https://github.com/httpwg/http-core/ | ||||
issues/161>) | ||||
C.6. Since draft-ietf-httpbis-cache-04 | ||||
* In Section 5.2, remove the registrations for stale-if-error and | ||||
stale-while-revalidate which happened in RFC 7234 | ||||
(<https://github.com/httpwg/http-core/issues/207>) | ||||
C.7. Since draft-ietf-httpbis-cache-05 | ||||
* In Section 3.3, clarify how weakly framed content is considered | ||||
for purposes of completeness (<https://github.com/httpwg/http- | ||||
core/issues/25>) | ||||
* Throughout, describe Vary and cache key operations more clearly | ||||
(<https://github.com/httpwg/http-core/issues/28>) | ||||
* In Section 3, remove concept of "cacheable methods" in favor of | ||||
prose (<https://github.com/httpwg/http-core/issues/54>, | ||||
<https://www.rfc-editor.org/errata/eid5300>) | ||||
* Refactored Section 7, and added a section on timing attacks | ||||
(<https://github.com/httpwg/http-core/issues/233>) | ||||
* Changed "cacheable by default" to "heuristically cacheable" | ||||
throughout (<https://github.com/httpwg/http-core/issues/242>) | ||||
C.8. Since draft-ietf-httpbis-cache-06 | ||||
* In Section 3 and Section 5.2.2.3, change response cacheability to | ||||
only require understanding the response status code if the must- | ||||
understand cache directive is present (<https://github.com/httpwg/ | ||||
http-core/issues/120>) | ||||
* Change requirements for handling different forms of cache | ||||
directives in Section 5.2 (<https://github.com/httpwg/http-core/ | ||||
issues/128>) | ||||
* Fix typo in Section 5.2.2.10 (<https://github.com/httpwg/http- | ||||
core/issues/264>) | ||||
* In Section 5.2.2.9 and Section 5.2.2.7, clarify "private" and | ||||
"public" so that they do not override all other cache directives | ||||
(<https://github.com/httpwg/http-core/issues/268>) | ||||
* In Section 3, distinguish between private with and without | ||||
qualifying headers (<https://github.com/httpwg/http-core/ | ||||
issues/270>) | ||||
* In Section 4.1, clarify that any "*" as a member of Vary will | ||||
disable caching (<https://github.com/httpwg/http-core/issues/286>) | ||||
* In Section 1.1, reference RFC 8174 as well | ||||
(<https://github.com/httpwg/http-core/issues/303>) | ||||
C.9. Since draft-ietf-httpbis-cache-07 | ||||
* Throughout, replace "effective request URI", "request-target" and | ||||
similar with "target URI" (<https://github.com/httpwg/http-core/ | ||||
issues/259>) | ||||
* In Section 5.2.2.9 and Section 5.2.2.7, make it clear that these | ||||
directives do not ignore other requirements for caching | ||||
(<https://github.com/httpwg/http-core/issues/320>) | ||||
* In Section 3.3, move definition of "complete" into semantics | ||||
(<https://github.com/httpwg/http-core/issues/334>) | ||||
C.10. Since draft-ietf-httpbis-cache-08 | ||||
* Appendix A now uses the sender variant of the "#" list expansion | ||||
(<https://github.com/httpwg/http-core/issues/192>) | ||||
C.11. Since draft-ietf-httpbis-cache-09 | ||||
* In Section 5.1, discuss handling of invalid and multiple Age | ||||
header field values (<https://github.com/httpwg/http-core/ | ||||
issues/193>) | ||||
* Switch to xml2rfc v3 mode for draft generation | ||||
(<https://github.com/httpwg/http-core/issues/394>) | ||||
C.12. Since draft-ietf-httpbis-cache-10 | ||||
* In Section 5.2 (Cache-Control), adjust ABNF to allow empty lists | ||||
(<https://github.com/httpwg/http-core/issues/210>) | ||||
C.13. Since draft-ietf-httpbis-cache-11 | ||||
* None. | ||||
C.14. Since draft-ietf-httpbis-cache-12 | ||||
* In Section 4.2.4, remove 'no-store', as it won't be in cache in | ||||
the first place (<https://github.com/httpwg/http-core/issues/447>, | ||||
<https://www.rfc-editor.org/errata/eid6279>) | ||||
* In Section 3.1, make it clear that only response headers need be | ||||
stored (<https://github.com/httpwg/http-core/issues/457>) | ||||
* Rewrote "Updating Stored Header Fields" Section 3.2 | ||||
(<https://github.com/httpwg/http-core/issues/458>) | ||||
* In Section 4.2.1 clarify how to handle invalid and conflicting | ||||
directives (<https://github.com/httpwg/http-core/issues/460>) | ||||
* In Section 4.3.3, mention retry of failed validation requests | ||||
(<https://github.com/httpwg/http-core/issues/462>) | ||||
* In Section 4.3.3, clarify requirement on storing a full response | ||||
to a conditional request (<https://github.com/httpwg/http-core/ | ||||
issues/463>) | ||||
* In Section 5.1, clarify error handling | ||||
(<https://github.com/httpwg/http-core/issues/471>) | ||||
* In Section 4.2, remove spurious "UTC" (<https://github.com/httpwg/ | ||||
http-core/issues/472>) | ||||
* In Section 4.2, correct the date-related rule names to consider | ||||
case-insensitive (<https://github.com/httpwg/http-core/ | ||||
issues/473>) | ||||
* In Section 6, strengthen recommendation for application caches to | ||||
pay attention to cache directives (<https://github.com/httpwg/ | ||||
http-core/issues/474>) | ||||
* In Section 4, mention collapsed requests | ||||
(<https://github.com/httpwg/http-core/issues/475>) | ||||
* In Section 4.4, relax requirements on Content-Location and | ||||
Location invalidation (<https://github.com/httpwg/http-core/ | ||||
issues/478>) | ||||
* In Section 4.3.4, refine the exceptions to update on a 304 | ||||
(<https://github.com/httpwg/http-core/issues/488>) | ||||
* Moved table of Cache-Control directives into Section 8.2 | ||||
(<https://github.com/httpwg/http-core/issues/506>) | ||||
* In Section 1.2, remove unused core ABNF rules | ||||
(<https://github.com/httpwg/http-core/issues/529>) | ||||
* Changed to using "payload data" when defining requirements about | ||||
the data being conveyed within a message, instead of the terms | ||||
"payload body" or "response body" or "representation body", since | ||||
they often get confused with the HTTP/1.1 message body (which | ||||
includes transfer coding) (<https://github.com/httpwg/http-core/ | ||||
issues/553>) | ||||
C.15. Since draft-ietf-httpbis-cache-13 | ||||
* In Section 5.2.2.2, clarify requirements around generating an | ||||
error response (<https://github.com/httpwg/http-core/issues/608>) | ||||
* Changed to using "content" instead of "payload" or "payload data" | ||||
to avoid confusion with the payload of version-specific messaging | ||||
frames (<https://github.com/httpwg/http-core/issues/654>) | ||||
* In Section 4.3.4, clarify how multiple validators are handled | ||||
(<https://github.com/httpwg/http-core/issues/659>) | ||||
* In Section 4.2.3, Section 5.2, and Section 5.2.2.4, remove notes | ||||
about very old HTTP/1.0 behaviours (<https://github.com/httpwg/ | ||||
http-core/issues/660>) | ||||
* In Section 5.2.2.3, modify operation to be more backwards- | ||||
compatible with existing implementations | ||||
(<https://github.com/httpwg/http-core/issues/661>) | ||||
C.16. Since draft-ietf-httpbis-cache-14 | ||||
* Fix subsection ordering in Section 5.2.2 | ||||
(<https://github.com/httpwg/http-core/issues/674>) | ||||
* In Section 2, define what a cache key is | ||||
(<https://github.com/httpwg/http-core/issues/728>) | ||||
* In Section 3.1, clarify what cache proxy headers apply to | ||||
(<https://github.com/httpwg/http-core/issues/729>) | ||||
* In Section 7.1, cache poisoning can affect private caches too | ||||
(<https://github.com/httpwg/http-core/issues/730>) | ||||
* In Section 5.1, adjust handling of invalid values to match most | ||||
deployed caches (<https://github.com/httpwg/http-core/issues/778>) | ||||
* In Section 5.3, mention parsing requirement relaxation | ||||
(<https://github.com/httpwg/http-core/issues/779>) | ||||
C.17. Since draft-ietf-httpbis-cache-15 | ||||
* In Section 4.3.1, tune description of relation between cache keys | ||||
and validators (<https://github.com/httpwg/http-core/issues/832>) | ||||
C.18. Since draft-ietf-httpbis-cache-16 | ||||
This draft addresses mostly editorial issues raised during or past | ||||
IETF Last Call; see <https://github.com/httpwg/http-core/ | ||||
issues?q=label%3Acaching+created%3A%3E2021-05-26> for a summary. | ||||
Furthermore: | ||||
* Addressed Genart last call review comments | ||||
(<https://github.com/httpwg/http-core/issues/847>) | ||||
* In Section 4.3.4, clarify that only selectable responses are | ||||
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>) | ||||
C.20. Since draft-ietf-httpbis-cache-18 | ||||
* None. | ||||
Acknowledgements | Acknowledgements | |||
See Appendix "Acknowledgements" of [HTTP]. | See Appendix "Acknowledgements" of [HTTP], which applies to this | |||
document as well. | ||||
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 | |||
Age header field Section 5.1 | ||||
age Section 4.2 | age Section 4.2 | |||
Age header field *_Section 5.1_* | ||||
C | C | |||
Cache-Control header field Section 5.2 | ||||
cache Section 1 | cache Section 1 | |||
cache key Section 2; Section 2 | cache key Section 2; Section 2 | |||
Cache-Control header field *_Section 5.2_* | ||||
collapsed requests Section 4 | collapsed requests Section 4 | |||
E | E | |||
Expires header field Section 5.3 | Expires header field *_Section 5.3_* | |||
explicit expiration time Section 4.2 | explicit expiration time Section 4.2 | |||
F | F | |||
Fields | Fields | |||
Age Section 5.1; Section 5.1 | Age *_Section 5.1_*; *_Section 5.1_* | |||
Cache-Control Section 5.2 | Cache-Control *_Section 5.2_* | |||
Expires Section 5.3; Section 5.3 | Expires *_Section 5.3_*; *_Section 5.3_* | |||
Pragma Section 5.4; Section 5.4 | Pragma *_Section 5.4_*; *_Section 5.4_* | |||
Warning Section 5.5 | Warning *_Section 5.5_* | |||
fresh Section 4.2 | fresh Section 4.2 | |||
freshness lifetime Section 4.2 | freshness lifetime Section 4.2 | |||
G | G | |||
Grammar | Grammar | |||
Age Section 5.1 | Age *_Section 5.1_* | |||
Cache-Control Section 5.2 | Cache-Control *_Section 5.2_* | |||
DIGIT Section 1.2 | DIGIT *_Section 1.2_* | |||
Expires Section 5.3 | Expires *_Section 5.3_* | |||
cache-directive Section 5.2 | cache-directive *_Section 5.2_* | |||
delta-seconds Section 1.2.2 | delta-seconds *_Section 1.2.2_* | |||
H | H | |||
Header Fields | Header Fields | |||
Age Section 5.1; Section 5.1 | Age *_Section 5.1_*; *_Section 5.1_* | |||
Cache-Control Section 5.2 | Cache-Control *_Section 5.2_* | |||
Expires Section 5.3; Section 5.3 | Expires *_Section 5.3_*; *_Section 5.3_* | |||
Pragma Section 5.4; Section 5.4 | Pragma *_Section 5.4_*; *_Section 5.4_* | |||
Warning Section 5.5 | Warning *_Section 5.5_* | |||
heuristic expiration time Section 4.2 | heuristic expiration time Section 4.2 | |||
heuristically cacheable Section 4.2.2 | heuristically cacheable Section 4.2.2 | |||
M | M | |||
max-age (cache directive) Section 5.2.1.1; Section 5.2.2.1 | max-age (cache directive) *_Section 5.2.1.1_*; | |||
max-stale (cache directive) Section 5.2.1.2 | *_Section 5.2.2.1_* | |||
min-fresh (cache directive) Section 5.2.1.3 | max-stale (cache directive) *_Section 5.2.1.2_* | |||
must-revalidate (cache directive) Section 5.2.2.2 | min-fresh (cache directive) *_Section 5.2.1.3_* | |||
must-understand (cache directive) Section 5.2.2.3 | must-revalidate (cache directive) *_Section 5.2.2.2_* | |||
must-understand (cache directive) *_Section 5.2.2.3_* | ||||
N | N | |||
no-cache (cache directive) Section 5.2.1.4; Section 5.2.2.4 | no-cache (cache directive) *_Section 5.2.1.4_*; | |||
no-store (cache directive) Section 5.2.1.5; Section 5.2.2.5 | *_Section 5.2.2.4_* | |||
no-transform (cache directive) Section 5.2.1.6; | no-store (cache directive) *_Section 5.2.1.5_*; | |||
Section 5.2.2.6 | *_Section 5.2.2.5_* | |||
no-transform (cache directive) *_Section 5.2.1.6_*; | ||||
*_Section 5.2.2.6_* | ||||
O | O | |||
only-if-cached (cache directive) Section 5.2.1.7 | only-if-cached (cache directive) *_Section 5.2.1.7_* | |||
P | P | |||
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_* | |||
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_* | |||
Authors' Addresses | Authors' Addresses | |||
Roy T. Fielding (editor) | Roy T. Fielding (editor) | |||
Adobe | Adobe | |||
345 Park Ave | 345 Park Ave | |||
San Jose, CA 95110 | San Jose, CA 95110 | |||
United States of America | United States of America | |||
Email: fielding@gbiv.com | Email: fielding@gbiv.com | |||
URI: https://roy.gbiv.com/ | URI: https://roy.gbiv.com/ | |||
Mark Nottingham (editor) | Mark Nottingham (editor) | |||
Fastly | Fastly | |||
Prahran VIC | Prahran | |||
Australia | Australia | |||
Email: mnot@mnot.net | Email: mnot@mnot.net | |||
URI: https://www.mnot.net/ | URI: https://www.mnot.net/ | |||
Julian Reschke (editor) | Julian Reschke (editor) | |||
greenbytes GmbH | greenbytes GmbH | |||
Hafenweg 16 | Hafenweg 16 | |||
48155 Münster | 48155 Münster | |||
Germany | Germany | |||
Email: julian.reschke@greenbytes.de | Email: julian.reschke@greenbytes.de | |||
URI: https://greenbytes.de/tech/webdav/ | URI: https://greenbytes.de/tech/webdav/ | |||
End of changes. 165 change blocks. | ||||
813 lines changed or deleted | 466 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/ |