draft-ietf-httpbis-p6-cache-11.txt   draft-ietf-httpbis-p6-cache-12.txt 
HTTPbis Working Group R. Fielding, Ed. HTTPbis Working Group R. Fielding, Ed.
Internet-Draft Day Software Internet-Draft Day Software
Obsoletes: 2616 (if approved) J. Gettys Obsoletes: 2616 (if approved) J. Gettys
Intended status: Standards Track Alcatel-Lucent Intended status: Standards Track Alcatel-Lucent
Expires: February 5, 2011 J. Mogul Expires: April 28, 2011 J. Mogul
HP HP
H. Frystyk H. Frystyk
Microsoft Microsoft
L. Masinter L. Masinter
Adobe Systems Adobe Systems
P. Leach P. Leach
Microsoft Microsoft
T. Berners-Lee T. Berners-Lee
W3C/MIT W3C/MIT
Y. Lafon, Ed. Y. Lafon, Ed.
W3C W3C
M. Nottingham, Ed. M. Nottingham, Ed.
J. Reschke, Ed. J. Reschke, Ed.
greenbytes greenbytes
August 4, 2010 October 25, 2010
HTTP/1.1, part 6: Caching HTTP/1.1, part 6: Caching
draft-ietf-httpbis-p6-cache-11 draft-ietf-httpbis-p6-cache-12
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.12. The changes in this draft are summarized in Appendix C.13.
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 February 5, 2011. This Internet-Draft will expire on April 28, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 17 skipping to change at page 3, line 17
Specification . . . . . . . . . . . . . . . . . . . . 7 Specification . . . . . . . . . . . . . . . . . . . . 7
2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7
2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7
2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8
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 . . . . . . . . . . . . . 14 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 . . . . . . . . . . . . . . . . . . . 16 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17
3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17
3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18
3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19
3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20
3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23
3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24
3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26
4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 28 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29
5.2. Header Field Registration . . . . . . . . . . . . . . . . 29 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30
6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30
7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30
8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30
8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 8.1. Normative References . . . . . . . . . . . . . . . . . . . 30
8.2. Informative References . . . . . . . . . . . . . . . . . . 31 8.2. Informative References . . . . . . . . . . . . . . . . . . 31
Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 31 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32
Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 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) . . . . . . . . . . . . . . . . . . . . 33
C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34
C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 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 . . . . . . . . . . . 34
C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35
C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35
C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 34 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 . . . . . . . . . . . 35
C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36
C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 35 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 . . . . . . . . . . . 36
C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 36 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 . . . . . . . . . . . 37
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 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 8, line 8 skipping to change at page 8, line 8
2.1. Response Cacheability 2.1. Response Cacheability
A cache MUST NOT store a response to any request, unless: A cache MUST NOT store a response to any request, unless:
o The request method is understood by the cache and defined as being o The request method is understood by the cache and defined as being
cacheable, and cacheable, and
o the response status code is understood by the cache, and o the response status code is understood by the cache, and
o the "no-store" cache directive (see Section 3.2) does not appear o the "no-store" cache directive (see Section 3.2) does not appear
in request or response headers, and in request or response header fields, and
o the "private" cache response directive (see Section 3.2.2 does not o the "private" cache response directive (see Section 3.2.2 does not
appear in the response, if the cache is shared, and appear in the response, if the cache is shared, and
o the "Authorization" header (see Section 3.1 of [Part7]) does not o the "Authorization" header field (see Section 4.1 of [Part7]) does
appear in the request, if the cache is shared, unless the response not appear in the request, if the cache is shared, unless the
explicitly allows it (see Section 2.6), and response explicitly allows it (see Section 2.6), and
o the response either: o the response either:
* contains an Expires header (see Section 3.3), or * contains an Expires header field (see Section 3.3), or
* contains a max-age response cache directive (see * contains a max-age response cache directive (see
Section 3.2.2), or Section 3.2.2), or
* contains a s-maxage response cache directive and the cache is * contains a s-maxage response cache directive and the cache is
shared, or shared, or
* contains a Cache Control Extension (see Section 3.2.3) that * contains a Cache Control Extension (see Section 3.2.3) that
allows it to be cached, or allows it to be cached, or
skipping to change at page 8, line 47 skipping to change at page 8, line 47
content (see Section 2.1.1). content (see Section 2.1.1).
Note that in normal operation, most caches will not store a response Note that in normal operation, most caches will not store a response
that has neither a cache validator nor an explicit expiration time, that has neither a cache validator nor an explicit expiration time,
as such responses are not usually useful to store. However, caches as such responses are not usually useful to store. However, caches
are not prohibited from storing such responses. are not prohibited from storing such responses.
2.1.1. Storing Partial and Incomplete Responses 2.1.1. Storing Partial and Incomplete Responses
A cache that receives an incomplete response (for example, with fewer A cache that receives an incomplete response (for example, with fewer
bytes of data than specified in a Content-Length header) can store bytes of data than specified in a Content-Length header field) can
the response, but MUST treat it as a partial response [Part5]. store the response, but MUST treat it as a partial response [Part5].
Partial responses can be combined as described in Section 4 of Partial responses can be combined as described in Section 4 of
[Part5]; the result might be a full response or might still be [Part5]; the result might be a full response or might still be
partial. A cache MUST NOT return a partial response to a client partial. A cache MUST NOT return a partial response to a client
without explicitly marking it as such using the 206 (Partial Content) without explicitly marking it as such using the 206 (Partial Content)
status code. status code.
A cache that does not support the Range and Content-Range headers A cache that does not support the Range and Content-Range header
MUST NOT store incomplete or partial responses. fields MUST NOT store incomplete or partial responses.
2.2. Constructing Responses from Caches 2.2. Constructing Responses from Caches
For a presented request, a cache MUST NOT return a stored response, For a presented request, a cache MUST NOT return a stored response,
unless: unless:
o The presented effective request URI (Section 4.3 of [Part1]) and o The presented effective request URI (Section 4.3 of [Part1]) and
that of the stored response match, and that of the stored response match, and
o the request method associated with the stored response allows it o the request method associated with the stored response allows it
to be used for the presented request, and to be used for the presented request, and
o selecting request-headers nominated by the stored response (if o selecting request-header fields nominated by the stored response
any) match those presented (see Section 2.7), and (if any) match those presented (see Section 2.7), and
o the presented request and stored response are free from directives o the presented request and stored response are free from directives
that would prevent its use (see Section 3.2 and Section 3.4), and that would prevent its use (see Section 3.2 and Section 3.4), and
o the stored response is either: o the stored response is either:
* fresh (see Section 2.3), or * fresh (see Section 2.3), or
* allowed to be served stale (see Section 2.3.3), or * allowed to be served stale (see Section 2.3.3), or
skipping to change at page 9, line 48 skipping to change at page 9, line 48
Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST
be written through the cache to the origin server; i.e., a cache must be written through the cache to the origin server; i.e., a cache must
not reply to such a request before having forwarded the request and not reply to such a request before having forwarded the request and
having received a corresponding response. having received a corresponding response.
Also, note that unsafe requests might invalidate already stored Also, note that unsafe requests might invalidate already stored
responses; see Section 2.5. responses; see Section 2.5.
Caches MUST use the most recent response (as determined by the Date Caches MUST use the most recent response (as determined by the Date
header) when more than one suitable response is stored. They can header field) when more than one suitable response is stored. They
also forward a request with "Cache-Control: max-age=0" or "Cache- can 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
without revalidating them on every use. An HTTP cache, especially a
shared cache, SHOULD use a mechanism, such as NTP [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 (Section 3.3) or the max-age response cache either the Expires header field (Section 3.3) or the max-age response
directive (Section 3.2.2). Generally, origin servers will assign cache directive (Section 3.2.2). Generally, origin servers will
future explicit expiration times to responses in the belief that the assign future explicit expiration times to responses in the belief
representation is not likely to change in a semantically significant that the representation is not likely to change in a semantically
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 validate the cached response before reusing it for subsequent
requests. requests.
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 HTTP caches MAY assign heuristic expiration times when explicit times
are not specified, employing algorithms that use other header values are not specified, employing algorithms that use other heade field
(such as the Last-Modified time) to estimate a plausible expiration values (such as the Last-Modified time) to estimate a plausible
time. The HTTP/1.1 specification does not provide specific expiration time. The HTTP/1.1 specification does not provide
algorithms, but does impose worst-case constraints on their results. specific algorithms, but does impose worst-case constraints on their
results.
The calculation to determine if a response is fresh is: The calculation to determine if a response is fresh is:
response_is_fresh = (freshness_lifetime > current_age) response_is_fresh = (freshness_lifetime > current_age)
The freshness_lifetime is defined in Section 2.3.1; the current_age The freshness_lifetime is defined in Section 2.3.1; the current_age
is defined in Section 2.3.2. is defined in Section 2.3.2.
Additionally, clients 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 16 skipping to change at page 11, line 20
A cache can calculate the freshness lifetime (denoted as A cache can calculate the freshness lifetime (denoted as
freshness_lifetime) of a response by using the first match of: freshness_lifetime) of a response by using the first match of:
o If the cache is shared and the s-maxage response cache directive o If the cache is shared and the s-maxage response cache directive
(Section 3.2.2) is present, use its value, or (Section 3.2.2) is present, use its value, or
o If the max-age response cache directive (Section 3.2.2) is o If the max-age response cache directive (Section 3.2.2) is
present, use its value, or present, use its value, or
o If the Expires response header (Section 3.3) is present, use its o If the Expires response header field (Section 3.3) is present, use
value minus the value of the Date response header, or its value minus the value of the Date response header field, or
o Otherwise, no explicit expiration time is present in the response. o Otherwise, no explicit expiration time is present in the response.
A heuristic freshness lifetime might be applicable; see A heuristic freshness lifetime might be applicable; see
Section 2.3.1.1. Section 2.3.1.1.
Note that this calculation is not vulnerable to clock skew, since all Note that this calculation is not vulnerable to clock skew, since all
of the information comes from the origin server. of the information comes from the origin server.
2.3.1.1. Calculating Heuristic Freshness 2.3.1.1. Calculating Heuristic Freshness
If no explicit expiration time is present in a stored response that If no explicit expiration time is present in a stored response that
has a status code 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 heuristic expiration time MAY be calculated.
Heuristics MUST NOT be used for response status codes that do not Heuristics MUST NOT be used for response status codes that do not
explicitly allow it. explicitly allow it.
When a heuristic is used to calculate freshness lifetime, the cache When a heuristic is used to calculate freshness lifetime, the cache
SHOULD attach a Warning header with a 113 warn-code to the response SHOULD attach a Warning header field with a 113 warn-code to the
if its current_age is more than 24 hours and such a warning is not response if its current_age is more than 24 hours and such a warning
already present. is not already present.
Also, if the response has a Last-Modified header (Section 6.6 of Also, if the response has a Last-Modified header field (Section 6.6
[Part4]), the heuristic expiration value SHOULD be no more than some of [Part4]), the heuristic expiration value SHOULD be no more than
fraction of the interval since that time. A typical setting of this some fraction of the interval since that time. A typical setting of
fraction might be 10%. 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 URLs 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 to convey the estimated age of HTTP/1.1 uses the Age response-header field to convey the estimated
the response message when obtained from a cache. The Age field value age of the response message when obtained from a cache. The Age
is the cache's estimate of the amount of time since the response was field value is the cache's estimate of the amount of time since the
generated or validated by the origin server. In essence, the Age response was generated or validated by the origin server. In
value is the sum of the time that the response has been resident in essence, the Age value is the sum of the time that the response has
each of the caches along the path from the origin server, plus the been resident in each of the caches along the path from the origin
amount of time it has been in transit along network paths. server, plus the amount of time it has been in transit along network
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 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
HTTP/1.1 requires origin servers to send a Date header, if HTTP/1.1 requires origin servers to send a Date header field, if
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, 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, and for requirements regarding responses without a Date header field, and for requirements regarding responses
Date response header. 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". Hosts that use HTTP, but especially
hosts running origin servers and caches, SHOULD use NTP hosts running origin servers and caches, SHOULD use NTP
([RFC1305]) or some similar protocol to synchronize their clocks ([RFC1305]) or some similar protocol to synchronize their clocks
to a globally accurate time standard. to a globally accurate time standard.
request_time request_time
skipping to change at page 13, line 48 skipping to change at page 14, line 7
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 Caches SHOULD NOT return stale responses unless they are 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 with the 110 warn-code Stale responses SHOULD have a Warning header field with the 110 warn-
(see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on code (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent
stale responses if the cache is disconnected. on 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 headers). A new Warning (but without removing any existing Warning header
cache SHOULD NOT attempt to validate a response simply because that fields). A cache SHOULD NOT attempt to validate a response simply
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, the cache SHOULD add an If-
Modified-Since header whose value is that of the Last-Modified header Modified-Since header field whose value is that of the Last-Modified
from the selected (see Section 2.7) stored response, if available. header field from the selected (see Section 2.7) stored response, if
available.
Additionally, the cache SHOULD add an If-None-Match header whose Additionally, the cache SHOULD add an If-None-Match header field
value is that of the ETag header(s) from all responses stored for the whose value is that of the ETag header field(s) from all responses
requested URI, if present. However, if any of the stored responses stored for the requested URI, if present. However, if any of the
contains only partial content, its entity-tag SHOULD NOT be included stored responses contains only partial content, its entity-tag SHOULD
in the If-None-Match header field unless the request is for a range NOT be included in the If-None-Match header field unless the request
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, the full response SHOULD be used to satisfy the
request and MAY replace the stored response. 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
skipping to change at page 15, line 7 skipping to change at page 15, line 14
case, it MAY return a previously stored response (see Section 2.3.3). case, it MAY return a previously stored response (see Section 2.3.3).
2.5. Request Methods that Invalidate 2.5. Request Methods that Invalidate
Because unsafe methods (Section 7.1.1 of [Part2]) have the potential Because unsafe methods (Section 7.1.1 of [Part2]) have the potential
for changing state on the origin server, intervening caches can use for changing state on the origin server, intervening caches can use
them to keep their contents up-to-date. them to keep their contents up-to-date.
The following HTTP methods MUST cause a cache to invalidate the The following HTTP methods MUST cause a cache to invalidate the
effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) effective Request URI (Section 4.3 of [Part1]) as well as the URI(s)
in the Location and Content-Location headers (if present): in the Location and Content-Location header fields (if present):
o PUT o PUT
o DELETE o DELETE
o POST o POST
An invalidation based on a URI from a Location or Content-Location An invalidation based on a URI from a Location or Content-Location
header MUST NOT be performed if the host part of that URI differs header field MUST NOT be performed if the host part of that URI
from the host part in the effective request URI (Section 4.3 of differs from the host part in the effective request URI (Section 4.3
[Part1]). This helps prevent denial of service attacks. of [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 for methods it does not
understand SHOULD invalidate the effective request URI (Section 4.3 understand SHOULD invalidate the effective request URI (Section 4.3
of [Part1]). of [Part1]).
Here, "invalidate" means that the cache will either remove all stored Here, "invalidate" means that the cache will either remove all stored
responses related to the effective request URI, or will mark these as responses related to the effective request URI, or will mark these as
"invalid" and in need of a mandatory validation before they can be "invalid" and in need of a mandatory validation before they can be
returned in response to a subsequent request. returned in response to a subsequent request.
Note that this does not guarantee that all appropriate responses are Note that this does not guarantee that all appropriate responses are
invalidated. For example, the request that caused the change at the invalidated. For example, the request that caused the change at the
origin server might not have gone through the cache where a response origin server might not have gone through the cache where a response
is stored. is stored.
2.6. Shared Caching of Authenticated Responses 2.6. Shared Caching of Authenticated Responses
Shared caches MUST NOT use a cached response to a request with an Shared caches MUST NOT use a cached response to a request with an
Authorization header (Section 3.1 of [Part7]) to satisfy any Authorization header 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-headers nominated that response unless all of the selecting request-header fields
by the Vary header match in both the original request (i.e., that nominated by the Vary header field match in both the original request
associated with the stored response), and the presented request. (i.e., that associated with the stored response), and the presented
request.
The selecting request-headers from two requests are defined to match The selecting request-header fields from two requests are defined to
if and only if those in the first request can be transformed to those match if and only if those in the first request can be transformed to
in the second request by applying any of the following: those in the second request by applying any of the following:
o adding or removing whitespace, where allowed in the header'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 message-header fields with the same field name
(see Section 3.2 of [Part1]) (see Section 3.2 of [Part1])
o normalizing both header values in a way that is known to have o normalizing both header field values in a way that is known to
identical semantics, according to the header's specification have identical semantics, according to the header field's
(e.g., re-ordering field values when order is not significant; specification (e.g., re-ordering field values when order is not
case-normalization, where values are defined to be case- significant; case-normalization, where values are defined to be
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-headers is known The stored response with matching selecting request-header fields is
as the selected response. known as the selected response.
If no selected response is available, the cache MAY forward the If no selected response is available, the cache MAY forward the
presented request to the origin server in a conditional request; see presented request to the origin server in a conditional request; see
Section 2.4. Section 2.4.
2.8. Combining Responses 2.8. Combining Responses
When a cache receives a 304 (Not Modified) response or a 206 (Partial When a cache receives a 304 (Not Modified) response or a 206 (Partial
Content) response (in this section, the "new" response"), it needs to Content) response (in this section, the "new" response"), it needs to
created an updated response by combining the stored response with the created an updated response by combining the stored response with the
skipping to change at page 17, line 13 skipping to change at page 17, line 23
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 If the new response's status code is 206 (partial content), both the
stored and new responses MUST have validators, and those validators stored and new responses MUST have validators, and those validators
MUST match using the strong comparison function (see Section 4 of MUST match using the strong comparison function (see Section 4 of
[Part4]). Otherwise, the responses MUST NOT be combined. [Part4]). Otherwise, the responses MUST NOT be combined.
The stored response headers are used as those of the updated The stored response header fields are used as those of the updated
response, except that response, except that
o any stored Warning headers with warn-code 1xx (see Section 3.6) o any stored Warning header fields with warn-code 1xx (see
MUST be deleted. Section 3.6) MUST be deleted.
o any stored Warning headers with warn-code 2xx MUST be retained. o any stored Warning header fields with warn-code 2xx MUST be
retained.
o any other headers provided in the new response MUST replace all o any other header fields provided in the new response MUST replace
instances of the corresponding headers from the stored response. all instances of the corresponding header fields from the stored
response.
The updated response headers MUST be used to replace those of the The updated response header fields MUST be used to replace those of
stored response in cache (unless the stored response is removed from the stored response in cache (unless the stored response is removed
cache). In the case of a 206 response, the combined representation from cache). In the case of a 206 response, the combined
MAY be stored. representation MAY be stored.
3. Header Field Definitions 3. Header Field Definitions
This section defines the syntax and semantics of HTTP/1.1 header This section defines the syntax and semantics of HTTP/1.1 header
fields related to caching. fields related to caching.
3.1. Age 3.1. Age
The "Age" response-header field conveys the sender's estimate of the The "Age" response-header field conveys the sender's estimate of the
amount of time since the response was generated or successfully amount of time since the response was generated or successfully
skipping to change at page 17, line 51 skipping to change at page 18, line 15
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 with a field-value of 2147483648 (2^31). 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
Caches SHOULD use an arithmetic type of at least 31 bits of range. 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" general-header field is used to specify
directives for caches along the request/response chain. Such cache directives for caches along the request/response chain. Such cache
directives are unidirectional in that the presence of a directive in directives are unidirectional in that the presence of a directive in
skipping to change at page 20, line 9 skipping to change at page 20, line 18
The min-fresh request directive indicates that the client is The min-fresh request directive indicates that the client is
willing to accept a response whose freshness lifetime is no less willing to accept a response whose freshness lifetime is no less
than its current age plus the specified time in seconds. That is, than its current age plus the specified time in seconds. That is,
the client wants a response that will still be fresh for at least the client wants a response that will still be fresh for at least
the specified number of seconds. the specified number of seconds.
no-transform no-transform
The no-transform request directive indicates that an intermediate The no-transform request directive indicates that an intermediate
cache or proxy MUST NOT change the Content-Encoding, Content-Range cache or proxy MUST NOT change the Content-Encoding, Content-Range
or Content-Type request headers, nor the request representation. or Content-Type request header 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, such a request MAY be forwarded within that group of
skipping to change at page 20, line 41 skipping to change at page 20, line 51
/ "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 the response MAY be
cached, even if it would normally be non-cacheable or cacheable cached, even if it would normally be non-cacheable or cacheable
only within a non-shared cache. (See also Authorization, Section only within a non-shared cache. (See also Authorization, Section
3.1 of [Part7], for additional details.) 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 (non-shared) cache MAY store the response.
If the private response directive specifies one or more field- If the private response directive specifies one or more field-
names, this requirement is limited to the field-values associated names, this requirement is limited to the field-values associated
with the listed response headers. That is, the specified field- with the listed response header fields. That is, the specified
names(s) MUST NOT be stored by a shared cache, whereas the field-names(s) MUST NOT be stored by a shared cache, whereas the
remainder of the response message MAY be. remainder of the response message MAY be.
Note: This usage of the word private only controls where the Note: This usage of the word private only controls where the
response 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 headers. That is, the specified field- with the listed response header fields. That is, the specified
name(s) MUST NOT be sent in the response to a subsequent request field-name(s) MUST NOT be sent in the response to a subsequent
without successful validation on the origin server. This allows request without successful validation on the origin server. This
an origin server to prevent the re-use of certain header fields in allows an origin server to prevent the re-use of certain header
a response, while still allowing caching of the rest of the fields in a response, while still allowing caching of the rest of
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
skipping to change at page 22, line 39 skipping to change at page 22, line 48
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. The s-maxage directive also implies the semantics of the header field. The s-maxage directive also implies the semantics
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 intermediate
cache or proxy MUST NOT change the Content-Encoding, Content-Range cache or proxy MUST NOT change the Content-Encoding, Content-Range
or Content-Type response headers, nor the response representation. or Content-Type response header 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 25, line 41 skipping to change at page 26, line 6
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-headers. the selecting request-header fields.
Servers SHOULD include a Vary header field with any cacheable Servers 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-headers (e.g., the network address of the limited to the request-header fields (e.g., the network address of
client), play a role in the selection of the response representation; the client), play a role in the selection of the response
therefore, a cache cannot determine whether this response is representation; therefore, a cache cannot determine whether this
appropriate. The "*" value MUST NOT be generated by a proxy server. response is appropriate. The "*" value MUST NOT be generated by a
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 request-
header fields defined by this specification. Field names are case- header fields defined by this specification. Field names are case-
insensitive. insensitive.
3.6. Warning 3.6. Warning
The "Warning" general-header field is used to carry additional The "Warning" general-header field is used to carry additional
information about the status or transformation of a message that information about the status or transformation of a message that
might not be reflected in the message. This information is typically might not be reflected in the message. This information is typically
used to warn about possible incorrectness introduced by caching used to warn about possible incorrectness introduced by caching
operations or transformations applied to the payload of the message. operations or 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 headers can in general be applied to any message, however Warning header fields can in general be applied to any message,
some warn-codes are specific to caches and can only be applied to however some warn-codes are specific to caches and can only be
response messages. applied to response messages.
Warning = "Warning" ":" OWS Warning-v Warning = "Warning" ":" OWS Warning-v
Warning-v = 1#warning-value Warning-v = 1#warning-value
warning-value = warn-code SP warn-agent SP warn-text warning-value = warn-code SP warn-agent SP warn-text
[SP warn-date] [SP warn-date]
warn-code = 3DIGIT warn-code = 3DIGIT
warn-agent = ( uri-host [ ":" port ] ) / pseudonym warn-agent = ( uri-host [ ":" port ] ) / pseudonym
; the name or pseudonym of the server adding ; the name or pseudonym of the server adding
; the Warning header, for use in debugging ; the Warning header field, for use in debugging
warn-text = quoted-string warn-text = quoted-string
warn-date = DQUOTE HTTP-date DQUOTE warn-date = DQUOTE HTTP-date DQUOTE
Multiple warnings can be attached to a response (either by the origin Multiple warnings can be attached to a response (either by the origin
server or by a cache), including multiple warnings with the same code server or by a cache), including multiple warnings with the same code
number, only differing in warn-text. number, only differing in warn-text.
When this occurs, the user agent SHOULD inform the user of as many of When this occurs, the user agent SHOULD inform the user of as many of
them as possible, in the order that they appear in the response. them as possible, in the order that they appear in the response.
Systems that generate multiple Warning headers SHOULD order them with Systems that generate multiple Warning header fields SHOULD order
this user agent behavior in mind. New Warning headers SHOULD be them with this user agent behavior in mind. New Warning header
added after any existing Warning headers. 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 caches after validation. They
can only be generated by a cache when validating a cached entry, can only be generated by a cache when validating a cached entry,
and MUST NOT be generated in any other situation. and MUST NOT be generated in any other situation.
o 2xx Warnings describe some aspect of the 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 caches 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 headers If an implementation sends a message with one or more Warning header
to a receiver whose version is HTTP/1.0 or lower, then the sender fields to a receiver whose version is HTTP/1.0 or lower, then the
MUST include in each warning-value a warn-date that matches the Date sender MUST include in each warning-value a warn-date that matches
header in the message. the Date header field in the message.
If an implementation receives a message with a warning-value that If an implementation receives a message with a warning-value that
includes a warn-date, and that warn-date is different from the Date includes a warn-date, and that warn-date is different from the Date
value in the response, then that warning-value MUST be deleted from value in the response, then that warning-value MUST be deleted from
the message before storing, forwarding, or using it. (preventing the the message before storing, forwarding, or using it. (preventing the
consequences of naive caching of Warning header fields.) If all of consequences of naive caching of Warning header fields.) If all of
the warning-values are deleted for this reason, the Warning header the warning-values are deleted for this reason, the Warning header
MUST be deleted as well. field MUST be 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. SHOULD be included whenever the returned response is stale.
111 Revalidation failed 111 Revalidation failed
skipping to change at page 30, line 21 skipping to change at page 30, line 48
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-11 and Message Parsing", draft-ietf-httpbis-p1-messaging-12
(work in progress), August 2010. (work in progress), October 2010.
[Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
and J. Reschke, Ed., "HTTP/1.1, part 2: Message and J. Reschke, Ed., "HTTP/1.1, part 2: Message
Semantics", draft-ietf-httpbis-p2-semantics-11 (work in Semantics", draft-ietf-httpbis-p2-semantics-12 (work in
progress), August 2010. progress), October 2010.
[Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional
Requests", draft-ietf-httpbis-p4-conditional-11 (work in Requests", draft-ietf-httpbis-p4-conditional-12 (work in
progress), August 2010. progress), October 2010.
[Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and
Partial Responses", draft-ietf-httpbis-p5-range-11 (work Partial Responses", draft-ietf-httpbis-p5-range-12 (work
in progress), August 2010. in progress), October 2010.
[Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication",
draft-ietf-httpbis-p7-auth-11 (work in progress), draft-ietf-httpbis-p7-auth-12 (work in progress),
August 2010. October 2010.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
8.2. Informative References 8.2. Informative References
[RFC1305] Mills, D., "Network Time Protocol (Version 3) [RFC1305] Mills, D., "Network Time Protocol (Version 3)
skipping to change at page 31, line 39 skipping to change at page 32, line 18
(Section 2.3.2) (Section 2.3.2)
Remove requirement to consider Content-Location in successful Remove requirement to consider Content-Location in successful
responses in order to determine the appropriate response to use. responses in order to determine the appropriate response to use.
(Section 2.4) (Section 2.4)
Clarify denial of service attack avoidance requirement. Clarify denial of service attack avoidance requirement.
(Section 2.5) (Section 2.5)
Do not mention RFC 2047 encoding and multiple languages in Warning Do not mention RFC 2047 encoding and multiple languages in Warning
headers anymore, as these aspects never were implemented. header fields anymore, as these aspects never were implemented.
(Section 3.6) (Section 3.6)
Appendix B. Collected ABNF Appendix B. Collected ABNF
Age = "Age:" OWS Age-v Age = "Age:" OWS Age-v
Age-v = delta-seconds Age-v = delta-seconds
Cache-Control = "Cache-Control:" OWS Cache-Control-v Cache-Control = "Cache-Control:" OWS Cache-Control-v
Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS
cache-directive ] ) cache-directive ] )
skipping to change at page 33, line 20 skipping to change at page 34, line 4
ABNF diagnostics: ABNF diagnostics:
; Age defined but not used ; Age defined but not used
; Cache-Control defined but not used ; Cache-Control defined but not used
; Expires defined but not used ; Expires defined but not used
; Pragma defined but not used ; Pragma defined but not used
; Vary defined but not used ; Vary defined but not used
; Warning defined but not used ; Warning defined but not used
Appendix C. Change Log (to be removed by RFC Editor before publication) Appendix C. Change Log (to be removed by RFC Editor before publication)
C.1. Since RFC 2616
C.1. Since RFC2616
Extracted relevant partitions from [RFC2616]. Extracted relevant partitions from [RFC2616].
C.2. Since draft-ietf-httpbis-p6-cache-00 C.2. Since draft-ietf-httpbis-p6-cache-00
Closed issues: Closed issues:
o <http://tools.ietf.org/wg/httpbis/trac/ticket/9>: "Trailer" o <http://tools.ietf.org/wg/httpbis/trac/ticket/9>: "Trailer"
(<http://purl.org/NET/http-errata#trailer-hop>) (<http://purl.org/NET/http-errata#trailer-hop>)
skipping to change at page 34, line 33 skipping to change at page 35, line 15
Other changes: Other changes:
o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work
in progress on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>) in progress on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>)
o Add explicit references to BNF syntax and rules imported from o Add explicit references to BNF syntax and rules imported from
other parts of the specification. other parts of the specification.
C.4. Since draft-ietf-httpbis-p6-cache-02 C.4. Since draft-ietf-httpbis-p6-cache-02
Ongoing work on IANA Message Header Registration Ongoing work on IANA Message Header Field Registration
(<http://tools.ietf.org/wg/httpbis/trac/ticket/40>): (<http://tools.ietf.org/wg/httpbis/trac/ticket/40>):
o Reference RFC 3984, and update header registrations for headers o Reference RFC 3984, and update header field registrations for
defined in this document. header fields defined in this document.
C.5. Since draft-ietf-httpbis-p6-cache-03 C.5. Since draft-ietf-httpbis-p6-cache-03
Closed issues: Closed issues:
o <http://tools.ietf.org/wg/httpbis/trac/ticket/106>: "Vary header o <http://tools.ietf.org/wg/httpbis/trac/ticket/106>: "Vary header
classification" classification"
C.6. Since draft-ietf-httpbis-p6-cache-04 C.6. Since draft-ietf-httpbis-p6-cache-04
Ongoing work on ABNF conversion Ongoing work on ABNF conversion
(<http://tools.ietf.org/wg/httpbis/trac/ticket/36>): (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>):
o Use "/" instead of "|" for alternatives. o Use "/" instead of "|" for alternatives.
o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional
whitespace ("OWS") and required whitespace ("RWS"). whitespace ("OWS") and required whitespace ("RWS").
o Rewrite ABNFs to spell out whitespace rules, factor out header o Rewrite ABNFs to spell out whitespace rules, factor out header
value format definitions. field value format definitions.
C.7. Since draft-ietf-httpbis-p6-cache-05 C.7. Since draft-ietf-httpbis-p6-cache-05
This is a total rewrite of this part of the specification. This is a total rewrite of this part of the specification.
Affected issues: Affected 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"
skipping to change at page 35, line 44 skipping to change at page 36, line 26
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>: Vary and non- o <http://tools.ietf.org/wg/httpbis/trac/ticket/37>: WVary 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-
Location on 304 responses" Location on 304 responses"
skipping to change at page 37, line 28 skipping to change at page 38, line 13
removing the 'changes from 2068' sections" removing the 'changes from 2068' sections"
o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing
heuristic caching for new status codes" heuristic caching for new status codes"
o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing o <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing
heuristic caching for new status codes" heuristic caching for new status codes"
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
Closed issues:
o <http://tools.ietf.org/wg/httpbis/trac/ticket/204>: "Text about
clock requirement for caches belongs in p6"
Index Index
A A
age 6 age 6
Age header 17 Age header 17
C C
cache 5 cache 5
Cache Directives Cache Directives
max-age 19, 22 max-age 19, 22
max-stale 19 max-stale 19
min-fresh 19 min-fresh 20
must-revalidate 22 must-revalidate 22
no-cache 19, 21 no-cache 19, 21
no-store 19, 21 no-store 19, 21
no-transform 20, 22 no-transform 20, 23
only-if-cached 20 only-if-cached 20
private 20 private 21
proxy-revalidate 22 proxy-revalidate 22
public 20 public 20
s-maxage 22 s-maxage 22
Cache-Control header 18 Cache-Control header 18
cacheable 5 cacheable 5
E E
Expires header 24 Expires header 24
explicit expiration time 5 explicit expiration time 5
F F
first-hand 6 first-hand 6
fresh 6 fresh 6
freshness lifetime 6 freshness lifetime 6
G G
Grammar Grammar
Age 17 Age 18
Age-v 17 Age-v 18
Cache-Control 18 Cache-Control 18
Cache-Control-v 18 Cache-Control-v 18
cache-extension 18 cache-extension 18
cache-request-directive 18 cache-request-directive 19
cache-response-directive 20 cache-response-directive 20
delta-seconds 17 delta-seconds 18
Expires 24 Expires 24
Expires-v 24 Expires-v 24
extension-pragma 24 extension-pragma 25
Pragma 24 Pragma 25
pragma-directive 24 pragma-directive 25
Pragma-v 24 Pragma-v 25
Vary 25 Vary 25
Vary-v 25 Vary-v 25
warn-agent 26 warn-agent 27
warn-code 26 warn-code 27
warn-date 26 warn-date 27
warn-text 26 warn-text 27
Warning 26 Warning 27
Warning-v 26 Warning-v 27
warning-value 26 warning-value 27
H H
Headers Headers
Age 17 Age 17
Cache-Control 18 Cache-Control 18
Expires 24 Expires 24
Pragma 24 Pragma 25
Vary 25 Vary 25
Warning 26 Warning 26
heuristic expiration time 5 heuristic expiration time 5
M M
max-age max-age
Cache Directive 19, 22 Cache Directive 19, 22
max-stale max-stale
Cache Directive 19 Cache Directive 19
min-fresh min-fresh
Cache Directive 19 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, 21
no-transform no-transform
Cache Directive 20, 22 Cache Directive 20, 23
O O
only-if-cached only-if-cached
Cache Directive 20 Cache Directive 20
P P
Pragma header 24 Pragma header 25
private private
Cache Directive 20 Cache Directive 21
proxy-revalidate proxy-revalidate
Cache Directive 22 Cache Directive 22
public public
Cache Directive 20 Cache Directive 20
S S
s-maxage s-maxage
Cache Directive 22 Cache Directive 22
stale 6 stale 6
 End of changes. 91 change blocks. 
187 lines changed or deleted 208 lines changed or added

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