draft-ietf-httpbis-p6-cache-12.txt | draft-ietf-httpbis-p6-cache-13.txt | |||
---|---|---|---|---|
HTTPbis Working Group R. Fielding, Ed. | HTTPbis Working Group R. Fielding, Ed. | |||
Internet-Draft Day Software | Internet-Draft Adobe | |||
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: April 28, 2011 J. Mogul | Expires: September 15, 2011 J. Mogul | |||
HP | HP | |||
H. Frystyk | H. Frystyk | |||
Microsoft | Microsoft | |||
L. Masinter | L. Masinter | |||
Adobe Systems | Adobe | |||
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 | |||
October 25, 2010 | March 14, 2011 | |||
HTTP/1.1, part 6: Caching | HTTP/1.1, part 6: Caching | |||
draft-ietf-httpbis-p6-cache-12 | draft-ietf-httpbis-p6-cache-13 | |||
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.13. | The changes in this draft are summarized in Appendix C.14. | |||
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 April 28, 2011. | This Internet-Draft will expire on September 15, 2011. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2010 IETF Trust and the persons identified as the | Copyright (c) 2011 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 | |||
carefully, as they describe your rights and restrictions with respect | carefully, as they describe your rights and restrictions with respect | |||
to this document. Code Components extracted from this document must | to this document. Code Components extracted from this document must | |||
include Simplified BSD License text as described in Section 4.e of | include Simplified BSD License text as described in Section 4.e of | |||
the Trust Legal Provisions and are provided without warranty as | the Trust Legal Provisions and are provided without warranty as | |||
skipping to change at page 2, line 51 | skipping to change at page 2, line 51 | |||
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 . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 | 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 | 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 | 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 | 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 | |||
1.4.2. ABNF Rules defined in other Parts of the | 1.4.2. ABNF Rules defined in other Parts of the | |||
Specification . . . . . . . . . . . . . . . . . . . . 7 | Specification . . . . . . . . . . . . . . . . . . . . 7 | |||
2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 | 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 | 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 8 | |||
2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 | 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 9 | |||
2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 | 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 | |||
2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 | 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 | |||
2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 | 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 | |||
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 . . . . . . . . . . . . . 15 | 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 15 | |||
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 . . . . . . . . . . . . . . . . . . . 17 | 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17 | |||
3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 | 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 | |||
3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
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 . . . . . . . . . . . 19 | |||
3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 | 3.2.2. Response Cache-Control Directives . . . . . . . . . . 21 | |||
3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 | 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 | |||
3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 | 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 | |||
3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 | 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 | 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 | 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 | |||
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 | |||
5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 | 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 | |||
5.2. Header Field Registration . . . . . . . . . . . . . . . . 30 | 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30 | |||
6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 | |||
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 | 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31 | |||
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 | 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31 | |||
8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 | 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31 | |||
8.2. Informative References . . . . . . . . . . . . . . . . . . 31 | 8.2. Informative References . . . . . . . . . . . . . . . . . . 32 | |||
Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 | Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32 | |||
Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 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) . . . . . . . . . . . . . . . . . . . . 33 | publication) . . . . . . . . . . . . . . . . . . . . 34 | |||
C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 | C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34 | |||
C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 | C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 | |||
C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 | C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 | |||
C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 | C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 | |||
C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 | C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 | |||
C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 | C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 | |||
C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 | C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 | |||
C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 | C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 | |||
C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 | C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 | |||
C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 36 | C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 | |||
C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 | C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 | |||
C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 37 | C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 38 | |||
C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 | C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38 | |||
C.14. Since draft-ietf-httpbis-p6-cache-12 . . . . . . . . . . . 38 | ||||
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 | Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 | |||
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 | |||
skipping to change at page 5, line 37 | skipping to change at page 5, line 37 | |||
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 | |||
(see Section 2.4). | (see Section 2.4). | |||
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. | |||
cache | ||||
A conformant implementation of a HTTP cache. Note that this | ||||
implies an HTTP/1.1 cache; this specification does not define | ||||
conformance for HTTP/1.0 caches. | ||||
shared cache | ||||
A cache that is accessible to more than one user; usually (but not | ||||
always) deployed as part of an intermediary. | ||||
private cache | ||||
A cache that is dedicated to a single user. | ||||
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 might 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 stored copy to satisfy | |||
a particular request. | a particular request. | |||
explicit expiration time | explicit expiration time | |||
The time at which the origin server intends that a representation | 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 | |||
skipping to change at page 6, line 38 | skipping to change at page 6, line 51 | |||
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 has an | that is used to find out whether a stored response is an | |||
equivalent copy of a representation. | equivalent copy of a representation. | |||
shared cache | ||||
A cache that is accessible to more than one user. A non-shared | ||||
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 | |||
document are to be interpreted as described in [RFC2119]. | document are to be interpreted as described in [RFC2119]. | |||
An implementation is not compliant if it fails to satisfy one or more | An implementation is not compliant if it fails to satisfy one or more | |||
of the "MUST" or "REQUIRED" level requirements for the protocols it | of the "MUST" or "REQUIRED" level requirements for the protocols it | |||
implements. An implementation that satisfies all the "MUST" or | implements. An implementation that satisfies all the "MUST" or | |||
"REQUIRED" level and all the "SHOULD" level requirements for its | "REQUIRED" level and all the "SHOULD" level requirements for its | |||
skipping to change at page 9, line 20 | skipping to change at page 9, line 30 | |||
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-header fields nominated by the stored response | o selecting header fields nominated by the stored response (if any) | |||
(if any) match those presented (see Section 2.7), and | 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). | |||
When a stored response is used to satisfy a request without | When a stored response is used to satisfy a request without | |||
validation, caches MUST include a single Age header field | validation, a cache MUST include a single Age header field | |||
(Section 3.1) in the response with a value equal to the stored | (Section 3.1) in the response with a value equal to the stored | |||
response's current_age; see Section 2.3.2. | response's current_age; see Section 2.3.2. | |||
Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST | A cache MUST write through requests with methods that are unsafe | |||
be written through the cache to the origin server; i.e., a cache must | (Section 7.1.1 of [Part2]) to the origin server; i.e., a cache must | |||
not reply to such a request before having forwarded the request and | not generate a reply to such a request before having forwarded the | |||
having received a corresponding response. | 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 2.5. | responses; see Section 2.5. | |||
Caches MUST use the most recent response (as determined by the Date | A cache MUST use the most recent response (as determined by the Date | |||
header field) when more than one suitable response is stored. They | header field) when more than one suitable response is stored. It can | |||
can also forward a request with "Cache-Control: max-age=0" or "Cache- | also forward a 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. | |||
An HTTP implementation without a clock MUST NOT used stored responses | A cache that does not have a clock available MUST NOT used stored | |||
without revalidating them on every use. An HTTP cache, especially a | responses without revalidating them on every use. A cache, | |||
shared cache, SHOULD use a mechanism, such as NTP [RFC1305], to | especially a shared cache, SHOULD use a mechanism, such as NTP | |||
synchronize its clock with a reliable external standard. | [RFC1305], to synchronize its clock with a reliable external | |||
standard. | ||||
2.3. Freshness Model | 2.3. Freshness Model | |||
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 field (Section 3.3) or the max-age response | either the Expires header field (Section 3.3) or the max-age response | |||
cache directive (Section 3.2.2). Generally, origin servers will | cache directive (Section 3.2.2). Generally, origin servers will | |||
assign future explicit expiration times to responses in the belief | assign future explicit expiration times to responses in the belief | |||
that the representation is not likely to change in a semantically | that the representation is not likely to change in a semantically | |||
significant way before the expiration time is reached. | significant 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 to | request, it can assign an explicit expiration time in the past to | |||
indicate that the response is already stale. Compliant caches will | indicate that the response is already stale. Compliant caches will | |||
validate the cached response before reusing it for subsequent | normally validate the cached response before reusing it for | |||
requests. | subsequent requests (see Section 2.3.3). | |||
Since origin servers do not always provide explicit expiration times, | Since origin servers do not always provide explicit expiration times, | |||
HTTP caches MAY assign heuristic expiration times when explicit times | a cache MAY assign a heuristic expiration time when an explicit time | |||
are not specified, employing algorithms that use other heade field | is not specified, employing algorithms that use other header field | |||
values (such as the Last-Modified time) to estimate a plausible | values (such as the Last-Modified time) to estimate a plausible | |||
expiration time. The HTTP/1.1 specification does not provide | expiration time. This specification does not provide specific | |||
specific algorithms, but does impose worst-case constraints on their | algorithms, but does impose worst-case constraints on their results. | |||
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 might 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 | |||
skipping to change at page 11, line 35 | skipping to change at page 11, line 44 | |||
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 whose definition allows heuristic freshness to be | has a status code whose definition allows heuristic freshness to be | |||
used (including the following in Section 8 of [Part2]: 200, 203, 206, | used (including the following in Section 8 of [Part2]: 200, 203, 206, | |||
300, 301 and 410), a heuristic expiration time MAY be calculated. | 300, 301 and 410), a cache MAY calculate a heuristic expiration time. | |||
Heuristics MUST NOT be used for response status codes that do not | A cache MUST NOT use heuristics to determine freshness for responses | |||
explicitly allow it. | with 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, a cache | |||
SHOULD attach a Warning header field with a 113 warn-code to the | SHOULD attach a Warning header field with a 113 warn-code to the | |||
response if its current_age is more than 24 hours and such a warning | response if its current_age is more than 24 hours and such a warning | |||
is not already present. | is not already present. | |||
Also, if the response has a Last-Modified header field (Section 6.6 | Also, if the response has a Last-Modified header field (Section 6.6 | |||
of [Part4]), the heuristic expiration value SHOULD be no more than | of [Part4]), a cache SHOULD NOT use a heuristic expiration value that | |||
some fraction of the interval since that time. A typical setting of | is more than some fraction of the interval since that time. A | |||
this fraction might be 10%. | typical setting of this fraction might be 10%. | |||
Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do | Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do | |||
not calculate heuristic freshness for URLs with query components | not calculate heuristic freshness for URIs with query components | |||
(i.e., those containing '?'). In practice, this has not been | (i.e., those containing '?'). In practice, this has not been | |||
widely implemented. Therefore, servers are encouraged to send | widely implemented. Therefore, servers are encouraged to send | |||
explicit directives (e.g., Cache-Control: no-cache) if they wish | explicit directives (e.g., Cache-Control: no-cache) if they wish | |||
to preclude caching. | to preclude caching. | |||
2.3.2. Calculating Age | 2.3.2. Calculating Age | |||
HTTP/1.1 uses the Age response-header field to convey the estimated | HTTP/1.1 uses the Age header field to convey the estimated age of the | |||
age of the response message when obtained from a cache. The Age | response message when obtained from a cache. The Age field value is | |||
field value is the cache's estimate of the amount of time since the | the cache's estimate of the amount of time since the response was | |||
response was generated or validated by the origin server. In | generated or validated by the origin server. In essence, the Age | |||
essence, the Age value is the sum of the time that the response has | value is the sum of the time that the response has been resident in | |||
been resident in each of the caches along the path from the origin | each of the caches along the path from the origin server, plus the | |||
server, plus the amount of time it has been in transit along network | amount of time it has been in transit along network paths. | |||
paths. | ||||
The following data is used for the age calculation: | The following data is used for the age calculation: | |||
age_value | age_value | |||
The term "age_value" denotes the value of the Age header field | The term "age_value" denotes the value of the Age header field | |||
(Section 3.1), in a form appropriate for arithmetic operation; or | (Section 3.1), in a form appropriate for arithmetic operation; or | |||
0, if not available. | 0, if not available. | |||
date_value | date_value | |||
skipping to change at page 12, line 40 | skipping to change at page 12, line 48 | |||
possible, with every response, giving the time at which the | possible, with every response, giving the time at which the | |||
response was generated. The term "date_value" denotes the value | response was generated. The term "date_value" denotes the value | |||
of the Date header field, in a form appropriate for arithmetic | of the Date header field, in a form appropriate for arithmetic | |||
operations. See Section 9.3 of [Part1] for the definition of the | operations. See Section 9.3 of [Part1] for the definition of the | |||
Date header field, and for requirements regarding responses | Date header field, and for requirements regarding responses | |||
without it. | without it. | |||
now | now | |||
The term "now" means "the current value of the clock at the host | The term "now" means "the current value of the clock at the host | |||
performing the calculation". Hosts that use HTTP, but especially | performing the calculation". A cache SHOULD use NTP ([RFC1305]) | |||
hosts running origin servers and caches, SHOULD use NTP | or some similar protocol to synchronize its clocks to a globally | |||
([RFC1305]) or some similar protocol to synchronize their clocks | accurate time standard. | |||
to a globally accurate time standard. | ||||
request_time | request_time | |||
The current value of the clock at the host at the time the request | The current value of the clock at the host at the time the request | |||
resulting in the stored response was made. | resulting in the stored response was made. | |||
response_time | response_time | |||
The current value of the clock at the host at the time the | The current value of the clock at the host at the time the | |||
response was received. | 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 local | 1. the "apparent_age": response_time minus date_value, if the local | |||
clock is reasonably well synchronized to the origin server's | clock is reasonably well synchronized to the origin server's | |||
clock. If the result is negative, the result is replaced by | clock. If the result is negative, the result is replaced by | |||
zero. | 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; note this value MUST be | response path implement HTTP/1.1. A cache MUST interpret this | |||
interpreted relative to the time the request was initiated, not | value relative to the time the request was initiated, not the | |||
the time that the response was received. | time that the response was received. | |||
apparent_age = max(0, response_time - date_value); | apparent_age = max(0, response_time - date_value); | |||
response_delay = response_time - request_time; | response_delay = response_time - request_time; | |||
corrected_age_value = age_value + response_delay; | corrected_age_value = age_value + response_delay; | |||
These are combined as | These are combined as | |||
corrected_initial_age = max(apparent_age, corrected_age_value); | corrected_initial_age = max(apparent_age, corrected_age_value); | |||
skipping to change at page 13, line 44 | skipping to change at page 13, line 49 | |||
resident_time = now - response_time; | resident_time = now - response_time; | |||
current_age = corrected_initial_age + resident_time; | current_age = corrected_initial_age + resident_time; | |||
2.3.3. Serving Stale Responses | 2.3.3. 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 2.3. | according to the calculations in Section 2.3. | |||
Caches MUST NOT return a stale response if it is prohibited by an | A cache MUST NOT return a stale response if it is prohibited by an | |||
explicit in-protocol directive (e.g., by a "no-store" or "no-cache" | explicit in-protocol directive (e.g., by a "no-store" or "no-cache" | |||
cache directive, a "must-revalidate" cache-response-directive, or an | cache directive, a "must-revalidate" cache-response-directive, or an | |||
applicable "s-maxage" or "proxy-revalidate" cache-response-directive; | applicable "s-maxage" or "proxy-revalidate" cache-response-directive; | |||
see Section 3.2.2). | see Section 3.2.2). | |||
Caches SHOULD NOT return stale responses unless they are disconnected | A cache SHOULD NOT return stale responses unless it is disconnected | |||
(i.e., it cannot contact the origin server or otherwise find a | (i.e., it cannot contact the origin server or otherwise find a | |||
forward path) or otherwise explicitly allowed (e.g., the max-stale | forward path) or otherwise explicitly allowed (e.g., the max-stale | |||
request directive; see Section 3.2.1). | request directive; see Section 3.2.1). | |||
Stale responses SHOULD have a Warning header field with the 110 warn- | A cache SHOULD append a Warning header field with the 110 warn-code | |||
code (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent | (see Section 3.6) to stale responses. Likewise, a cache SHOULD add | |||
on stale responses if the cache is disconnected. | the 112 warn-code to stale responses if the cache is disconnected. | |||
If a cache receives a first-hand response (either an entire response, | If a cache receives a first-hand response (either an entire response, | |||
or a 304 (Not Modified) response) that it would normally forward to | or a 304 (Not Modified) response) that it would normally forward to | |||
the requesting client, and the received response is no longer fresh, | the requesting client, and the received response is no longer fresh, | |||
the cache SHOULD forward it to the requesting client without adding a | the cache SHOULD forward it to the requesting client without adding a | |||
new Warning (but without removing any existing Warning header | new Warning (but without removing any existing Warning header | |||
fields). A cache SHOULD NOT attempt to validate a response simply | fields). A cache SHOULD NOT attempt to validate a response simply | |||
because that response became stale in transit. | because that response became stale in transit. | |||
2.4. Validation Model | 2.4. Validation Model | |||
When a cache has one or more stored responses for a requested URI, | When a cache has one or more stored responses for a requested URI, | |||
but cannot serve any of them (e.g., because they are not fresh, or | but cannot serve any of them (e.g., because they are not fresh, or | |||
one cannot be selected; see Section 2.7), it can use the conditional | one cannot be selected; see Section 2.7), it can use the conditional | |||
request mechanism [Part4] in the forwarded request to give the origin | request mechanism [Part4] in the forwarded request to give the origin | |||
server an opportunity to both select a valid stored response to be | server an opportunity to both select a valid stored response to be | |||
used, and to update it. This process is known as "validating" or | used, and to update it. This process is known as "validating" or | |||
"revalidating" the stored response. | "revalidating" the stored response. | |||
When sending such a conditional request, the cache SHOULD add an If- | When sending such a conditional request, a cache SHOULD add an If- | |||
Modified-Since header field whose value is that of the Last-Modified | Modified-Since header field whose value is that of the Last-Modified | |||
header field from the selected (see Section 2.7) stored response, if | header field from the selected (see Section 2.7) stored response, if | |||
available. | available. | |||
Additionally, the cache SHOULD add an If-None-Match header field | Additionally, a cache SHOULD add an If-None-Match header field whose | |||
whose value is that of the ETag header field(s) from all responses | value is that of the ETag header field(s) from all responses stored | |||
stored for the requested URI, if present. However, if any of the | for the requested URI, if present. However, if any of the stored | |||
stored responses contains only partial content, its entity-tag SHOULD | responses contains only partial content, the cache SHOULD NOT include | |||
NOT be included in the If-None-Match header field unless the request | its entity-tag in the If-None-Match header field unless the request | |||
is for a range that would be fully satisfied by that stored response. | is for a range 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 SHOULD be used to satisfy the | suitable. Instead, a cache SHOULD use the full response to satisfy | |||
request and MAY replace the stored response. | the request and MAY replace the stored response. | |||
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 request methods (Section 7.1.1 of [Part2]) have the | |||
for changing state on the origin server, intervening caches can use | potential for changing state on the origin server, intervening caches | |||
them to keep their contents up-to-date. | can use them to keep their contents up-to-date. | |||
The following HTTP methods MUST cause a cache to invalidate the | A cache MUST invalidate the effective Request URI (Section 4.3 of | |||
effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) | [Part1]) as well as the URI(s) in the Location and Content-Location | |||
in the Location and Content-Location header fields (if present): | header fields (if present) when the following request methods are | |||
received: | ||||
o PUT | o PUT | |||
o DELETE | o DELETE | |||
o POST | o POST | |||
An invalidation based on a URI from a Location or Content-Location | However, a cache MUST NOT invalidate a URI from a Location or | |||
header field MUST NOT be performed if the host part of that URI | Content-Location header field if the host part of that URI differs | |||
differs from the host part in the effective request URI (Section 4.3 | from the host part in the effective request URI (Section 4.3 of | |||
of [Part1]). This helps prevent denial of service attacks. | [Part1]). This helps prevent denial of service attacks. | |||
A cache that passes through requests for methods it does not | A cache that passes through requests with 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. | |||
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 | A shared cache MUST NOT use a cached response to a request with an | |||
Authorization header field (Section 4.1 of [Part7]) to satisfy any | Authorization header field (Section 4.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. | |||
Note that cached responses that contain the "must-revalidate" and/or | Note that cached responses that contain the "must-revalidate" and/or | |||
"s-maxage" response directives are not allowed to be served stale | "s-maxage" response directives are not allowed to be served stale | |||
(Section 2.3.3) by shared caches. In particular, a response with | (Section 2.3.3) by shared caches. In particular, a response with | |||
either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to | either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to | |||
satisfy a subsequent request without revalidating it on the origin | satisfy a subsequent request without revalidating it on the origin | |||
server. | server. | |||
2.7. Caching Negotiated Responses | 2.7. Caching Negotiated Responses | |||
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 that has a Vary header field (Section 3.5), it MUST NOT use | response that has a Vary header field (Section 3.5), it MUST NOT use | |||
that response unless all of the selecting request-header fields | that response unless all of the selecting header fields nominated by | |||
nominated by the Vary header field match in both the original request | the Vary header field match in both the original request (i.e., that | |||
(i.e., that associated with the stored response), and the presented | associated with the stored response), and the presented request. | |||
request. | ||||
The selecting request-header fields from two requests are defined to | The selecting header fields from two requests are defined to match if | |||
match if and only if those in the first request can be transformed to | and only if those in the first request can be transformed to those in | |||
those in the second request by applying any of the following: | the second request by applying any of the following: | |||
o adding or removing whitespace, where allowed in the header field's | o adding or removing whitespace, where allowed in the header field's | |||
syntax | syntax | |||
o combining multiple message-header fields with the same field name | o combining multiple header fields with the same field name (see | |||
(see Section 3.2 of [Part1]) | Section 3.2 of [Part1]) | |||
o normalizing both header field values in a way that is known to | o 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., re-ordering field values when order is not | specification (e.g., re-ordering field values when order is not | |||
significant; case-normalization, where values are defined to be | significant; case-normalization, where values are defined to be | |||
case-insensitive) | case-insensitive) | |||
If (after any normalization that might take place) a header field is | If (after any normalization that might take place) a header field is | |||
absent from a request, it can only match another request if it is | absent from a request, it can only match another request if it is | |||
also absent there. | also absent there. | |||
A 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-header fields is | The stored response with matching selecting header fields is known as | |||
known as the selected response. | 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 | create 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, and potentially update the cached response. | 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: might need language about | response to use. [[TODO-mention-CL: might need language about | |||
Content-Location here]][[TODO-select-for-combine: Shouldn't this be | Content-Location here]][[TODO-select-for-combine: Shouldn't this be | |||
the selected response?]] | the selected response?]] | |||
If the new response's status code is 206 (partial content), both the | When the new response's status code is 206 (partial content), a cache | |||
stored and new responses MUST have validators, and those validators | MUST NOT combine it with the old response if either response does not | |||
MUST match using the strong comparison function (see Section 4 of | have a validator, and MUST NOT combine it with the old response when | |||
[Part4]). Otherwise, the responses MUST NOT be combined. | those validators do not match with the strong comparison function | |||
(see Section 4 of [Part4]). | ||||
The stored response header fields are used as those of the updated | The stored response header fields are used as those of the updated | |||
response, except that | response, except that | |||
o any stored Warning header fields with warn-code 1xx (see | o a cache MUST delete any stored Warning header fields with warn- | |||
Section 3.6) MUST be deleted. | code 1xx (see Section 3.6). | |||
o any stored Warning header fields with warn-code 2xx MUST be | o a cache MUST retain any stored Warning header fields with warn- | |||
retained. | code 2xx. | |||
o any other header fields provided in the new response MUST replace | o a cache MUST use other header fields provided in the new response | |||
all instances of the corresponding header fields from the stored | to replace all instances of the corresponding header fields from | |||
response. | the stored response. | |||
The updated response header fields MUST be used to replace those of | A cache MUST use the updated response header fields to replace those | |||
the stored response in cache (unless the stored response is removed | of the stored response (unless the stored response is removed). In | |||
from cache). In the case of a 206 response, the combined | the case of a 206 response, a cache MAY store the combined | |||
representation MAY be stored. | representation. | |||
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. | |||
3.1. Age | 3.1. Age | |||
The "Age" response-header field conveys the sender's estimate of the | The "Age" header field conveys the sender's estimate of the amount of | |||
amount of time since the response was generated or successfully | time since the response was generated or successfully validated at | |||
validated at the origin server. Age values are calculated as | the origin server. Age values are calculated as specified in | |||
specified in Section 2.3.2. | Section 2.3.2. | |||
Age = "Age" ":" OWS Age-v | Age = "Age" ":" OWS Age-v | |||
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 field with a field-value of 2147483648 | MUST transmit an Age header field with a field-value of 2147483648 | |||
(2^31). Caches SHOULD use an arithmetic type of at least 31 bits of | (2^31). Recipients parsing the Age header field-value SHOULD use an | |||
range. | 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 might 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" header field is used to specify directives for | |||
directives for caches along the request/response chain. Such cache | caches along the request/response chain. Such cache directives are | |||
directives are unidirectional in that the presence of a directive in | unidirectional in that the presence of a directive in a request does | |||
a request does not imply that the same directive is to be given in | 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 | A cache MUST obey the requirements of the Cache-Control directives | |||
directives defined in this section. See Section 3.2.3 for | defined in this section. See Section 3.2.3 for information about how | |||
information about how Cache-Control directives defined elsewhere are | Cache-Control directives defined elsewhere are handled. | |||
handled. | ||||
Note: HTTP/1.0 caches might not implement Cache-Control and might | Note: HTTP/1.0 caches might not implement Cache-Control and might | |||
only implement Pragma: no-cache (see Section 3.4). | only implement Pragma: no-cache (see Section 3.4). | |||
Cache directives MUST be passed through by a proxy or gateway | A proxy, whether or not it implements a cache, MUST pass cache | |||
application, regardless of their significance to that application, | directives through in forwarded messages, regardless of their | |||
since the directives might be applicable to all recipients along the | significance to that application, since the directives might be | |||
request/response chain. It is not possible to target a directive to | applicable to all recipients along the request/response chain. It is | |||
a specific cache. | not possible to target a directive to a specific cache. | |||
Cache-Control = "Cache-Control" ":" OWS Cache-Control-v | Cache-Control = "Cache-Control" ":" OWS Cache-Control-v | |||
Cache-Control-v = 1#cache-directive | Cache-Control-v = 1#cache-directive | |||
cache-directive = cache-request-directive | cache-directive = cache-request-directive | |||
/ cache-response-directive | / cache-response-directive | |||
cache-extension = token [ "=" ( token / quoted-string ) ] | cache-extension = token [ "=" ( token / quoted-string ) ] | |||
3.2.1. Request Cache-Control Directives | 3.2.1. Request Cache-Control Directives | |||
skipping to change at page 19, line 19 | skipping to change at page 19, line 27 | |||
/ "no-store" | / "no-store" | |||
/ "max-age" "=" delta-seconds | / "max-age" "=" delta-seconds | |||
/ "max-stale" [ "=" delta-seconds ] | / "max-stale" [ "=" delta-seconds ] | |||
/ "min-fresh" "=" delta-seconds | / "min-fresh" "=" delta-seconds | |||
/ "no-transform" | / "no-transform" | |||
/ "only-if-cached" | / "only-if-cached" | |||
/ cache-extension | / cache-extension | |||
no-cache | no-cache | |||
The no-cache request directive indicates that a stored response | The no-cache request directive indicates that a cache MUST NOT use | |||
MUST NOT be used to satisfy the request without successful | a stored response to satisfy the request without successful | |||
validation on the origin server. | validation on the origin server. | |||
no-store | 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 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 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 | 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 might be vulnerable to eavesdropping. | networks might be vulnerable to eavesdropping. | |||
Note that if a request containing this directive is satisfied from | ||||
a cache, the no-store request directive does not apply to the | ||||
already stored response. | ||||
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 | |||
skipping to change at page 20, line 16 | skipping to change at page 20, line 32 | |||
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 intermediary | |||
cache or proxy MUST NOT change the Content-Encoding, Content-Range | (whether or not it implements a cache) MUST NOT change the | |||
or Content-Type request header fields, nor the request | Content-Encoding, Content-Range or Content-Type request header | |||
representation. | fields, 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 code. If a group of | respond with a 504 (Gateway Timeout) status code. If a group of | |||
caches 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, a member cache MAY forward such a request within | |||
caches. | that group of 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" | |||
/ "no-transform" | / "no-transform" | |||
/ "must-revalidate" | / "must-revalidate" | |||
/ "proxy-revalidate" | / "proxy-revalidate" | |||
/ "max-age" "=" delta-seconds | / "max-age" "=" delta-seconds | |||
/ "s-maxage" "=" delta-seconds | / "s-maxage" "=" delta-seconds | |||
/ cache-extension | / cache-extension | |||
public | public | |||
The public response directive indicates that the response MAY be | The public response directive indicates that a response whose | |||
cached, even if it would normally be non-cacheable or cacheable | associated request contains an 'Authentication' header MAY be | |||
only within a non-shared cache. (See also Authorization, Section | stored (see Section 2.6). | |||
4.1 of [Part7], for additional details.) | ||||
private | private | |||
The private response directive indicates that the response message | The private response directive indicates that the response message | |||
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 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 header fields. That is, the specified | with the listed response header fields. That is, a shared cache | |||
field-names(s) MUST NOT be stored by a shared cache, whereas the | MUST NOT store the specified field-names(s), whereas it MAY store | |||
remainder of the response message MAY be. | the remainder of the response message. | |||
Note: This usage of the word private only controls where the | Note: This usage of the word private only controls where the | |||
response can be stored; it 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 a cache from using it to satisfy a request without | prevent a cache from using it to satisfy a request without | |||
contacting it, even by caches that have been configured to return | 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 header fields. That is, the specified | with the listed response header fields. That is, a cache MUST NOT | |||
field-name(s) MUST NOT be sent in the response to a subsequent | send the specified field-name(s) in the response to a subsequent | |||
request without successful validation on the origin server. This | request without successful validation on the origin server. This | |||
allows an origin server to prevent the re-use of certain header | allows an origin server to prevent the re-use of certain header | |||
fields in a response, while still allowing caching of the rest of | fields in a response, while still allowing caching of the rest of | |||
the response. | the response. | |||
Note: Most HTTP/1.0 caches will not recognize or obey this | Note: Most HTTP/1.0 caches will not recognize or obey this | |||
directive. Also, no-cache response directives with field-names | directive. Also, no-cache response directives with field-names | |||
are often handled by implementations as if an unqualified no-cache | are often handled by implementations as if an unqualified no-cache | |||
directive was received; i.e., the special handling for the | directive was received; i.e., the special handling for the | |||
qualified form is not widely implemented. | qualified form is not widely implemented. | |||
no-store | 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 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 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 | 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 might 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, a cache MUST NOT use the response to satisfy | |||
requests without successful validation on the origin server. | subsequent 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 a | |||
HTTP/1.1 cache MUST obey the must-revalidate directive; in | cache MUST obey the must-revalidate directive; in particular, if a | |||
particular, if the cache cannot reach the origin server for any | cache cannot reach the origin server for any reason, it MUST | |||
reason, it MUST generate a 504 (Gateway Timeout) response. | generate a 504 (Gateway Timeout) response. | |||
Servers SHOULD send the must-revalidate directive if and only if | A server SHOULD send the must-revalidate directive if and only if | |||
failure to validate a request on the representation could result | failure to validate a request on the representation could result | |||
in 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 private caches. | |||
max-age | max-age | |||
The max-age response directive indicates that response is to be | The max-age response directive indicates that response is to be | |||
considered stale after its age is greater than the specified | considered stale after its age is greater than the specified | |||
number of seconds. | number of seconds. | |||
s-maxage | s-maxage | |||
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 field. The s-maxage directive also implies the semantics | header field. The s-maxage directive also implies the semantics | |||
of the proxy-revalidate response directive. | of the 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 intermediary | |||
cache or proxy MUST NOT change the Content-Encoding, Content-Range | (regardless of whether it implements a cache) MUST NOT change the | |||
or Content-Type response header fields, nor the response | Content-Encoding, Content-Range or Content-Type response header | |||
representation. | fields, 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 23, line 35 | skipping to change at page 24, line 7 | |||
extensions to the cache-control directives can be made without | extensions to the cache-control directives can be made without | |||
requiring changes to the base protocol. | requiring changes to the base protocol. | |||
This extension mechanism depends on an HTTP cache obeying all of the | This extension mechanism depends on an HTTP cache obeying all of the | |||
cache-control directives defined for its native HTTP-version, obeying | cache-control directives defined for its native HTTP-version, obeying | |||
certain extensions, and ignoring all directives that it does not | certain extensions, and ignoring all directives that it does not | |||
understand. | understand. | |||
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. We | "community" that acts as a modifier to the private directive. We | |||
define this new directive to mean that, in addition to any non-shared | define this new directive to mean that, in addition to any private | |||
cache, any cache that is shared only by members of the community | cache, any cache that is shared only by members of the community | |||
named within its value may cache the response. An origin server | named within its value may cache the response. An origin server | |||
wishing to allow the UCI community to use an otherwise private | 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 seeing this header field will act correctly even if the cache | A cache seeing this header field will act correctly even if the cache | |||
does not understand the community cache-extension, since it will also | does not understand the community cache-extension, since it will also | |||
see and understand the private directive and thus default to the safe | see and understand the private directive and thus default to the safe | |||
behavior. | behavior. | |||
Unrecognized cache directives MUST be ignored; it is assumed that any | A cache MUST be ignore unrecognized cache directives; it is assumed | |||
cache directive likely to be unrecognized by an HTTP/1.1 cache will | that any cache directive likely to be unrecognized by an HTTP/1.1 | |||
be combined with standard directives (or the response's default | cache will be combined with standard directives (or the response's | |||
cacheability) such that the cache behavior will remain minimally | default cacheability) such that the cache behavior will remain | |||
correct even if the cache does not understand the extension(s). | minimally correct even if the cache does not understand the | |||
extension(s). | ||||
The HTTP Cache Directive Registry defines the name space for the | The HTTP Cache Directive Registry defines the name space for the | |||
cache directives. | cache directives. | |||
Registrations MUST include the following fields: | A registration MUST include the following fields: | |||
o Cache Directive Name | o Cache Directive Name | |||
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>. | |||
skipping to change at page 24, line 31 | skipping to change at page 25, line 4 | |||
The "Expires" 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]; a sender MUST use the rfc1123-date format. | |||
Expires = "Expires" ":" OWS Expires-v | Expires = "Expires" ":" OWS Expires-v | |||
Expires-v = HTTP-date | Expires-v = HTTP-date | |||
For example | For example | |||
Expires: Thu, 01 Dec 1994 16:00:00 GMT | Expires: Thu, 01 Dec 1994 16:00:00 GMT | |||
Note: If a response includes a Cache-Control field with the max- | Note: If a response includes a Cache-Control field with the max- | |||
age directive (see Section 3.2.2), that directive overrides the | age directive (see Section 3.2.2), that directive overrides the | |||
Expires field. Likewise, the s-maxage directive overrides Expires | Expires field. Likewise, the s-maxage directive overrides Expires | |||
in shared caches. | in shared caches. | |||
HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in | A server SHOULD NOT send Expires dates more than one year in the | |||
the future. | future. | |||
HTTP/1.1 clients and caches MUST treat other invalid date formats, | A cache MUST treat other invalid date formats, especially including | |||
especially including the value "0", as in the past (i.e., "already | the value "0", as in the past (i.e., "already expired"). | |||
expired"). | ||||
3.4. Pragma | 3.4. Pragma | |||
The "Pragma" general-header field is used to include implementation- | The "Pragma" header field is used to include implementation-specific | |||
specific directives that might apply to any recipient along the | directives that might apply to any recipient along the request/ | |||
request/response chain. All pragma directives specify optional | response chain. All pragma directives specify optional behavior from | |||
behavior from the viewpoint of the protocol; however, some systems | the viewpoint of the protocol; however, some systems MAY require that | |||
MAY require that behavior be consistent with the directives. | behavior be consistent with the directives. | |||
Pragma = "Pragma" ":" OWS Pragma-v | Pragma = "Pragma" ":" OWS Pragma-v | |||
Pragma-v = 1#pragma-directive | Pragma-v = 1#pragma-directive | |||
pragma-directive = "no-cache" / extension-pragma | pragma-directive = "no-cache" / extension-pragma | |||
extension-pragma = token [ "=" ( token / quoted-string ) ] | extension-pragma = token [ "=" ( token / quoted-string ) ] | |||
When the no-cache directive is present in a request message, an | When the no-cache directive is present in a request message, a cache | |||
application SHOULD forward the request toward the origin server even | SHOULD forward the request toward the origin server even if it has a | |||
if it has a cached copy of what is being requested. This pragma | stored copy of what is being requested. This pragma directive has | |||
directive has the same semantics as the no-cache response directive | the same semantics as the no-cache response directive (see | |||
(see Section 3.2.2) and is defined here for backward compatibility | Section 3.2.2) and is defined here for backward compatibility with | |||
with HTTP/1.0. Clients SHOULD include both header fields when a no- | HTTP/1.0. A client SHOULD include both header fields when a no-cache | |||
cache request is sent to a server not known to be HTTP/1.1 compliant. | request is sent to a server not known to be HTTP/1.1 compliant. A | |||
HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had | cache SHOULD treat "Pragma: no-cache" as if the client had sent | |||
sent "Cache-Control: no-cache". | "Cache-Control: no-cache". | |||
Note: Because the meaning of "Pragma: no-cache" as a response- | Note: Because the meaning of "Pragma: no-cache" as a header field | |||
header field is not actually specified, it does not provide a | is not actually specified, it does not provide a reliable | |||
reliable replacement for "Cache-Control: no-cache" in a response. | replacement for "Cache-Control: no-cache" in a response. | |||
This mechanism is deprecated; no new Pragma directives will be | This mechanism is deprecated; no new Pragma directives will be | |||
defined in HTTP. | defined in HTTP. | |||
3.5. Vary | 3.5. Vary | |||
The "Vary" response-header field conveys the set of request-header | The "Vary" header field conveys the set of header fields that were | |||
fields that were used to select the representation. | used to select the representation. | |||
Caches use this information, in part, to determine whether a stored | Caches use this information, in part, to determine whether a stored | |||
response can be used to satisfy a given request; see Section 2.7. | response can be used to satisfy a given request; see Section 2.7. | |||
determines, while the response is fresh, whether a cache is permitted | determines, while the response is fresh, whether a cache is permitted | |||
to use the response to reply to a subsequent request without | to use the response to reply to a subsequent request without | |||
validation; see Section 2.7. | validation; see Section 2.7. | |||
In uncacheable or stale responses, the Vary field value advises the | In uncacheable or stale responses, the Vary field value advises the | |||
user agent about the criteria that were used to select the | user agent about the criteria that were used to select the | |||
representation. | representation. | |||
Vary = "Vary" ":" OWS Vary-v | Vary = "Vary" ":" OWS Vary-v | |||
Vary-v = "*" / 1#field-name | Vary-v = "*" / 1#field-name | |||
The set of header fields named by the Vary field value is known as | The set of header fields named by the Vary field value is known as | |||
the selecting request-header fields. | the selecting header fields. | |||
Servers SHOULD include a Vary header field with any cacheable | A server SHOULD include a Vary header field with any cacheable | |||
response that is subject to server-driven negotiation. Doing so | response that is subject to server-driven negotiation. Doing so | |||
allows a cache to properly interpret future requests on that resource | allows a cache to properly interpret future requests on that resource | |||
and informs the user agent about the presence of negotiation on that | and informs the user agent about the presence of negotiation on that | |||
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-header fields (e.g., the network address of | limited to the header fields (e.g., the network address of the | |||
the client), play a role in the selection of the response | client), play a role in the selection of the response representation; | |||
representation; therefore, a cache cannot determine whether this | therefore, a cache cannot determine whether this response is | |||
response is appropriate. The "*" value MUST NOT be generated by a | appropriate. A proxy MUST NOT generate the "*" value. | |||
proxy 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 header | |||
header fields defined by this specification. Field names are case- | 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" header field is used to carry additional information | |||
information about the status or transformation of a message that | about the status or transformation of a message that might not be | |||
might not be reflected in the message. This information is typically | reflected in the message. This information is typically used to warn | |||
used to warn about possible incorrectness introduced by caching | about possible incorrectness introduced by caching operations or | |||
operations or transformations applied to the payload of the message. | transformations applied to the payload of the 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 header fields can in general be applied to any message, | Warning header fields can in general be applied to any message, | |||
however some warn-codes are specific to caches and can only be | however some warn-codes are specific to caches and can only be | |||
applied to response messages. | applied to response messages. | |||
Warning = "Warning" ":" OWS Warning-v | Warning = "Warning" ":" OWS Warning-v | |||
skipping to change at page 27, line 34 | skipping to change at page 27, line 44 | |||
Systems that generate multiple Warning header fields SHOULD order | Systems that generate multiple Warning header fields SHOULD order | |||
them with this user agent behavior in mind. New Warning header | them with this user agent behavior in mind. New Warning header | |||
fields SHOULD be added after any existing Warning headers fields. | fields SHOULD be added after any existing Warning headers fields. | |||
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 a cache after validation. | |||
can only be generated by a cache when validating a cached entry, | They can only be generated by a cache when validating a cached | |||
and MUST NOT be generated in any other situation. | entry, and MUST NOT be generated in any other situation. | |||
o 2xx Warnings describe some aspect of the representation that is | o 2xx Warnings describe some aspect of the representation that is | |||
not rectified by a validation (for example, a lossy compression of | not rectified by a validation (for example, a lossy compression of | |||
the representation) and MUST NOT be deleted by caches after | the representation) and MUST NOT be deleted by a cache after | |||
validation, unless a full response is returned, in which case they | validation, unless a full response is returned, in which case they | |||
MUST be. | MUST be. | |||
If an implementation sends a message with one or more Warning header | If an implementation sends a message with one or more Warning header | |||
fields to a receiver whose version is HTTP/1.0 or lower, then the | fields 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 | sender MUST include in each warning-value a warn-date that matches | |||
the Date header field in the message. | the Date header field in the message. | |||
If an implementation receives a message with a warning-value that | If a system receives a message with a warning-value that includes a | |||
includes a warn-date, and that warn-date is different from the Date | warn-date, and that warn-date is different from the Date value in the | |||
value in the response, then that warning-value MUST be deleted from | response, then that warning-value MUST be deleted from the message | |||
the message before storing, forwarding, or using it. (preventing the | before storing, forwarding, or using it. (preventing the consequences | |||
consequences of naive caching of Warning header fields.) If all of | of naive caching of Warning header fields.) If all of the warning- | |||
the warning-values are deleted for this reason, the Warning header | values are deleted for this reason, the Warning header field MUST be | |||
field MUST be deleted as well. | deleted as well. | |||
The following warn-codes are defined by this specification, each with | The following warn-codes are defined by this specification, each with | |||
a recommended warn-text in English, and a description of its meaning. | a recommended warn-text in English, and a description of its meaning. | |||
110 Response is stale | 110 Response is stale | |||
SHOULD be included whenever the returned response is stale. | A cache SHOULD include this whenever the returned response is | |||
stale. | ||||
111 Revalidation failed | 111 Revalidation failed | |||
SHOULD be included if a cache returns a stale response because an | A cache SHOULD include this when returning a stale response | |||
attempt to validate the response failed, due to an inability to | because an attempt to validate the response failed, due to an | |||
reach the server. | inability to reach the server. | |||
112 Disconnected operation | 112 Disconnected operation | |||
SHOULD be included if the cache is intentionally disconnected from | A cache SHOULD b include this if it is intentionally disconnected | |||
the rest of the network for a period of time. | from the rest of the network for a period of time. | |||
113 Heuristic expiration | 113 Heuristic expiration | |||
SHOULD be included if the cache heuristically chose a freshness | A cache SHOULD include this if it heuristically chose a freshness | |||
lifetime greater than 24 hours and the response's age is greater | lifetime greater than 24 hours and the response's age is greater | |||
than 24 hours. | than 24 hours. | |||
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 proxy if it applies any | MUST be added by a proxy if it applies any transformation to the | |||
transformation to the representation, such as changing the | representation, such as changing the content-coding, media-type, | |||
content-coding, media-type, or modifying the representation data, | or modifying the representation data, unless this Warning code | |||
unless this Warning code already appears in the response. | 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 | |||
skipping to change at page 30, line 48 | skipping to change at page 31, line 18 | |||
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-12 | and Message Parsing", draft-ietf-httpbis-p1-messaging-13 | |||
(work in progress), October 2010. | (work in progress), March 2011. | |||
[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-12 (work in | Semantics", draft-ietf-httpbis-p2-semantics-13 (work in | |||
progress), October 2010. | progress), March 2011. | |||
[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-12 (work in | Requests", draft-ietf-httpbis-p4-conditional-13 (work in | |||
progress), October 2010. | progress), March 2011. | |||
[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-12 (work | Partial Responses", draft-ietf-httpbis-p5-range-13 (work | |||
in progress), October 2010. | in progress), March 2011. | |||
[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-12 (work in progress), | draft-ietf-httpbis-p7-auth-13 (work in progress), | |||
October 2010. | March 2011. | |||
[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 36, line 26 | skipping to change at page 36, line 41 | |||
C.8. Since draft-ietf-httpbis-p6-cache-06 | C.8. Since draft-ietf-httpbis-p6-cache-06 | |||
Closed issues: | Closed issues: | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/161>: "base for | o <http://tools.ietf.org/wg/httpbis/trac/ticket/161>: "base for | |||
numeric protocol elements" | numeric protocol elements" | |||
Affected issues: | Affected issues: | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/37>: WVary and non- | o <http://tools.ietf.org/wg/httpbis/trac/ticket/37>: "Vary and non- | |||
existant headers" | existant headers" | |||
C.9. Since draft-ietf-httpbis-p6-cache-07 | C.9. Since draft-ietf-httpbis-p6-cache-07 | |||
Closed issues: | Closed issues: | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/54>: "Definition of | o <http://tools.ietf.org/wg/httpbis/trac/ticket/54>: "Definition of | |||
1xx Warn-Codes" | 1xx Warn-Codes" | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/167>: "Content- | o <http://tools.ietf.org/wg/httpbis/trac/ticket/167>: "Content- | |||
skipping to change at page 38, line 20 | skipping to change at page 38, line 33 | |||
o Clean up TODOs and prose in "Combining Responses." | o Clean up TODOs and prose in "Combining Responses." | |||
C.13. Since draft-ietf-httpbis-p6-cache-11 | C.13. Since draft-ietf-httpbis-p6-cache-11 | |||
Closed issues: | Closed issues: | |||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/204>: "Text about | o <http://tools.ietf.org/wg/httpbis/trac/ticket/204>: "Text about | |||
clock requirement for caches belongs in p6" | clock requirement for caches belongs in p6" | |||
C.14. Since draft-ietf-httpbis-p6-cache-12 | ||||
Closed issues: | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/224>: "Header | ||||
Classification" | ||||
o <http://tools.ietf.org/wg/httpbis/trac/ticket/268>: "Clarify | ||||
'public'" | ||||
Index | Index | |||
A | A | |||
age 6 | age 6 | |||
Age header 17 | Age header field 18 | |||
C | C | |||
cache 5 | cache 5 | |||
Cache Directives | Cache Directives | |||
max-age 19, 22 | max-age 20, 23 | |||
max-stale 19 | max-stale 20 | |||
min-fresh 20 | min-fresh 20 | |||
must-revalidate 22 | must-revalidate 22 | |||
no-cache 19, 21 | no-cache 19, 21 | |||
no-store 19, 21 | no-store 19, 22 | |||
no-transform 20, 23 | no-transform 20, 23 | |||
only-if-cached 20 | only-if-cached 20 | |||
private 21 | private 21 | |||
proxy-revalidate 22 | proxy-revalidate 23 | |||
public 20 | public 21 | |||
s-maxage 22 | s-maxage 23 | |||
Cache-Control header 18 | Cache-Control header field 18 | |||
cacheable 5 | cacheable 5 | |||
E | E | |||
Expires header 24 | Expires header field 24 | |||
explicit expiration time 5 | explicit expiration time 6 | |||
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 18 | |||
Age-v 18 | Age-v 18 | |||
Cache-Control 18 | Cache-Control 19 | |||
Cache-Control-v 18 | Cache-Control-v 19 | |||
cache-extension 18 | cache-extension 19 | |||
cache-request-directive 19 | cache-request-directive 19 | |||
cache-response-directive 20 | cache-response-directive 21 | |||
delta-seconds 18 | delta-seconds 18 | |||
Expires 24 | Expires 25 | |||
Expires-v 24 | Expires-v 25 | |||
extension-pragma 25 | extension-pragma 25 | |||
Pragma 25 | Pragma 25 | |||
pragma-directive 25 | pragma-directive 25 | |||
Pragma-v 25 | Pragma-v 25 | |||
Vary 25 | Vary 26 | |||
Vary-v 25 | Vary-v 26 | |||
warn-agent 27 | warn-agent 27 | |||
warn-code 27 | warn-code 27 | |||
warn-date 27 | warn-date 27 | |||
warn-text 27 | warn-text 27 | |||
Warning 27 | Warning 27 | |||
Warning-v 27 | Warning-v 27 | |||
warning-value 27 | warning-value 27 | |||
H | H | |||
Headers | Header Fields | |||
Age 17 | Age 18 | |||
Cache-Control 18 | Cache-Control 18 | |||
Expires 24 | Expires 24 | |||
Pragma 25 | Pragma 25 | |||
Vary 25 | Vary 26 | |||
Warning 26 | Warning 26 | |||
heuristic expiration time 5 | heuristic expiration time 6 | |||
M | M | |||
max-age | max-age | |||
Cache Directive 19, 22 | Cache Directive 20, 23 | |||
max-stale | max-stale | |||
Cache Directive 19 | Cache Directive 20 | |||
min-fresh | min-fresh | |||
Cache Directive 20 | Cache Directive 20 | |||
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, 21 | Cache Directive 19, 22 | |||
no-transform | no-transform | |||
Cache Directive 20, 23 | Cache Directive 20, 23 | |||
O | O | |||
only-if-cached | only-if-cached | |||
Cache Directive 20 | Cache Directive 20 | |||
P | P | |||
Pragma header 25 | Pragma header field 25 | |||
private | private | |||
Cache Directive 21 | Cache Directive 21 | |||
private cache 5 | ||||
proxy-revalidate | proxy-revalidate | |||
Cache Directive 22 | Cache Directive 23 | |||
public | public | |||
Cache Directive 20 | Cache Directive 21 | |||
S | S | |||
s-maxage | s-maxage | |||
Cache Directive 22 | Cache Directive 23 | |||
shared cache 5 | ||||
stale 6 | stale 6 | |||
V | V | |||
validator 6 | validator 6 | |||
Vary header 25 | Vary header field 26 | |||
W | W | |||
Warning header 26 | Warning header field 26 | |||
Authors' Addresses | Authors' Addresses | |||
Roy T. Fielding (editor) | Roy T. Fielding (editor) | |||
Day Software | Adobe Systems Incorporated | |||
23 Corporate Plaza DR, Suite 280 | 345 Park Ave | |||
Newport Beach, CA 92660 | San Jose, CA 95110 | |||
USA | USA | |||
Phone: +1-949-706-5300 | ||||
Fax: +1-949-706-5305 | ||||
EMail: fielding@gbiv.com | EMail: fielding@gbiv.com | |||
URI: http://roy.gbiv.com/ | URI: http://roy.gbiv.com/ | |||
Jim Gettys | Jim Gettys | |||
Alcatel-Lucent Bell Labs | Alcatel-Lucent Bell Labs | |||
21 Oak Knoll Road | 21 Oak Knoll Road | |||
Carlisle, MA 01741 | Carlisle, MA 01741 | |||
USA | USA | |||
EMail: jg@freedesktop.org | EMail: jg@freedesktop.org | |||
URI: http://gettys.wordpress.com/ | URI: http://gettys.wordpress.com/ | |||
Jeffrey C. Mogul | Jeffrey C. Mogul | |||
skipping to change at page 41, line 29 | skipping to change at page 42, line 4 | |||
EMail: JeffMogul@acm.org | EMail: JeffMogul@acm.org | |||
Henrik Frystyk Nielsen | Henrik Frystyk Nielsen | |||
Microsoft Corporation | Microsoft Corporation | |||
1 Microsoft Way | 1 Microsoft Way | |||
Redmond, WA 98052 | Redmond, WA 98052 | |||
USA | USA | |||
EMail: henrikn@microsoft.com | EMail: henrikn@microsoft.com | |||
Larry Masinter | Larry Masinter | |||
Adobe Systems, Incorporated | Adobe Systems Incorporated | |||
345 Park Ave | 345 Park Ave | |||
San Jose, CA 95110 | San Jose, CA 95110 | |||
USA | USA | |||
EMail: LMM@acm.org | EMail: LMM@acm.org | |||
URI: http://larry.masinter.net/ | URI: http://larry.masinter.net/ | |||
Paul J. Leach | Paul J. Leach | |||
Microsoft Corporation | Microsoft Corporation | |||
1 Microsoft Way | 1 Microsoft Way | |||
End of changes. 137 change blocks. | ||||
296 lines changed or deleted | 318 lines changed or added | |||
This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |