draft-ietf-httpbis-p6-cache-10.txt | draft-ietf-httpbis-p6-cache-11.txt | |||
---|---|---|---|---|
HTTPbis Working Group R. Fielding, Ed. | HTTPbis Working Group R. Fielding, Ed. | |||
Internet-Draft Day Software | Internet-Draft Day Software | |||
Obsoletes: 2616 (if approved) J. Gettys | Obsoletes: 2616 (if approved) J. Gettys | |||
Intended status: Standards Track Alcatel-Lucent | Intended status: Standards Track Alcatel-Lucent | |||
Expires: January 13, 2011 J. Mogul | Expires: February 5, 2011 J. Mogul | |||
HP | HP | |||
H. Frystyk | H. Frystyk | |||
Microsoft | Microsoft | |||
L. Masinter | L. Masinter | |||
Adobe Systems | Adobe Systems | |||
P. Leach | P. Leach | |||
Microsoft | Microsoft | |||
T. Berners-Lee | T. Berners-Lee | |||
W3C/MIT | W3C/MIT | |||
Y. Lafon, Ed. | Y. Lafon, Ed. | |||
W3C | W3C | |||
M. Nottingham, Ed. | M. Nottingham, Ed. | |||
J. Reschke, Ed. | J. Reschke, Ed. | |||
greenbytes | greenbytes | |||
July 12, 2010 | August 4, 2010 | |||
HTTP/1.1, part 6: Caching | HTTP/1.1, part 6: Caching | |||
draft-ietf-httpbis-p6-cache-10 | draft-ietf-httpbis-p6-cache-11 | |||
Abstract | Abstract | |||
The Hypertext Transfer Protocol (HTTP) is an application-level | The Hypertext Transfer Protocol (HTTP) is an application-level | |||
protocol for distributed, collaborative, hypermedia information | protocol for distributed, collaborative, hypermedia information | |||
systems. This document is Part 6 of the seven-part specification | systems. This document is Part 6 of the seven-part specification | |||
that defines the protocol referred to as "HTTP/1.1" and, taken | that defines the protocol referred to as "HTTP/1.1" and, taken | |||
together, obsoletes RFC 2616. Part 6 defines requirements on HTTP | together, obsoletes RFC 2616. Part 6 defines requirements on HTTP | |||
caches and the associated header fields that control cache behavior | caches and the associated header fields that control cache behavior | |||
or indicate cacheable response messages. | or indicate cacheable response messages. | |||
Editorial Note (To be removed by RFC Editor) | Editorial Note (To be removed by RFC Editor) | |||
Discussion of this draft should take place on the HTTPBIS working | Discussion of this draft should take place on the HTTPBIS working | |||
group mailing list (ietf-http-wg@w3.org). The current issues list is | group mailing list (ietf-http-wg@w3.org). The current issues list is | |||
at <http://tools.ietf.org/wg/httpbis/trac/report/3> and related | at <http://tools.ietf.org/wg/httpbis/trac/report/3> and related | |||
documents (including fancy diffs) can be found at | documents (including fancy diffs) can be found at | |||
<http://tools.ietf.org/wg/httpbis/>. | <http://tools.ietf.org/wg/httpbis/>. | |||
The changes in this draft are summarized in Appendix C.11. | The changes in this draft are summarized in Appendix C.12. | |||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at http://datatracker.ietf.org/drafts/current/. | Drafts is at http://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on January 13, 2011. | This Internet-Draft will expire on February 5, 2011. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2010 IETF Trust and the persons identified as the | Copyright (c) 2010 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents | Provisions Relating to IETF Documents | |||
(http://trustee.ietf.org/license-info) in effect on the date of | (http://trustee.ietf.org/license-info) in effect on the date of | |||
publication of this document. Please review these documents | publication of this document. Please review these documents | |||
skipping to change at page 3, line 24 | skipping to change at page 3, line 24 | |||
2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 | 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 | |||
2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 | 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 | |||
2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 | 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 | |||
2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 | 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 | |||
2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 | 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 | |||
2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 | 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 | |||
2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 16 | 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 16 | |||
3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 | 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 | |||
3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 | 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 | |||
3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 | 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 | |||
3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 | 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 | |||
3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 | 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 | |||
3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 | 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 | 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 | 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 | |||
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 | |||
5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 | 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 28 | |||
5.2. Message Header Registration . . . . . . . . . . . . . . . 30 | 5.2. Header Field Registration . . . . . . . . . . . . . . . . 29 | |||
6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 | |||
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 | 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | |||
8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 | 8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 | |||
8.2. Informative References . . . . . . . . . . . . . . . . . . 31 | 8.2. Informative References . . . . . . . . . . . . . . . . . . 31 | |||
Appendix A. Compatibility with Previous Versions . . . . . . . . 32 | Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 31 | |||
A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 32 | Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 | |||
A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 32 | ||||
Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 | ||||
Appendix C. Change Log (to be removed by RFC Editor before | Appendix C. Change Log (to be removed by RFC Editor before | |||
publication) . . . . . . . . . . . . . . . . . . . . 34 | publication) . . . . . . . . . . . . . . . . . . . . 33 | |||
C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 34 | C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 | |||
C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 | C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 | |||
C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 | C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 | |||
C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 | C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 | |||
C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 | C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 | |||
C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 | C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 34 | |||
C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 | C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 | |||
C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 | C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 | |||
C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 | C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 35 | |||
C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 | C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 36 | |||
C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 | C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 36 | |||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 | C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 37 | |||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 | ||||
1. Introduction | 1. Introduction | |||
HTTP is typically used for distributed information systems, where | HTTP is typically used for distributed information systems, where | |||
performance can be improved by the use of response caches. This | performance can be improved by the use of response caches. This | |||
document defines aspects of HTTP/1.1 related to caching and reusing | document defines aspects of HTTP/1.1 related to caching and reusing | |||
response messages. | response messages. | |||
1.1. Purpose | 1.1. Purpose | |||
An HTTP cache is a local store of response messages and the subsystem | An HTTP cache is a local store of response messages and the subsystem | |||
that controls its message storage, retrieval, and deletion. A cache | that controls its message storage, retrieval, and deletion. A cache | |||
stores cacheable responses in order to reduce the response time and | stores cacheable responses in order to reduce the response time and | |||
network bandwidth consumption on future, equivalent requests. Any | network bandwidth consumption on future, equivalent requests. Any | |||
client or server may include a cache, though a cache cannot be used | client or server MAY employ a cache, though a cache cannot be used by | |||
by a server that is acting as a tunnel. | a server that is acting as a tunnel. | |||
Caching would be useless if it did not significantly improve | Caching would be useless if it did not significantly improve | |||
performance. The goal of caching in HTTP/1.1 is to reuse a prior | performance. The goal of caching in HTTP/1.1 is to reuse a prior | |||
response message to satisfy a current request. In some cases, a | response message to satisfy a current request. In some cases, a | |||
stored response can be reused without the need for a network request, | stored response can be reused without the need for a network request, | |||
reducing latency and network round-trips; a "freshness" mechanism is | reducing latency and network round-trips; a "freshness" mechanism is | |||
used for this purpose (see Section 2.3). Even when a new request is | used for this purpose (see Section 2.3). Even when a new request is | |||
required, it is often possible to reuse all or parts of the payload | required, it is often possible to reuse all or parts of the payload | |||
of a prior response to satisfy the request, thereby reducing network | of a prior response to satisfy the request, thereby reducing network | |||
bandwidth usage; a "validation" mechanism is used for this purpose | bandwidth usage; a "validation" mechanism is used for this purpose | |||
skipping to change at page 5, line 41 | skipping to change at page 5, line 41 | |||
1.2. Terminology | 1.2. Terminology | |||
This specification uses a number of terms to refer to the roles | This specification uses a number of terms to refer to the roles | |||
played by participants in, and objects of, HTTP caching. | played by participants in, and objects of, HTTP caching. | |||
cacheable | cacheable | |||
A response is cacheable if a cache is allowed to store a copy of | A response is cacheable if a cache is allowed to store a copy of | |||
the response message for use in answering subsequent requests. | the response message for use in answering subsequent requests. | |||
Even when a response is cacheable, there may be additional | Even when a response is cacheable, there might be additional | |||
constraints on whether a cache can use the cached copy to satisfy | constraints on whether a cache can use the cached copy to satisfy | |||
a particular request. | a particular request. | |||
explicit expiration time | explicit expiration time | |||
The time at which the origin server intends that an entity should | The time at which the origin server intends that a representation | |||
no longer be returned by a cache without further validation. | no longer be returned by a cache without further validation. | |||
heuristic expiration time | heuristic expiration time | |||
An expiration time assigned by a cache when no explicit expiration | An expiration time assigned by a cache when no explicit expiration | |||
time is available. | time is available. | |||
age | age | |||
The age of a response is the time since it was sent by, or | The age of a response is the time since it was sent by, or | |||
skipping to change at page 6, line 37 | skipping to change at page 6, line 37 | |||
A response is fresh if its age has not yet exceeded its freshness | A response is fresh if its age has not yet exceeded its freshness | |||
lifetime. | lifetime. | |||
stale | stale | |||
A response is stale if its age has passed its freshness lifetime | A response is stale if its age has passed its freshness lifetime | |||
(either explicit or heuristic). | (either explicit or heuristic). | |||
validator | validator | |||
A protocol element (e.g., an entity tag or a Last-Modified time) | A protocol element (e.g., an entity-tag or a Last-Modified time) | |||
that is used to find out whether a stored response is an | that is used to find out whether a stored response has an | |||
equivalent copy of an entity. | equivalent copy of a representation. | |||
shared cache | shared cache | |||
A cache that is accessible to more than one user. A non-shared | A cache that is accessible to more than one user. A non-shared | |||
cache is dedicated to a single user. | cache is dedicated to a single user. | |||
1.3. Requirements | 1.3. Requirements | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | |||
skipping to change at page 9, line 14 | skipping to change at page 9, line 14 | |||
status code. | status code. | |||
A cache that does not support the Range and Content-Range headers | A cache that does not support the Range and Content-Range headers | |||
MUST NOT store incomplete or partial responses. | MUST NOT store incomplete or partial responses. | |||
2.2. Constructing Responses from Caches | 2.2. Constructing Responses from Caches | |||
For a presented request, a cache MUST NOT return a stored response, | For a presented request, a cache MUST NOT return a stored response, | |||
unless: | unless: | |||
o The presented Effective Request URI (Section 4.3 of [Part1]) and | o The presented effective request URI (Section 4.3 of [Part1]) and | |||
that of the stored response match, and | that of the stored response match, and | |||
o the request method associated with the stored response allows it | o 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 | |||
o selecting request-headers nominated by the stored response (if | o selecting request-headers nominated by the stored response (if | |||
any) match those presented (see Section 2.7), and | any) match those presented (see Section 2.7), and | |||
o the presented request and stored response are free from directives | o the presented request and stored response are free from directives | |||
that would prevent its use (see Section 3.2 and Section 3.4), and | that would prevent its use (see Section 3.2 and Section 3.4), and | |||
o the stored response is either: | o the stored response is either: | |||
* fresh (see Section 2.3), or | * fresh (see Section 2.3), or | |||
* allowed to be served stale (see Section 2.3.3), or | * allowed to be served stale (see Section 2.3.3), or | |||
* successfully validated (see Section 2.4). | * successfully validated (see Section 2.4). | |||
[[TODO-method-cacheability: define method cacheability for GET, HEAD | When a stored response is used to satisfy a request without | |||
and POST in p2-semantics.]] | validation, caches MUST include a single Age header field | |||
(Section 3.1) in the response with a value equal to the stored | ||||
When a stored response is used to satisfy a request, caches MUST | response's current_age; see Section 2.3.2. | |||
include a single Age header field (Section 3.1) in the response with | ||||
a value equal to the stored response's current_age; see | ||||
Section 2.3.2. [[DISCUSS-includes-validated: this currently includes | ||||
successfully validated responses.]] | ||||
Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST | Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST | |||
be written through the cache to the origin server; i.e., a cache must | be written through the cache to the origin server; i.e., a cache must | |||
not reply to such a request before having forwarded the request and | not reply to such a request before having forwarded the request and | |||
having received a corresponding response. | 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 2.5. | responses; see Section 2.5. | |||
Caches MUST use the most recent response (as determined by the Date | Caches MUST use the most recent response (as determined by the Date | |||
skipping to change at page 10, line 19 | skipping to change at page 10, line 16 | |||
When a response is "fresh" in the cache, it can be used to satisfy | When a response is "fresh" in the cache, it can be used to satisfy | |||
subsequent requests without contacting the origin server, thereby | subsequent requests without contacting the origin server, thereby | |||
improving efficiency. | improving 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 (Section 3.3) or the max-age response cache | either the Expires header (Section 3.3) or the max-age response cache | |||
directive (Section 3.2.2). Generally, origin servers will assign | directive (Section 3.2.2). Generally, origin servers will assign | |||
future explicit expiration times to responses in the belief that the | future explicit expiration times to responses in the belief that the | |||
entity is not likely to change in a semantically significant way | representation is not likely to change in a semantically significant | |||
before the expiration time is reached. | way before the expiration time is reached. | |||
If an origin server wishes to force a cache to validate every | If an origin server wishes to force a cache to validate every | |||
request, it can assign an explicit expiration time in the past. This | request, it can assign an explicit expiration time in the past to | |||
means that the response is always stale, so that caches should | indicate that the response is already stale. Compliant caches will | |||
validate it before using it for subsequent requests. [[TODO- | validate the cached response before reusing it for subsequent | |||
response-stale: This wording may cause confusion, because the | requests. | |||
response may still be served stale.]] | ||||
Since origin servers do not always provide explicit expiration times, | Since origin servers do not always provide explicit expiration times, | |||
HTTP caches may also assign heuristic expiration times when they are | HTTP caches MAY assign heuristic expiration times when explicit times | |||
not specified, employing algorithms that use other header values | are not specified, employing algorithms that use other header values | |||
(such as the Last-Modified time) to estimate a plausible expiration | (such as the Last-Modified time) to estimate a plausible expiration | |||
time. The HTTP/1.1 specification does not provide specific | time. The HTTP/1.1 specification does not provide specific | |||
algorithms, but does impose worst-case constraints on their results. | algorithms, but does impose worst-case constraints on their results. | |||
The calculation to determine if a response is fresh is: | The calculation to determine if a response is fresh is: | |||
response_is_fresh = (freshness_lifetime > current_age) | response_is_fresh = (freshness_lifetime > current_age) | |||
The freshness_lifetime is defined in Section 2.3.1; the current_age | The freshness_lifetime is defined in Section 2.3.1; the current_age | |||
is defined in Section 2.3.2. | is defined in Section 2.3.2. | |||
Additionally, clients may need to influence freshness calculation. | Additionally, clients might need to influence freshness calculation. | |||
They can do this using several request cache directives, with the | They can do this using several request cache directives, with the | |||
effect of either increasing or loosening constraints on freshness. | effect of either increasing or loosening constraints on freshness. | |||
See Section 3.2.1. | See Section 3.2.1. | |||
[[ISSUE-no-req-for-directives: there are not requirements directly | [[ISSUE-no-req-for-directives: there are not requirements directly | |||
applying to cache-request-directives and freshness.]] | applying to cache-request-directives and freshness.]] | |||
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 4 for an explanation of the difference between | resource. See Section 4 for an explanation of the difference between | |||
skipping to change at page 11, line 32 | skipping to change at page 11, line 29 | |||
o Otherwise, no explicit expiration time is present in the response. | o 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 2.3.1.1. | Section 2.3.1.1. | |||
Note that this calculation is not vulnerable to clock skew, since all | Note that this calculation is not vulnerable to clock skew, since all | |||
of the information comes from the origin server. | of the information comes from the origin server. | |||
2.3.1.1. Calculating Heuristic Freshness | 2.3.1.1. Calculating Heuristic Freshness | |||
If no explicit expiration time is present in a stored response that | If no explicit expiration time is present in a stored response that | |||
has a status code of 200, 203, 206, 300, 301 or 410, a heuristic | has a status code whose definition allows heuristic freshness to be | |||
expiration time can be calculated. Heuristics MUST NOT be used for | used (including the following in Section 8 of [Part2]: 200, 203, 206, | |||
other response status codes. | 300, 301 and 410), a heuristic expiration time MAY be calculated. | |||
Heuristics MUST NOT be used for response status codes that do not | ||||
explicitly allow it. | ||||
When a heuristic is used to calculate freshness lifetime, the cache | When a heuristic is used to calculate freshness lifetime, the cache | |||
SHOULD attach a Warning header with a 113 warn-code to the response | SHOULD attach a Warning header with a 113 warn-code to the response | |||
if its current_age is more than 24 hours and such a warning is not | if its current_age is more than 24 hours and such a warning is not | |||
already present. | already present. | |||
Also, if the response has a Last-Modified header (Section 6.6 of | Also, if the response has a Last-Modified header (Section 6.6 of | |||
[Part4]), the heuristic expiration value SHOULD be no more than some | [Part4]), the heuristic expiration value SHOULD be no more than some | |||
fraction of the interval since that time. A typical setting of this | fraction of the interval since that time. A typical setting of this | |||
fraction might be 10%. | fraction might be 10%. | |||
skipping to change at page 14, line 39 | skipping to change at page 14, line 39 | |||
requested URI, if present. However, if any of the stored responses | requested URI, if present. However, if any of the stored responses | |||
contains only partial content, its entity-tag SHOULD NOT be included | contains only partial content, its entity-tag SHOULD NOT be included | |||
in the If-None-Match header field unless the request is for a range | in the If-None-Match header field unless the request is for a range | |||
that would be fully satisfied by that stored response. | that would be fully satisfied by that stored response. | |||
A 304 (Not Modified) response status code indicates that the stored | A 304 (Not Modified) response status code indicates that the stored | |||
response can be updated and reused; see Section 2.8. | response can be updated and reused; see Section 2.8. | |||
A full response (i.e., one with a response body) indicates that none | A full response (i.e., one with a response body) indicates that none | |||
of the stored responses nominated in the conditional request is | of the stored responses nominated in the conditional request is | |||
suitable. Instead, the full response is used both to satisfy the | suitable. Instead, the full response SHOULD be used to satisfy the | |||
request and replace the stored response. [[TODO-req-missing: Should | request and MAY replace the stored response. | |||
there be a requirement here?]] | ||||
If a cache receives a 5xx response while attempting to validate a | If a cache receives a 5xx response while attempting to validate a | |||
response, it MAY either forward this response to the requesting | response, it MAY either forward this response to the requesting | |||
client, or act as if the server failed to respond. In the latter | client, or act as if the server failed to respond. In the latter | |||
case, it MAY return a previously stored response (see Section 2.3.3). | case, it MAY return a previously stored response (see Section 2.3.3). | |||
2.5. Request Methods that Invalidate | 2.5. Request Methods that Invalidate | |||
Because unsafe methods (Section 7.1.1 of [Part2]) have the potential | Because unsafe methods (Section 7.1.1 of [Part2]) have the potential | |||
for changing state on the origin server, intervening caches can use | for changing state on the origin server, intervening caches can use | |||
them to keep their contents up-to-date. | them to keep their contents up-to-date. | |||
The following HTTP methods MUST cause a cache to invalidate the | The following HTTP methods MUST cause a cache to invalidate the | |||
Effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) | effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) | |||
in the Location and Content-Location headers (if present): | in the Location and Content-Location headers (if present): | |||
o PUT | o PUT | |||
o DELETE | o DELETE | |||
o POST | o POST | |||
An invalidation based on a URI from a Location or Content-Location | An invalidation based on a URI from a Location or Content-Location | |||
header MUST NOT be performed if the host part of that URI differs | header MUST NOT be performed if the host part of that URI differs | |||
from the host part in the Effective Request URI (Section 4.3 of | from the host part in the effective request URI (Section 4.3 of | |||
[Part1]). This helps prevent denial of service attacks. | [Part1]). This helps prevent denial of service attacks. | |||
[[TODO-def-host-part: "host part" needs to be specified better.]] | ||||
A cache that passes through requests for methods it does not | A cache that passes through requests for methods it does not | |||
understand SHOULD invalidate the Effective Request URI (Section 4.3 | understand SHOULD invalidate the effective request URI (Section 4.3 | |||
of [Part1]). | of [Part1]). | |||
Here, "invalidate" means that the cache will either remove all stored | Here, "invalidate" means that the cache will either remove all stored | |||
responses related to the Effective Request URI, or will mark these as | responses related to the effective request URI, or will mark these 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 | |||
returned in response to a subsequent request. | returned in response to a subsequent request. | |||
Note that this does not guarantee that all appropriate responses are | Note that this does not guarantee that all appropriate responses are | |||
invalidated. For example, the request that caused the change at the | invalidated. For example, the request that caused the change at the | |||
origin server might not have gone through the cache where a response | origin server might not have gone through the cache where a response | |||
is stored. | is stored. | |||
[[TODO-spec-success-invalidate: specify that only successful (2xx, | ||||
3xx?) responses invalidate.]] | ||||
2.6. Shared Caching of Authenticated Responses | 2.6. Shared Caching of Authenticated Responses | |||
Shared caches MUST NOT use a cached response to a request with an | Shared caches MUST NOT use a cached response to a request with an | |||
Authorization header (Section 3.1 of [Part7]) to satisfy any | Authorization header (Section 3.1 of [Part7]) to satisfy any | |||
subsequent request unless a cache directive that allows such | subsequent request unless a cache directive that allows such | |||
responses to be stored is present in the response. | responses to be stored is present in the response. | |||
In this specification, the following Cache-Control response | In this specification, the following Cache-Control response | |||
directives (Section 3.2.2) have such an effect: must-revalidate, | directives (Section 3.2.2) have such an effect: must-revalidate, | |||
public, s-maxage. | public, s-maxage. | |||
skipping to change at page 16, line 32 | skipping to change at page 16, line 29 | |||
o combining multiple message-header fields with the same field name | o combining multiple message-header fields with the same field name | |||
(see Section 3.2 of [Part1]) | (see Section 3.2 of [Part1]) | |||
o normalizing both header values in a way that is known to have | o normalizing both header values in a way that is known to have | |||
identical semantics, according to the header's specification | identical semantics, according to the header's specification | |||
(e.g., re-ordering field values when order is not significant; | (e.g., re-ordering field values when order is not significant; | |||
case-normalization, where values are defined to be case- | case-normalization, where values are defined to be case- | |||
insensitive) | insensitive) | |||
If (after any normalisation that may take place) a header field is | If (after any normalization that might take place) a header field is | |||
absent from a request, it can only match another request if it is | absent from a request, it can only match another request if it is | |||
also absent there. | also absent there. | |||
A Vary header field-value of "*" always fails to match, and | A Vary header field-value of "*" always fails to match, and | |||
subsequent requests to that resource can only be properly interpreted | subsequent requests to that resource can only be properly interpreted | |||
by the origin server. | by the origin server. | |||
The stored response with matching selecting request-headers is known | The stored response with matching selecting request-headers is known | |||
as the selected response. | as the selected response. | |||
If no selected response is available, the cache MAY forward the | If no selected response is available, the cache MAY forward the | |||
presented request to the origin server in a conditional request; see | presented request to the origin server in a conditional request; see | |||
Section 2.4. | Section 2.4. | |||
2.8. Combining Responses | 2.8. Combining Responses | |||
When a cache receives a 304 (Not Modified) response or a 206 (Partial | When a cache receives a 304 (Not Modified) response or a 206 (Partial | |||
Content) response (in this section, the "new" response"), it needs to | Content) response (in this section, the "new" response"), it needs to | |||
created an updated response by combining the stored response with the | created an updated response by combining the stored response with the | |||
new one, so that the updated response can be used to satisfy the | new one, so that the updated response can be used to satisfy the | |||
request. | request, and potentially update the cached response. | |||
If the new response contains an ETag, it identifies the stored | If the new response contains an ETag, it identifies the stored | |||
response to use. [[TODO-mention-CL: may need language about Content- | response to use. [[TODO-mention-CL: might need language about | |||
Location here]][[TODO-inm-mult-etags: cover case where INM with | Content-Location here]][[TODO-select-for-combine: Shouldn't this be | |||
multiple etags was sent]] | the selected response?]] | |||
If the status code is 206 (partial content), both the stored and new | If the new response's status code is 206 (partial content), both the | |||
responses MUST have validators, and those validators MUST match using | stored and new responses MUST have validators, and those validators | |||
the strong comparison function (see Section 4 of [Part4]). | MUST match using the strong comparison function (see Section 4 of | |||
Otherwise, the responses MUST NOT be combined. | [Part4]). Otherwise, the responses MUST NOT be combined. | |||
The stored response headers are used as those of the updated | The stored response headers are used as those of the updated | |||
response, except that | response, except that | |||
o any stored Warning headers with warn-code 1xx (see Section 3.6) | o any stored Warning headers with warn-code 1xx (see Section 3.6) | |||
MUST be deleted from the stored response and the updated response. | MUST be deleted. | |||
o any stored Warning headers with warn-code 2xx MUST be retained in | ||||
the stored response and the updated response. | ||||
o any headers provided in the new response MUST replace the | ||||
corresponding headers from the stored response. | ||||
If a header field-name in the new response matches more than one | o any stored Warning headers with warn-code 2xx MUST be retained. | |||
header in the stored response, all such stored headers MUST be | ||||
replaced. | ||||
The updated response can [[TODO-is-req: requirement?]] be used to | o any other headers provided in the new response MUST replace all | |||
replace the stored response in cache. In the case of a 206 response, | instances of the corresponding headers from the stored response. | |||
the combined entity-body MAY be stored. | ||||
[[ISSUE-how-head: discuss how to handle HEAD updates]] | The updated response headers MUST be used to replace those of the | |||
stored response in cache (unless the stored response is removed from | ||||
cache). In the case of a 206 response, the combined representation | ||||
MAY be stored. | ||||
3. Header Field Definitions | 3. Header Field Definitions | |||
This section defines the syntax and semantics of HTTP/1.1 header | This section defines the syntax and semantics of HTTP/1.1 header | |||
fields related to caching. | fields related to caching. | |||
For entity-header fields, both sender and recipient refer to either | ||||
the client or the server, depending on who sends and who receives the | ||||
entity. | ||||
3.1. Age | 3.1. Age | |||
The "Age" response-header field conveys the sender's estimate of the | The "Age" response-header field conveys the sender's estimate of the | |||
amount of time since the response was generated or successfully | amount of time since the response was generated or successfully | |||
validated at the origin server. Age values are calculated as | validated at the origin server. Age values are calculated as | |||
specified in Section 2.3.2. | specified in Section 2.3.2. | |||
Age = "Age" ":" OWS Age-v | Age = "Age" ":" OWS Age-v | |||
Age-v = delta-seconds | Age-v = delta-seconds | |||
skipping to change at page 18, line 18 | skipping to change at page 18, line 4 | |||
Age-v = delta-seconds | Age-v = delta-seconds | |||
Age field-values are non-negative integers, representing time in | Age field-values are non-negative integers, representing time in | |||
seconds. | seconds. | |||
delta-seconds = 1*DIGIT | delta-seconds = 1*DIGIT | |||
If a cache receives a value larger than the largest positive integer | If a cache receives a value larger than the largest positive integer | |||
it can represent, or if any of its age calculations overflows, it | it can represent, or if any of its age calculations overflows, it | |||
MUST transmit an Age header with a field-value of 2147483648 (2^31). | MUST transmit an Age header with a field-value of 2147483648 (2^31). | |||
Caches SHOULD use an arithmetic type of at least 31 bits of range. | Caches SHOULD use an arithmetic type of at least 31 bits of range. | |||
The presence of an Age header field in a response implies that a | The presence of an Age header field in a response implies that a | |||
response is not first-hand. However, the converse is not true, since | response is not first-hand. However, the converse is not true, since | |||
HTTP/1.0 caches may not implement the Age header field. | HTTP/1.0 caches might not implement the Age header field. | |||
3.2. Cache-Control | 3.2. Cache-Control | |||
The "Cache-Control" general-header field is used to specify | The "Cache-Control" general-header field is used to specify | |||
directives for caches along the request/response chain. Such cache | directives for caches along the request/response chain. Such cache | |||
directives are unidirectional in that the presence of a directive in | directives are unidirectional in that the presence of a directive in | |||
a request does not imply that the same directive is to be given in | a request does not imply that the same directive is to be given in | |||
the response. | the response. | |||
HTTP/1.1 caches MUST obey the requirements of the Cache-Control | HTTP/1.1 caches MUST obey the requirements of the Cache-Control | |||
skipping to change at page 19, line 38 | skipping to change at page 19, line 24 | |||
store any part of either this request or any response to it. This | store any part of either this request or any response to it. This | |||
directive applies to both non-shared and shared caches. "MUST NOT | directive applies to both non-shared 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 | store the information in non-volatile storage, and MUST make a | |||
best-effort attempt to remove the information from volatile | best-effort attempt to remove the information from volatile | |||
storage as promptly as possible after forwarding it. | storage as 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 privacy. In particular, malicious or compromised caches | ensuring privacy. In particular, malicious or compromised caches | |||
might not recognize or obey this directive, and communications | might not recognize or obey this directive, and communications | |||
networks may be vulnerable to eavesdropping. | networks might be vulnerable to eavesdropping. | |||
max-age | max-age | |||
The max-age request directive indicates that the client is willing | The max-age request directive indicates that the client is willing | |||
to accept a response whose age is no greater than the specified | to accept a response whose age is no greater than the specified | |||
time in seconds. Unless the max-stale request directive is also | time in seconds. Unless the max-stale request directive is also | |||
present, the client is not willing to accept a stale response. | present, the client is not willing to accept a stale response. | |||
max-stale | max-stale | |||
The max-stale request directive indicates that the client is | The max-stale request directive indicates that the client is | |||
willing to accept a response that has exceeded its expiration | willing to accept a response that has exceeded its expiration | |||
time. If max-stale is assigned a value, then the client is | time. If max-stale is assigned a value, then the client is | |||
willing to accept a response that has exceeded its expiration time | willing to accept a response that has exceeded its expiration time | |||
by no more than the specified number of seconds. If no value is | by no more than the specified number of seconds. If no value is | |||
assigned to max-stale, then the client is willing to accept a | assigned to max-stale, then the client is willing to accept a | |||
stale response of any age. [[TODO-staleness: of any staleness? | stale response of any age. | |||
--mnot]] | ||||
min-fresh | min-fresh | |||
The min-fresh request directive indicates that the client is | The min-fresh request directive indicates that the client is | |||
willing to accept a response whose freshness lifetime is no less | willing to accept a response whose freshness lifetime is no less | |||
than its current age plus the specified time in seconds. That is, | than its current age plus the specified time in seconds. That is, | |||
the client wants a response that will still be fresh for at least | the client wants a response that will still be fresh for at least | |||
the specified number of seconds. | the specified number of seconds. | |||
no-transform | no-transform | |||
The no-transform request directive indicates that an intermediate | The no-transform request directive indicates that an intermediate | |||
cache or proxy MUST NOT change the Content-Encoding, Content-Range | cache or proxy MUST NOT change the Content-Encoding, Content-Range | |||
or Content-Type request headers, nor the request entity-body. | or Content-Type request headers, nor the request representation. | |||
only-if-cached | only-if-cached | |||
The only-if-cached request directive indicates that the client | The only-if-cached request directive indicates that the client | |||
only wishes to return a stored response. If it receives this | only wishes to return a stored response. If it receives this | |||
directive, a cache SHOULD either respond using a stored response | directive, a cache SHOULD either respond using a stored response | |||
that is consistent with the other constraints of the request, or | that is consistent with the other constraints of the request, or | |||
respond with a 504 (Gateway Timeout) status. If a group of caches | respond with a 504 (Gateway Timeout) status code. If a group of | |||
is being operated as a unified system with good internal | caches is being operated as a unified system with good internal | |||
connectivity, such a request MAY be forwarded within that group of | connectivity, such a request MAY be forwarded within that group of | |||
caches. | caches. | |||
3.2.2. Response Cache-Control Directives | 3.2.2. Response Cache-Control Directives | |||
cache-response-directive = | cache-response-directive = | |||
"public" | "public" | |||
/ "private" [ "=" DQUOTE 1#field-name DQUOTE ] | / "private" [ "=" DQUOTE 1#field-name DQUOTE ] | |||
/ "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] | / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] | |||
/ "no-store" | / "no-store" | |||
skipping to change at page 21, line 20 | skipping to change at page 21, line 7 | |||
is intended for a single user and MUST NOT be stored by a shared | is intended for a single user and MUST NOT be stored by a shared | |||
cache. A private (non-shared) cache MAY store the response. | cache. A private (non-shared) cache MAY store the response. | |||
If the private response directive specifies one or more field- | If the private response directive specifies one or more field- | |||
names, this requirement is limited to the field-values associated | names, this requirement is limited to the field-values associated | |||
with the listed response headers. That is, the specified field- | with the listed response headers. That is, the specified field- | |||
names(s) MUST NOT be stored by a shared cache, whereas the | names(s) MUST NOT be stored by a shared cache, whereas the | |||
remainder of the response message MAY be. | remainder of the response message MAY be. | |||
Note: This usage of the word private only controls where the | Note: This usage of the word private only controls where the | |||
response may be stored, and cannot ensure the privacy of the | response can be stored; it cannot ensure the privacy of the | |||
message content. Also, private response directives with field- | message content. Also, private response directives with field- | |||
names are often handled by implementations as if an unqualified | names are often handled by implementations as if an unqualified | |||
private directive was received; i.e., the special handling for the | private directive was received; i.e., the special handling for the | |||
qualified form is not widely implemented. | qualified form is not widely implemented. | |||
no-cache | no-cache | |||
The no-cache response directive indicates that the response MUST | The no-cache response directive indicates that the response MUST | |||
NOT be used to satisfy a subsequent request without successful | NOT be used to satisfy a subsequent request without successful | |||
validation on the origin server. This allows an origin server to | validation on the origin server. This allows an origin server to | |||
prevent caching even by caches that have been configured to return | prevent a cache from using it to satisfy a request without | |||
contacting it, even by caches that have been configured to return | ||||
stale responses. | stale responses. | |||
If the no-cache response directive specifies one or more field- | If the no-cache response directive specifies one or more field- | |||
names, this requirement is limited to the field-values associated | names, this requirement is limited to the field-values associated | |||
with the listed response headers. That is, the specified field- | with the listed response headers. That is, the specified field- | |||
name(s) MUST NOT be sent in the response to a subsequent request | name(s) MUST NOT be sent in the response to a subsequent request | |||
without successful validation on the origin server. This allows | without successful validation on the origin server. This allows | |||
an origin server to prevent the re-use of certain header fields in | an origin server to prevent the re-use of certain header fields in | |||
a response, while still allowing caching of the rest of the | a response, while still allowing caching of the rest of the | |||
response. | response. | |||
skipping to change at page 22, line 18 | skipping to change at page 21, line 50 | |||
store any part of either the immediate request or response. This | store any part of either the immediate request or response. This | |||
directive applies to both non-shared and shared caches. "MUST NOT | directive applies to both non-shared 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 | store the information in non-volatile storage, and MUST make a | |||
best-effort attempt to remove the information from volatile | best-effort attempt to remove the information from volatile | |||
storage as promptly as possible after forwarding it. | storage as 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 privacy. In particular, malicious or compromised caches | ensuring privacy. In particular, malicious or compromised caches | |||
might not recognize or obey this directive, and communications | might not recognize or obey this directive, and communications | |||
networks may be vulnerable to eavesdropping. | networks might be vulnerable to eavesdropping. | |||
must-revalidate | must-revalidate | |||
The must-revalidate response directive indicates that once it has | The must-revalidate response directive indicates that once it has | |||
become stale, the response MUST NOT be used to satisfy subsequent | become stale, the response MUST NOT be used to satisfy subsequent | |||
requests without successful validation on the origin server. | requests without successful validation on the origin server. | |||
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 an | operation for certain protocol features. In all circumstances an | |||
HTTP/1.1 cache MUST obey the must-revalidate directive; in | HTTP/1.1 cache MUST obey the must-revalidate directive; in | |||
particular, if the cache cannot reach the origin server for any | particular, if the cache cannot reach the origin server for any | |||
reason, it MUST generate a 504 (Gateway Timeout) response. | reason, it MUST generate a 504 (Gateway Timeout) response. | |||
Servers SHOULD send the must-revalidate directive if and only if | Servers SHOULD send the must-revalidate directive if and only if | |||
failure to validate a request on the entity could result in | failure to validate a request on the representation could result | |||
incorrect operation, such as a silently unexecuted financial | in incorrect operation, such as a silently unexecuted financial | |||
transaction. | transaction. | |||
proxy-revalidate | proxy-revalidate | |||
The proxy-revalidate response directive has the same meaning as | The proxy-revalidate response directive has the same meaning as | |||
the must-revalidate response directive, except that it does not | the must-revalidate response directive, except that it does not | |||
apply to non-shared caches. | apply to non-shared caches. | |||
max-age | max-age | |||
skipping to change at page 23, line 12 | skipping to change at page 22, line 46 | |||
The s-maxage response directive indicates that, in shared caches, | The s-maxage response directive indicates that, in shared caches, | |||
the maximum age specified by this directive overrides the maximum | the maximum age specified by this directive overrides the maximum | |||
age specified by either the max-age directive or the Expires | age specified by either the max-age directive or the Expires | |||
header. The s-maxage directive also implies the semantics of the | header. The s-maxage directive also implies the semantics of the | |||
proxy-revalidate response directive. | proxy-revalidate response directive. | |||
no-transform | no-transform | |||
The no-transform response directive indicates that an intermediate | The no-transform response directive indicates that an intermediate | |||
cache or proxy MUST NOT change the Content-Encoding, Content-Range | cache or proxy MUST NOT change the Content-Encoding, Content-Range | |||
or Content-Type response headers, nor the response entity-body. | or Content-Type response headers, nor the response representation. | |||
3.2.3. Cache Control Extensions | 3.2.3. Cache Control Extensions | |||
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 cache-extension tokens, each with an optional value. | or more cache-extension tokens, each with an optional value. | |||
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. Behavioral extensions are designed to work by acting as | directives. Behavioral extensions are designed to work by acting as | |||
modifiers to the existing base of cache directives. Both the new | modifiers to the existing base of cache directives. Both the new | |||
directive and the standard directive are supplied, such that | directive and the standard directive are supplied, such that | |||
skipping to change at page 24, line 25 | skipping to change at page 24, line 10 | |||
o Pointer to specification text | o Pointer to specification text | |||
Values to be added to this name space are subject to IETF review | Values to be added to this name space are subject to IETF review | |||
([RFC5226], Section 4.1). | ([RFC5226], Section 4.1). | |||
The registry itself is maintained at | The registry itself is maintained at | |||
<http://www.iana.org/assignments/http-cache-directives>. | <http://www.iana.org/assignments/http-cache-directives>. | |||
3.3. Expires | 3.3. Expires | |||
The "Expires" entity-header field gives the date/time after which the | The "Expires" header field gives the date/time after which the | |||
response is considered stale. See Section 2.3 for further discussion | response is considered stale. See Section 2.3 for further discussion | |||
of the freshness model. | of the freshness model. | |||
The presence of an Expires field does not imply that the original | The presence of an Expires field does not imply that the original | |||
resource will change or cease to exist at, before, or after that | resource will change or cease to exist at, before, or after that | |||
time. | time. | |||
The field-value is an absolute date and time as defined by HTTP-date | The field-value is an absolute date and time as defined by HTTP-date | |||
in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. | in Section 6.1 of [Part1]; it MUST be sent in rfc1123-date format. | |||
skipping to change at page 26, line 25 | skipping to change at page 26, line 9 | |||
resource. A server MAY include a Vary header field with a non- | resource. A server MAY include a Vary header field with a non- | |||
cacheable response that is subject to server-driven negotiation, | cacheable response that is subject to server-driven negotiation, | |||
since this might provide the user agent with useful information about | since this might provide the user agent with useful information about | |||
the dimensions over which the response varies at the time of the | the dimensions over which the response varies at the time of the | |||
response. | response. | |||
A Vary field value of "*" signals that unspecified parameters not | A Vary field value of "*" signals that unspecified parameters not | |||
limited to the request-headers (e.g., the network address of the | limited to the request-headers (e.g., the network address of the | |||
client), play a role in the selection of the response representation; | client), play a role in the selection of the response representation; | |||
therefore, a cache cannot determine whether this response is | therefore, a cache cannot determine whether this response is | |||
appropriate. The "*" value MUST NOT be generated by a proxy server; | appropriate. The "*" value MUST NOT be generated by a proxy server. | |||
it may only be generated by an origin server. | ||||
The field-names given are not limited to the set of standard request- | The field-names given are not limited to the set of standard request- | |||
header fields defined by this specification. Field names are case- | header fields defined by this specification. Field names are case- | |||
insensitive. | insensitive. | |||
3.6. Warning | 3.6. Warning | |||
The "Warning" general-header field is used to carry additional | The "Warning" general-header field is used to carry additional | |||
information about the status or transformation of a message that | information about the status or transformation of a message that | |||
might not be reflected in the message. This information is typically | might not be reflected in the message. This information is typically | |||
used to warn about possible incorrectness introduced by caching | used to warn about possible incorrectness introduced by caching | |||
operations or transformations applied to the entity body of the | operations or transformations applied to the payload of the message. | |||
message. | ||||
Warnings can be used for other purposes, both cache-related and | Warnings can be used for other purposes, both cache-related and | |||
otherwise. The use of a warning, rather than an error status code, | otherwise. The use of a warning, rather than an error status code, | |||
distinguishes these responses from true failures. | distinguishes these responses from true failures. | |||
Warning headers can in general be applied to any message, however | Warning headers can in general be applied to any message, however | |||
some warn-codes are specific to caches and can only be applied to | some warn-codes are specific to caches and can only be applied to | |||
response messages. | response messages. | |||
Warning = "Warning" ":" OWS Warning-v | Warning = "Warning" ":" OWS Warning-v | |||
skipping to change at page 27, line 38 | skipping to change at page 27, line 15 | |||
Warnings are assigned three digit warn-codes. The first digit | Warnings are assigned three digit warn-codes. The first digit | |||
indicates whether the Warning is required to be deleted from a stored | indicates whether the Warning is required to be deleted from a stored | |||
response after validation: | response after validation: | |||
o 1xx Warnings describe the freshness or validation status of the | o 1xx Warnings describe the freshness or validation status of the | |||
response, and so MUST be deleted by caches after validation. They | response, and so MUST be deleted by caches after validation. They | |||
can only be generated by a cache when validating a cached entry, | can only be generated by a cache when validating a cached entry, | |||
and MUST NOT be generated in any other situation. | and MUST NOT be generated in any other situation. | |||
o 2xx Warnings describe some aspect of the entity body or entity | o 2xx Warnings describe some aspect of the representation that is | |||
headers that is not rectified by a validation (for example, a | not rectified by a validation (for example, a lossy compression of | |||
lossy compression of the entity bodies) and MUST NOT be deleted by | the representation) and MUST NOT be deleted by caches after | |||
caches after validation, unless a full response is returned, in | validation, unless a full response is returned, in which case they | |||
which case they MUST be. | MUST be. | |||
If an implementation sends a message with one or more Warning headers | If an implementation sends a message with one or more Warning headers | |||
to a receiver whose version is HTTP/1.0 or lower, then the sender | to a receiver whose version is HTTP/1.0 or lower, then the sender | |||
MUST include in each warning-value a warn-date that matches the Date | MUST include in each warning-value a warn-date that matches the Date | |||
header in the message. | header in the message. | |||
If an implementation receives a message with a warning-value that | If an implementation receives a message with a warning-value that | |||
includes a warn-date, and that warn-date is different from the Date | includes a warn-date, and that warn-date is different from the Date | |||
value in the response, then that warning-value MUST be deleted from | value in the response, then that warning-value MUST be deleted from | |||
the message before storing, forwarding, or using it. (preventing the | the message before storing, forwarding, or using it. (preventing the | |||
skipping to change at page 28, line 41 | skipping to change at page 28, line 20 | |||
199 Miscellaneous warning | 199 Miscellaneous warning | |||
The warning text can include arbitrary information to be presented | The warning text can include arbitrary information to be presented | |||
to a human user, or logged. A system receiving this warning MUST | to a human user, or logged. A system receiving this warning MUST | |||
NOT take any automated action, besides presenting the warning to | NOT take any automated action, besides presenting the warning to | |||
the user. | the user. | |||
214 Transformation applied | 214 Transformation applied | |||
MUST be added by an intermediate cache or proxy if it applies any | MUST be added by an intermediate proxy if it applies any | |||
transformation changing the content-coding (as specified in the | transformation to the representation, such as changing the | |||
Content-Encoding header) or media-type (as specified in the | content-coding, media-type, or modifying the representation data, | |||
Content-Type header) of the response, or the entity-body of the | unless this Warning code already appears in the response. | |||
response, unless this Warning code already appears in the | ||||
response. | ||||
299 Miscellaneous persistent warning | 299 Miscellaneous persistent warning | |||
The warning text can include arbitrary information to be presented | The warning text can include arbitrary information to be presented | |||
to a human user, or logged. A system receiving this warning MUST | to a human user, or logged. A system receiving this warning MUST | |||
NOT take any automated action. | NOT take any automated action. | |||
4. History Lists | 4. History Lists | |||
User agents often have history mechanisms, such as "Back" buttons and | User agents often have history mechanisms, such as "Back" buttons and | |||
history lists, that can be used to redisplay an entity retrieved | history lists, that can be used to redisplay a representation | |||
earlier in a session. | retrieved earlier in a session. | |||
The freshness model (Section 2.3) does not necessarily apply to | The freshness model (Section 2.3) does not necessarily apply to | |||
history mechanisms. I.e., a history mechanism can display a previous | history mechanisms. I.e., a history mechanism can display a previous | |||
representation even if it has expired. | representation even if it has expired. | |||
This does not prohibit the history mechanism from telling the user | This does not prohibit the history mechanism from telling the user | |||
that a view might be stale, or from honoring cache directives (e.g., | that a view might be stale, or from honoring cache directives (e.g., | |||
Cache-Control: no-store). | Cache-Control: no-store). | |||
5. IANA Considerations | 5. IANA Considerations | |||
5.1. Cache Directive Registry | 5.1. Cache Directive Registry | |||
The registration procedure for HTTP Cache Directives is defined by | The registration procedure for HTTP Cache Directives is defined by | |||
Section 3.2.3 of this document. | Section 3.2.3 of this document. | |||
The HTTP Cache Directive Registry should be created at | The HTTP Cache Directive Registry shall be created at | |||
<http://www.iana.org/assignments/http-cache-directives> and be | <http://www.iana.org/assignments/http-cache-directives> and be | |||
populated with the registrations below: | populated with the registrations below: | |||
+------------------------+------------------------------+ | +------------------------+------------------------------+ | |||
| Cache Directive | Reference | | | Cache Directive | Reference | | |||
+------------------------+------------------------------+ | +------------------------+------------------------------+ | |||
| max-age | Section 3.2.1, Section 3.2.2 | | | max-age | Section 3.2.1, Section 3.2.2 | | |||
| max-stale | Section 3.2.1 | | | max-stale | Section 3.2.1 | | |||
| min-fresh | Section 3.2.1 | | | min-fresh | Section 3.2.1 | | |||
| must-revalidate | Section 3.2.2 | | | must-revalidate | Section 3.2.2 | | |||
skipping to change at page 30, line 5 | skipping to change at page 29, line 26 | |||
| no-transform | Section 3.2.1, Section 3.2.2 | | | no-transform | Section 3.2.1, Section 3.2.2 | | |||
| only-if-cached | Section 3.2.1 | | | only-if-cached | Section 3.2.1 | | |||
| private | Section 3.2.2 | | | private | Section 3.2.2 | | |||
| proxy-revalidate | Section 3.2.2 | | | proxy-revalidate | Section 3.2.2 | | |||
| public | Section 3.2.2 | | | public | Section 3.2.2 | | |||
| s-maxage | Section 3.2.2 | | | s-maxage | Section 3.2.2 | | |||
| stale-if-error | [RFC5861], Section 4 | | | stale-if-error | [RFC5861], Section 4 | | |||
| stale-while-revalidate | [RFC5861], Section 3 | | | stale-while-revalidate | [RFC5861], Section 3 | | |||
+------------------------+------------------------------+ | +------------------------+------------------------------+ | |||
5.2. Message Header Registration | 5.2. Header Field Registration | |||
The Message Header Registry located at <http://www.iana.org/ | The Message Header Field Registry located at <http://www.iana.org/ | |||
assignments/message-headers/message-header-index.html> should be | assignments/message-headers/message-header-index.html> shall be | |||
updated with the permanent registrations below (see [RFC3864]): | updated with the permanent registrations below (see [RFC3864]): | |||
+-------------------+----------+----------+-------------+ | +-------------------+----------+----------+-------------+ | |||
| Header Field Name | Protocol | Status | Reference | | | Header Field Name | Protocol | Status | Reference | | |||
+-------------------+----------+----------+-------------+ | +-------------------+----------+----------+-------------+ | |||
| Age | http | standard | Section 3.1 | | | Age | http | standard | Section 3.1 | | |||
| Cache-Control | http | standard | Section 3.2 | | | Cache-Control | http | standard | Section 3.2 | | |||
| Expires | http | standard | Section 3.3 | | | Expires | http | standard | Section 3.3 | | |||
| Pragma | http | standard | Section 3.4 | | | Pragma | http | standard | Section 3.4 | | |||
| Vary | http | standard | Section 3.5 | | | Vary | http | standard | Section 3.5 | | |||
skipping to change at page 30, line 32 | skipping to change at page 30, line 5 | |||
The change controller is: "IETF (iesg@ietf.org) - Internet | The change controller is: "IETF (iesg@ietf.org) - Internet | |||
Engineering Task Force". | Engineering Task Force". | |||
6. Security Considerations | 6. Security Considerations | |||
Caches expose additional potential vulnerabilities, since the | Caches expose additional potential vulnerabilities, since the | |||
contents of the cache represent an attractive target for malicious | contents of the cache represent an attractive target for malicious | |||
exploitation. Because cache contents persist after an HTTP request | exploitation. Because cache contents persist after an HTTP request | |||
is complete, an attack on the cache can reveal information long after | is complete, an attack on the cache can reveal information long after | |||
a user believes that the information has been removed from the | a user believes that the information has been removed from the | |||
network. Therefore, cache contents should be protected as sensitive | network. Therefore, cache contents need to be protected as sensitive | |||
information. | information. | |||
7. Acknowledgments | 7. Acknowledgments | |||
Much of the content and presentation of the caching design is due to | Much of the content and presentation of the caching design is due to | |||
suggestions and comments from individuals including: Shel Kaphan, | suggestions and comments from individuals including: Shel Kaphan, | |||
Paul Leach, Koen Holtman, David Morris, and Larry Masinter. | Paul Leach, Koen Holtman, David Morris, and Larry Masinter. | |||
8. References | 8. References | |||
8.1. Normative References | 8.1. Normative References | |||
[Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | |||
and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, | and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, | |||
and Message Parsing", draft-ietf-httpbis-p1-messaging-10 | and Message Parsing", draft-ietf-httpbis-p1-messaging-11 | |||
(work in progress), July 2010. | (work in progress), August 2010. | |||
[Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | |||
and J. Reschke, Ed., "HTTP/1.1, part 2: Message | and J. Reschke, Ed., "HTTP/1.1, part 2: Message | |||
Semantics", draft-ietf-httpbis-p2-semantics-10 (work in | Semantics", draft-ietf-httpbis-p2-semantics-11 (work in | |||
progress), July 2010. | progress), August 2010. | |||
[Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | |||
and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional | and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional | |||
Requests", draft-ietf-httpbis-p4-conditional-10 (work in | Requests", draft-ietf-httpbis-p4-conditional-11 (work in | |||
progress), July 2010. | progress), August 2010. | |||
[Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | |||
and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and | and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and | |||
Partial Responses", draft-ietf-httpbis-p5-range-10 (work | Partial Responses", draft-ietf-httpbis-p5-range-11 (work | |||
in progress), July 2010. | in progress), August 2010. | |||
[Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., | |||
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., | |||
and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", | and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", | |||
draft-ietf-httpbis-p7-auth-10 (work in progress), | draft-ietf-httpbis-p7-auth-11 (work in progress), | |||
July 2010. | August 2010. | |||
[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, March 1997. | Requirement Levels", BCP 14, RFC 2119, March 1997. | |||
[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, January 2008. | Specifications: ABNF", STD 68, RFC 5234, January 2008. | |||
8.2. Informative References | 8.2. Informative References | |||
[RFC1305] Mills, D., "Network Time Protocol (Version 3) | [RFC1305] Mills, D., "Network Time Protocol (Version 3) | |||
skipping to change at page 32, line 5 | skipping to change at page 31, line 26 | |||
Procedures for Message Header Fields", BCP 90, RFC 3864, | Procedures for Message Header Fields", BCP 90, RFC 3864, | |||
September 2004. | September 2004. | |||
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an | [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an | |||
IANA Considerations Section in RFCs", BCP 26, RFC 5226, | IANA Considerations Section in RFCs", BCP 26, RFC 5226, | |||
May 2008. | May 2008. | |||
[RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale | [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale | |||
Content", RFC 5861, April 2010. | Content", RFC 5861, April 2010. | |||
Appendix A. Compatibility with Previous Versions | Appendix A. Changes from RFC 2616 | |||
A.1. Changes from RFC 2068 | ||||
A case was missed in the Cache-Control model of HTTP/1.1; s-maxage | ||||
was introduced to add this missing case. (Sections 2.1, 3.2). | ||||
Range request responses would become very verbose if all meta-data | ||||
were always returned; by allowing the server to only send needed | ||||
headers in a 206 response, this problem can be avoided. | ||||
(Section 2.8) | ||||
The Cache-Control: max-age directive was not properly defined for | ||||
responses. (Section 3.2.2) | ||||
Warnings could be cached incorrectly, or not updated appropriately. | ||||
(Section 2.3, 2.8, 3.2, and 3.6) Warning also needed to be a general | ||||
header, as PUT or other methods may have need for it in requests. | ||||
A.2. Changes from RFC 2616 | ||||
Make the specified age calculation algorithm less conservative. | Make the specified age calculation algorithm less conservative. | |||
(Section 2.3.2) | (Section 2.3.2) | |||
Remove requirement to consider Content-Location in successful | Remove requirement to consider Content-Location in successful | |||
responses in order to determine the appropriate response to use. | responses in order to determine the appropriate response to use. | |||
(Section 2.4) | (Section 2.4) | |||
Clarify denial of service attack avoidance requirement. | Clarify denial of service attack avoidance requirement. | |||
(Section 2.5) | (Section 2.5) | |||
skipping to change at page 38, line 8 | skipping to change at page 37, line 10 | |||
for cache-control directives" | for cache-control directives" | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/211>: "Heuristic | o <http://tools.ietf.org/wg/httpbis/trac/ticket/211>: "Heuristic | |||
caching of URLs with query components" | caching of URLs with query components" | |||
Partly resolved issues: | Partly resolved issues: | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/196>: "Term for the | o <http://tools.ietf.org/wg/httpbis/trac/ticket/196>: "Term for the | |||
requested resource's URI" | requested resource's URI" | |||
C.12. Since draft-ietf-httpbis-p6-cache-10 | ||||
Closed issues: | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/109>: "Clarify | ||||
entity / representation / variant terminology" | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/220>: "consider | ||||
removing the 'changes from 2068' sections" | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing | ||||
heuristic caching for new status codes" | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing | ||||
heuristic caching for new status codes" | ||||
o Clean up TODOs and prose in "Combining Responses." | ||||
Index | Index | |||
A | A | |||
age 6 | age 6 | |||
Age header 17 | Age header 17 | |||
C | C | |||
cache 5 | cache 5 | |||
Cache Directives | Cache Directives | |||
max-age 19, 22 | max-age 19, 22 | |||
max-stale 19 | max-stale 19 | |||
min-fresh 20 | min-fresh 19 | |||
must-revalidate 22 | must-revalidate 22 | |||
no-cache 19, 21 | no-cache 19, 21 | |||
no-store 19, 22 | no-store 19, 21 | |||
no-transform 20, 23 | no-transform 20, 22 | |||
only-if-cached 20 | only-if-cached 20 | |||
private 21 | private 20 | |||
proxy-revalidate 22 | proxy-revalidate 22 | |||
public 20 | public 20 | |||
s-maxage 22 | s-maxage 22 | |||
Cache-Control header 18 | Cache-Control header 18 | |||
cacheable 5 | cacheable 5 | |||
E | E | |||
Expires header 24 | Expires header 24 | |||
explicit expiration time 5 | explicit expiration time 5 | |||
F | F | |||
first-hand 6 | first-hand 6 | |||
fresh 6 | fresh 6 | |||
freshness lifetime 6 | freshness lifetime 6 | |||
G | G | |||
Grammar | Grammar | |||
Age 18 | Age 17 | |||
Age-v 18 | Age-v 17 | |||
Cache-Control 18 | Cache-Control 18 | |||
Cache-Control-v 18 | Cache-Control-v 18 | |||
cache-extension 18 | cache-extension 18 | |||
cache-request-directive 19 | cache-request-directive 18 | |||
cache-response-directive 20 | cache-response-directive 20 | |||
delta-seconds 18 | delta-seconds 17 | |||
Expires 24 | Expires 24 | |||
Expires-v 24 | Expires-v 24 | |||
extension-pragma 25 | extension-pragma 24 | |||
Pragma 25 | Pragma 24 | |||
pragma-directive 25 | pragma-directive 24 | |||
Pragma-v 25 | Pragma-v 24 | |||
Vary 26 | Vary 25 | |||
Vary-v 26 | Vary-v 25 | |||
warn-agent 27 | warn-agent 26 | |||
warn-code 27 | warn-code 26 | |||
warn-date 27 | warn-date 26 | |||
warn-text 27 | warn-text 26 | |||
Warning 27 | Warning 26 | |||
Warning-v 27 | Warning-v 26 | |||
warning-value 27 | warning-value 26 | |||
H | H | |||
Headers | Headers | |||
Age 17 | Age 17 | |||
Cache-Control 18 | Cache-Control 18 | |||
Expires 24 | Expires 24 | |||
Pragma 25 | Pragma 24 | |||
Vary 25 | Vary 25 | |||
Warning 26 | Warning 26 | |||
heuristic expiration time 5 | heuristic expiration time 5 | |||
M | M | |||
max-age | max-age | |||
Cache Directive 19, 22 | Cache Directive 19, 22 | |||
max-stale | max-stale | |||
Cache Directive 19 | Cache Directive 19 | |||
min-fresh | min-fresh | |||
Cache Directive 20 | Cache Directive 19 | |||
must-revalidate | must-revalidate | |||
Cache Directive 22 | Cache Directive 22 | |||
N | N | |||
no-cache | no-cache | |||
Cache Directive 19, 21 | Cache Directive 19, 21 | |||
no-store | no-store | |||
Cache Directive 19, 22 | Cache Directive 19, 21 | |||
no-transform | no-transform | |||
Cache Directive 20, 23 | Cache Directive 20, 22 | |||
O | O | |||
only-if-cached | only-if-cached | |||
Cache Directive 20 | Cache Directive 20 | |||
P | P | |||
Pragma header 25 | Pragma header 24 | |||
private | private | |||
Cache Directive 21 | Cache Directive 20 | |||
proxy-revalidate | proxy-revalidate | |||
Cache Directive 22 | Cache Directive 22 | |||
public | public | |||
Cache Directive 20 | Cache Directive 20 | |||
S | S | |||
s-maxage | s-maxage | |||
Cache Directive 22 | Cache Directive 22 | |||
stale 6 | stale 6 | |||
End of changes. 79 change blocks. | ||||
191 lines changed or deleted | 167 lines changed or added | |||
This html diff was produced by rfcdiff 1.38. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |