draft-ietf-httpbis-cache-02.txt   draft-ietf-httpbis-cache-03.txt 
HTTP Working Group R. Fielding, Ed. HTTP Working Group R. Fielding, Ed.
Internet-Draft Adobe Internet-Draft Adobe
Obsoletes: 7234 (if approved) M. Nottingham, Ed. Obsoletes: 7234 (if approved) M. Nottingham, Ed.
Intended status: Standards Track Fastly Intended status: Standards Track Fastly
Expires: January 3, 2019 J. Reschke, Ed. Expires: April 21, 2019 J. Reschke, Ed.
greenbytes greenbytes
July 2, 2018 October 18, 2018
HTTP Caching HTTP Caching
draft-ietf-httpbis-cache-02 draft-ietf-httpbis-cache-03
Abstract Abstract
The Hypertext Transfer Protocol (HTTP) is a stateless application- The Hypertext Transfer Protocol (HTTP) is a stateless application-
level protocol for distributed, collaborative, hypertext information level protocol for distributed, collaborative, hypertext information
systems. This document defines HTTP caches and the associated header systems. This document defines HTTP caches and the associated header
fields that control cache behavior or indicate cacheable response fields that control cache behavior or indicate cacheable response
messages. messages.
This document obsoletes RFC 7234. This document obsoletes RFC 7234.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
This note is to be removed before publishing as an RFC. This note is to be removed before publishing as an RFC.
Discussion of this draft takes place on the HTTP working group Discussion of this draft takes place on the HTTP working group
mailing list (ietf-http-wg@w3.org), which is archived at mailing list (ietf-http-wg@w3.org), which is archived at
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. <https://lists.w3.org/Archives/Public/ietf-http-wg/>.
Working Group information can be found at <https://httpwg.org/>; Working Group information can be found at <https://httpwg.org/>;
source code and issues list for this draft can be found at source code and issues list for this draft can be found at
<https://github.com/httpwg/http-core>. <https://github.com/httpwg/http-core>.
The changes in this draft are summarized in Appendix C.3. The changes in this draft are summarized in Appendix C.4.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 3, 2019. This Internet-Draft will expire on April 21, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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
(https://trustee.ietf.org/license-info) in effect on the date of (https://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 6 skipping to change at page 3, line 6
3.1. Storing Incomplete Responses . . . . . . . . . . . . . . 8 3.1. Storing Incomplete Responses . . . . . . . . . . . . . . 8
3.2. Storing Responses to Authenticated Requests . . . . . . . 8 3.2. Storing Responses to Authenticated Requests . . . . . . . 8
3.3. Combining Partial Content . . . . . . . . . . . . . . . . 8 3.3. Combining Partial Content . . . . . . . . . . . . . . . . 8
4. Constructing Responses from Caches . . . . . . . . . . . . . 9 4. Constructing Responses from Caches . . . . . . . . . . . . . 9
4.1. Calculating Secondary Keys with Vary . . . . . . . . . . 10 4.1. Calculating Secondary Keys with Vary . . . . . . . . . . 10
4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 11 4.2. Freshness . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 12 4.2.1. Calculating Freshness Lifetime . . . . . . . . . . . 12
4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 13 4.2.2. Calculating Heuristic Freshness . . . . . . . . . . . 13
4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 14 4.2.3. Calculating Age . . . . . . . . . . . . . . . . . . . 14
4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 15 4.2.4. Serving Stale Responses . . . . . . . . . . . . . . . 15
4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 16 4.3. Validation . . . . . . . . . . . . . . . . . . . . . . . 15
4.3.1. Sending a Validation Request . . . . . . . . . . . . 16 4.3.1. Sending a Validation Request . . . . . . . . . . . . 16
4.3.2. Handling a Received Validation Request . . . . . . . 17 4.3.2. Handling a Received Validation Request . . . . . . . 16
4.3.3. Handling a Validation Response . . . . . . . . . . . 18 4.3.3. Handling a Validation Response . . . . . . . . . . . 18
4.3.4. Freshening Stored Responses upon Validation . . . . . 18 4.3.4. Freshening Stored Responses upon Validation . . . . . 18
4.3.5. Freshening Responses via HEAD . . . . . . . . . . . . 19 4.3.5. Freshening Responses with HEAD . . . . . . . . . . . 19
4.4. Invalidation . . . . . . . . . . . . . . . . . . . . . . 20 4.4. Invalidation . . . . . . . . . . . . . . . . . . . . . . 20
5. Header Field Definitions . . . . . . . . . . . . . . . . . . 21 5. Header Field Definitions . . . . . . . . . . . . . . . . . . 20
5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 5.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 22 5.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 21
5.2.1. Request Cache-Control Directives . . . . . . . . . . 23 5.2.1. Request Cache-Control Directives . . . . . . . . . . 22
5.2.2. Response Cache-Control Directives . . . . . . . . . . 25 5.2.1.1. max-age . . . . . . . . . . . . . . . . . . . . . 22
5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 28 5.2.1.2. max-stale . . . . . . . . . . . . . . . . . . . . 22
5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 29 5.2.1.3. min-fresh . . . . . . . . . . . . . . . . . . . . 23
5.2.1.4. no-cache . . . . . . . . . . . . . . . . . . . . 23
5.2.1.5. no-store . . . . . . . . . . . . . . . . . . . . 23
5.2.1.6. no-transform . . . . . . . . . . . . . . . . . . 24
5.2.1.7. only-if-cached . . . . . . . . . . . . . . . . . 24
5.2.2. Response Cache-Control Directives . . . . . . . . . . 24
5.2.2.1. must-revalidate . . . . . . . . . . . . . . . . . 24
5.2.2.2. no-cache . . . . . . . . . . . . . . . . . . . . 24
5.2.2.3. no-store . . . . . . . . . . . . . . . . . . . . 25
5.2.2.4. no-transform . . . . . . . . . . . . . . . . . . 26
5.2.2.5. public . . . . . . . . . . . . . . . . . . . . . 26
5.2.2.6. private . . . . . . . . . . . . . . . . . . . . . 26
5.2.2.7. proxy-revalidate . . . . . . . . . . . . . . . . 27
5.2.2.8. max-age . . . . . . . . . . . . . . . . . . . . . 27
5.2.2.9. s-maxage . . . . . . . . . . . . . . . . . . . . 27
5.2.3. Cache Control Extensions . . . . . . . . . . . . . . 27
5.2.4. Cache Directive Registry . . . . . . . . . . . . . . 28
5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 29 5.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 29
5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 30 5.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 31 5.5. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 30
5.5.1. Warning: 110 - "Response is Stale" . . . . . . . . . 33 6. Relationship to Applications . . . . . . . . . . . . . . . . 31
5.5.2. Warning: 111 - "Revalidation Failed" . . . . . . . . 33 7. Security Considerations . . . . . . . . . . . . . . . . . . . 31
5.5.3. Warning: 112 - "Disconnected Operation" . . . . . . . 33 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 32
5.5.4. Warning: 113 - "Heuristic Expiration" . . . . . . . . 34 8.1. Header Field Registration . . . . . . . . . . . . . . . . 32
5.5.5. Warning: 199 - "Miscellaneous Warning" . . . . . . . 34 8.2. Cache Directive Registration . . . . . . . . . . . . . . 32
5.5.6. Warning: 214 - "Transformation Applied" . . . . . . . 34 8.3. Warn Code Registry . . . . . . . . . . . . . . . . . . . 32
5.5.7. Warning: 299 - "Miscellaneous Persistent Warning" . . 34 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 32
5.5.8. Warn Code Registry . . . . . . . . . . . . . . . . . 34 9.1. Normative References . . . . . . . . . . . . . . . . . . 32
6. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 34 9.2. Informative References . . . . . . . . . . . . . . . . . 33
7. Security Considerations . . . . . . . . . . . . . . . . . . . 35 Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 35
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 36 Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 35
8.1. Header Field Registration . . . . . . . . . . . . . . . . 36 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 36
8.2. Cache Directive Registration . . . . . . . . . . . . . . 36 C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 36
8.3. Warn Code Registration . . . . . . . . . . . . . . . . . 36 C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 36
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 36 C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 36
9.1. Normative References . . . . . . . . . . . . . . . . . . 36 C.4. Since draft-ietf-httpbis-cache-02 . . . . . . . . . . . . 36
9.2. Informative References . . . . . . . . . . . . . . . . . 37 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Appendix A. Collected ABNF . . . . . . . . . . . . . . . . . . . 38 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 39
Appendix B. Changes from RFC 7234 . . . . . . . . . . . . . . . 39 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 39
C.1. Between RFC7234 and draft 00 . . . . . . . . . . . . . . 39
C.2. Since draft-ietf-httpbis-cache-00 . . . . . . . . . . . . 39
C.3. Since draft-ietf-httpbis-cache-01 . . . . . . . . . . . . 39
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 42
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 42
1. Introduction 1. Introduction
The Hypertext Transfer Protocol (HTTP) is a stateless application- The Hypertext Transfer Protocol (HTTP) is a stateless application-
level request/response protocol that uses extensible semantics and level request/response protocol that uses extensible semantics and
self-descriptive messages for flexible interaction with network-based self-descriptive messages for flexible interaction with network-based
hypertext information systems. HTTP is defined by a series of hypertext information systems. HTTP is defined by a series of
documents that collectively form the HTTP/1.1 specification: documents that collectively form the HTTP/1.1 specification:
o "HTTP Semantics" [Semantics] o "HTTP Semantics" [Semantics]
skipping to change at page 4, line 37 skipping to change at page 4, line 43
and network bandwidth consumption on future, equivalent requests. and network bandwidth consumption on future, equivalent requests.
Any client or server MAY employ a cache, though a cache cannot be Any client or server MAY employ a cache, though a cache cannot be
used by a server that is acting as a tunnel. used by a server that is acting as a tunnel.
A shared cache is a cache that stores responses to be reused by more A shared cache is a cache that stores responses to be reused by more
than one user; shared caches are usually (but not always) deployed as than one user; shared caches are usually (but not always) deployed as
a part of an intermediary. A private cache, in contrast, is a part of an intermediary. A private cache, in contrast, is
dedicated to a single user; often, they are deployed as a component dedicated to a single user; often, they are deployed as a component
of a user agent. of a user agent.
The goal of caching in HTTP/1.1 is to significantly improve The goal of caching in HTTP is to significantly improve performance
performance by reusing a prior response message to satisfy a current by reusing a prior response message to satisfy a current request. A
request. A stored response is considered "fresh", as defined in stored response is considered "fresh", as defined in Section 4.2, if
Section 4.2, if the response can be reused without "validation" the response can be reused without "validation" (checking with the
(checking with the origin server to see if the cached response origin server to see if the cached response remains valid for this
remains valid for this request). A fresh response can therefore request). A fresh response can therefore reduce both latency and
reduce both latency and network overhead each time it is reused. network overhead each time it is reused. When a cached response is
When a cached response is not fresh, it might still be reusable if it not fresh, it might still be reusable if it can be freshened by
can be freshened by validation (Section 4.3) or if the origin is validation (Section 4.3) or if the origin is unavailable
unavailable (Section 4.2.4). (Section 4.2.4).
This document obsoletes RFC 7234, with the changes being summarized This document obsoletes RFC 7234, with the changes being summarized
in Appendix B. in Appendix B.
1.1. Requirements Notation 1.1. Requirements Notation
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "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].
skipping to change at page 5, line 39 skipping to change at page 5, line 44
The rules below are defined in [Semantics]: The rules below are defined in [Semantics]:
HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1> HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>
OWS = <OWS, see [Semantics], Section 4.3> OWS = <OWS, see [Semantics], Section 4.3>
field-name = <field-name, see [Semantics], Section 4.2> field-name = <field-name, see [Semantics], Section 4.2>
quoted-string = <quoted-string, see [Semantics], Section 4.2.3> quoted-string = <quoted-string, see [Semantics], Section 4.2.3>
token = <token, see [Semantics], Section 4.2.3> token = <token, see [Semantics], Section 4.2.3>
uri-host = <host, see [RFC3986], Section 3.2.2> uri-host = <host, see [RFC3986], Section 3.2.2>
port = <port, see [RFC3986], Section 3.2.3> port = <port, see [RFC3986], Section 3.2.3>
pseudonym = <pseudonym, see [Semantics], Section 5.6.1> pseudonym = <pseudonym, see [Semantics], Section 5.5.1>
1.3. Delta Seconds 1.3. Delta Seconds
The delta-seconds rule specifies a non-negative integer, representing The delta-seconds rule specifies a non-negative integer, representing
time in seconds. time in seconds.
delta-seconds = 1*DIGIT delta-seconds = 1*DIGIT
A recipient parsing a delta-seconds value and converting it to binary A recipient parsing a delta-seconds value and converting it to binary
form ought to use an arithmetic type of at least 31 bits of non- form ought to use an arithmetic type of at least 31 bits of non-
skipping to change at page 6, line 19 skipping to change at page 6, line 25
to be stored in binary form; an implementation could produce it as to be stored in binary form; an implementation could produce it as
a canned string if any overflow occurs, even if the calculations a canned string if any overflow occurs, even if the calculations
are performed with an arithmetic type incapable of directly are performed with an arithmetic type incapable of directly
representing that number. What matters here is that an overflow representing that number. What matters here is that an overflow
be detected and not treated as a negative value in later be detected and not treated as a negative value in later
calculations. calculations.
2. Overview of Cache Operation 2. Overview of Cache Operation
Proper cache operation preserves the semantics of HTTP transfers Proper cache operation preserves the semantics of HTTP transfers
([Semantics]) while eliminating the transfer of information already ([Semantics]) while reducing the transfer of information already held
held in the cache. Although caching is an entirely OPTIONAL feature in the cache. Although caching is an entirely OPTIONAL feature of
of HTTP, it can be assumed that reusing a cached response is HTTP, it can be assumed that reusing a cached response is desirable
desirable and that such reuse is the default behavior when no and that such reuse is the default behavior when no requirement or
requirement or local configuration prevents it. Therefore, HTTP local configuration prevents it. Therefore, HTTP cache requirements
cache requirements are focused on preventing a cache from either are focused on preventing a cache from either storing a non-reusable
storing a non-reusable response or reusing a stored response response or reusing a stored response inappropriately, rather than
inappropriately, rather than mandating that caches always store and mandating that caches always store and reuse particular responses.
reuse particular responses.
Each cache entry consists of a cache key and one or more HTTP Each cache entry consists of a cache key and one or more HTTP
responses corresponding to prior requests that used the same key. responses corresponding to prior requests that used the same key.
The most common form of cache entry is a successful result of a The most common form of cache entry is a successful result of a
retrieval request: i.e., a 200 (OK) response to a GET request, which retrieval request: i.e., a 200 (OK) response to a GET request, which
contains a representation of the resource identified by the request contains a representation of the resource identified by the request
target (Section 7.3.1 of [Semantics]). However, it is also possible target (Section 7.3.1 of [Semantics]). However, it is also possible
to cache permanent redirects, negative results (e.g., 404 (Not to cache permanent redirects, negative results (e.g., 404 (Not
Found)), incomplete results (e.g., 206 (Partial Content)), and Found)), incomplete results (e.g., 206 (Partial Content)), and
responses to methods other than GET if the method's definition allows responses to methods other than GET if the method's definition allows
skipping to change at page 7, line 12 skipping to change at page 7, line 14
by a secondary key for the values of the original request's selecting by a secondary key for the values of the original request's selecting
header fields (Section 4.1). header fields (Section 4.1).
3. Storing Responses in Caches 3. Storing Responses in Caches
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 final (see Section 9.3 of
[Messaging]), 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 5.2) does not appear o the "no-store" cache directive (see Section 5.2) does not appear
in request or response header fields, and in request or response header fields, and
o the "private" response directive (see Section 5.2.2.6) does not o the "private" response directive (see Section 5.2.2.6) 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 field (see Section 8.5.3 of [Semantics]) o the Authorization header field (see Section 8.5.3 of [Semantics])
does not appear in the request, if the cache is shared, unless the does not appear in the request, if the cache is shared, unless the
skipping to change at page 8, line 40 skipping to change at page 8, line 45
A shared cache MUST NOT use a cached response to a request with an A shared cache MUST NOT use a cached response to a request with an
Authorization header field (Section 8.5.3 of [Semantics]) to satisfy Authorization header field (Section 8.5.3 of [Semantics]) to satisfy
any subsequent request unless a cache directive that allows such any 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 5.2.2) have such an effect: must-revalidate, directives (Section 5.2.2) have such an effect: must-revalidate,
public, and s-maxage. public, and s-maxage.
Note that cached responses that contain the "must-revalidate" and/or
"s-maxage" response directives are not allowed to be served stale
(Section 4.2.4) by shared caches. In particular, a response with
either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
satisfy a subsequent request without revalidating it on the origin
server.
3.3. Combining Partial Content 3.3. Combining Partial Content
A response might transfer only a partial representation if the A response might transfer only a partial representation if the
connection closed prematurely or if the request used one or more connection closed prematurely or if the request used one or more
Range specifiers (Section 8.3 of [Semantics]). After several such Range specifiers (Section 8.3 of [Semantics]). After several such
transfers, a cache might have received several ranges of the same transfers, a cache might have received several ranges of the same
representation. A cache MAY combine these ranges into a single representation. A cache MAY combine these ranges into a single
stored response, and reuse that response to satisfy later requests, stored response, and reuse that response to satisfy later requests,
if they all share the same strong validator and the cache complies if they all share the same strong validator and the cache complies
with the client requirements in Section 9.3.7.3 of [Semantics]. with the client requirements in Section 9.3.7.3 of [Semantics].
When combining the new response with one or more stored responses, a When combining the new response with one or more stored responses, a
cache MUST: cache MUST use the header fields provided in the new response, aside
from Content-Range, to replace all instances of the corresponding
o delete any Warning header fields in the stored response with warn- header fields in the stored response.
code 1xx (see Section 5.5);
o retain any Warning header fields in the stored response with warn-
code 2xx; and,
o use other header fields provided in the new response, aside from
Content-Range, to replace all instances of the corresponding
header fields in the stored response.
4. Constructing Responses from Caches 4. Constructing Responses from Caches
When presented with a request, a cache MUST NOT reuse a stored When presented with a request, a cache MUST NOT reuse a stored
response, unless: response, unless:
o The presented effective request URI (Section 5.3 of [Semantics]) o The presented effective request URI (Section 5.3 of [Semantics])
and that of the stored response match, and 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
skipping to change at page 13, line 50 skipping to change at page 13, line 44
whose status codes are defined as cacheable by default (see whose status codes are defined as cacheable by default (see
Section 9.1 of [Semantics]), and those responses without explicit Section 9.1 of [Semantics]), and those responses without explicit
freshness that have been marked as explicitly cacheable (e.g., with a freshness that have been marked as explicitly cacheable (e.g., with a
"public" response directive). "public" response directive).
If the response has a Last-Modified header field (Section 10.2.2 of If the response has a Last-Modified header field (Section 10.2.2 of
[Semantics]), caches are encouraged to use a heuristic expiration [Semantics]), caches are encouraged to use a heuristic expiration
value that is no more than some fraction of the interval since that value that is no more than some fraction of the interval since that
time. A typical setting of this fraction might be 10%. time. A typical setting of this fraction might be 10%.
When a heuristic is used to calculate freshness lifetime, a cache
SHOULD generate a Warning header field with a 113 warn-code (see
Section 5.5.4) in the response if its current_age is more than 24
hours and such a warning is not already present.
Note: Section 13.9 of [RFC2616] prohibited caches from calculating Note: Section 13.9 of [RFC2616] prohibited caches from calculating
heuristic freshness for URIs with query components (i.e., those heuristic freshness for URIs with query components (i.e., those
containing '?'). In practice, this has not been widely containing '?'). In practice, this has not been widely
implemented. Therefore, origin servers are encouraged to send implemented. Therefore, origin 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.
4.2.3. Calculating Age 4.2.3. Calculating Age
The Age header field is used to convey an estimated age of the The Age header field is used to convey an estimated age of the
skipping to change at page 15, line 11 skipping to change at page 14, line 50
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. A cache MUST interpret this response path implement HTTP/1.1 or greater. A cache MUST
value relative to the time the request was initiated, not the interpret this value relative to the time the request was
time that the response was received. initiated, not the time that the response was received.
apparent_age = max(0, response_time - date_value); apparent_age = max(0, response_time - date_value);
response_delay = response_time - request_time; response_delay = response_time - request_time;
corrected_age_value = age_value + response_delay; corrected_age_value = age_value + response_delay;
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 16, line 5 skipping to change at page 15, line 43
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 5.2.2). see Section 5.2.2).
A cache MUST NOT send stale responses unless it is disconnected A cache MUST NOT send 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 doing so is explicitly allowed (e.g., by the max- forward path) or doing so is explicitly allowed (e.g., by the max-
stale request directive; see Section 5.2.1). stale request directive; see Section 5.2.1).
A cache SHOULD generate a Warning header field with the 110 warn-code
(see Section 5.5.1) in stale responses. Likewise, a cache SHOULD
generate a 112 warn-code (see Section 5.5.3) in stale responses if
the cache is disconnected.
A cache SHOULD NOT generate a new Warning header field when
forwarding a response that does not have an Age header field, even if
the response is already stale. A cache need not validate a response
that merely became stale in transit.
4.3. Validation 4.3. Validation
When a cache has one or more stored responses for a requested URI, When a cache has one or more stored responses for a requested URI,
but cannot serve any of them (e.g., because they are not fresh, or but cannot serve any of them (e.g., because they are not fresh, or
one cannot be selected; see Section 4.1), it can use the conditional one cannot be selected; see Section 4.1), it can use the conditional
request mechanism Section 8.2 of [Semantics] in the forwarded request request mechanism Section 8.2 of [Semantics] in the forwarded request
to give the next inbound server an opportunity to select a valid to give the next inbound server an opportunity to select a valid
stored response to use, updating the stored metadata in the process, stored response to use, updating the stored metadata in the process,
or to replace the stored response(s) with a new response. This or to replace the stored response(s) with a new response. This
process is known as "validating" or "revalidating" the stored process is known as "validating" or "revalidating" the stored
response. response.
4.3.1. Sending a Validation Request 4.3.1. Sending a Validation Request
When sending a conditional request for cache validation, a cache When generating a conditional request for validation, a cache starts
sends one or more precondition header fields containing validator with either a request it is attempting to satisfy, or -- if it is
metadata from its stored response(s), which is then compared by initiating the request independently -- it synthesises a request
recipients to determine whether a stored response is equivalent to a using a stored response by copying the method, request-target, and
current representation of the resource. request header fields used for identifying the secondary cache key
Section 4.1.
It then updates that request with one or more precondition header
fields. These contain validator metadata sourced from stored
response(s) that have the same cache key (both primary and secondary,
as applicable).
The precondition header fields are then compared by recipients to
determine whether any stored response is equivalent to a current
representation of the resource.
One such validator is the timestamp given in a Last-Modified header One such validator is the timestamp given in a Last-Modified header
field (Section 10.2.2 of [Semantics]), which can be used in an If- field (Section 10.2.2 of [Semantics]), which can be used in an If-
Modified-Since header field for response validation, or in an If- Modified-Since header field for response validation, or in an If-
Unmodified-Since or If-Range header field for representation Unmodified-Since or If-Range header field for representation
selection (i.e., the client is referring specifically to a previously selection (i.e., the client is referring specifically to a previously
obtained representation with that timestamp). obtained representation with that timestamp).
Another validator is the entity-tag given in an ETag header field Another validator is the entity-tag given in an ETag header field
(Section 10.2.3 of [Semantics]). One or more entity-tags, indicating (Section 10.2.3 of [Semantics]). One or more entity-tags, indicating
skipping to change at page 18, line 49 skipping to change at page 18, line 37
o However, if a cache receives a 5xx (Server Error) response while o However, if a cache receives a 5xx (Server Error) response while
attempting to validate a response, it can either forward this attempting to validate a response, it can either forward this
response to the requesting client, or act as if the server failed response to the requesting client, or act as if the server failed
to respond. In the latter case, the cache MAY send a previously to respond. In the latter case, the cache MAY send a previously
stored response (see Section 4.2.4). stored response (see Section 4.2.4).
4.3.4. Freshening Stored Responses upon Validation 4.3.4. Freshening Stored Responses upon Validation
When a cache receives a 304 (Not Modified) response and already has When a cache receives a 304 (Not Modified) response and already has
one or more stored 200 (OK) responses for the same cache key, the one or more stored 200 (OK) responses for the applicable cache key,
cache needs to identify which of the stored responses are updated by the cache needs to identify which (if any) are to be updated by the
this new response and then update the stored response(s) with the new new information provided, and then do so.
information provided in the 304 response.
The stored response to update is identified by using the first match The stored response(s) to update are identified by using the first
(if any) of the following: match (if any) of the following:
o If the new response contains a strong validator (see o If the new response contains a strong validator (see
Section 10.2.1 of [Semantics]), then that strong validator Section 10.2.1 of [Semantics]), then that strong validator
identifies the selected representation for update. All of the identifies the selected representation for update. All of the
stored responses with the same strong validator are selected. If stored responses with the same strong validator are identified for
none of the stored responses contain the same strong validator, update. If none of the stored responses contain the same strong
then the cache MUST NOT use the new response to update any stored validator, then the cache MUST NOT use the new response to update
responses. any stored responses.
o If the new response contains a weak validator and that validator o If the new response contains a weak validator and that validator
corresponds to one of the cache's stored responses, then the most corresponds to one of the cache's stored responses, then the most
recent of those matching stored responses is selected for update. recent of those matching stored responses is identified for
update.
o If the new response does not include any form of validator (such o If the new response does not include any form of validator (such
as in the case where a client generates an If-Modified-Since as in the case where a client generates an If-Modified-Since
request from a source other than the Last-Modified response header request from a source other than the Last-Modified response header
field), and there is only one stored response, and that stored field), and there is only one stored response, and that stored
response also lacks a validator, then that stored response is response also lacks a validator, then that stored response is
selected for update. identified for update.
If a stored response is selected for update, the cache MUST:
o delete any Warning header fields in the stored response with warn-
code 1xx (see Section 5.5);
o retain any Warning header fields in the stored response with warn-
code 2xx; and,
o use other header fields provided in the 304 (Not Modified) For each stored response identified for update, the cache MUST use
response to replace all instances of the corresponding header the header fields provided in the 304 (Not Modified) response to
fields in the stored response. replace all instances of the corresponding header fields in the
stored response.
4.3.5. Freshening Responses via HEAD 4.3.5. Freshening Responses with HEAD
A response to the HEAD method is identical to what an equivalent A response to the HEAD method is identical to what an equivalent
request made with a GET would have been, except it lacks a body. request made with a GET would have been, except it lacks a body.
This property of HEAD responses can be used to invalidate or update a This property of HEAD responses can be used to invalidate or update a
cached GET response if the more efficient conditional GET request cached GET response if the more efficient conditional GET request
mechanism is not available (due to no validators being present in the mechanism is not available (due to no validators being present in the
stored response) or if transmission of the representation body is not stored response) or if transmission of the representation body is not
desired even if it has changed. desired even if it has changed.
When a cache makes an inbound HEAD request for a given request target When a cache makes an inbound HEAD request for a given request target
skipping to change at page 20, line 19 skipping to change at page 19, line 46
For each of the stored responses that could have been selected, if For each of the stored responses that could have been selected, if
the stored response and HEAD response have matching values for any the stored response and HEAD response have matching values for any
received validator fields (ETag and Last-Modified) and, if the HEAD received validator fields (ETag and Last-Modified) and, if the HEAD
response has a Content-Length header field, the value of Content- response has a Content-Length header field, the value of Content-
Length matches that of the stored response, the cache SHOULD update Length matches that of the stored response, the cache SHOULD update
the stored response as described below; otherwise, the cache SHOULD the stored response as described below; otherwise, the cache SHOULD
consider the stored response to be stale. consider the stored response to be stale.
If a cache updates a stored response with the metadata provided in a If a cache updates a stored response with the metadata provided in a
HEAD response, the cache MUST: HEAD response, the cache MUST use the header fields provided in the
HEAD response to replace all instances of the corresponding header
o delete any Warning header fields in the stored response with warn- fields in the stored response and append new header fields to the
code 1xx (see Section 5.5); stored response's header section unless otherwise restricted by the
Cache-Control header field.
o retain any Warning header fields in the stored response with warn-
code 2xx; and,
o use other header fields provided in the HEAD response to replace
all instances of the corresponding header fields in the stored
response and append new header fields to the stored response's
header section unless otherwise restricted by the Cache-Control
header field.
4.4. Invalidation 4.4. Invalidation
Because unsafe request methods (Section 7.2.1 of [Semantics]) such as Because unsafe request methods (Section 7.2.1 of [Semantics]) such as
PUT, POST or DELETE have the potential for changing state on the PUT, POST or DELETE have the potential for changing state on the
origin server, intervening caches can use them to keep their contents origin server, intervening caches can use them to keep their contents
up to date. up to date.
A cache MUST invalidate the effective Request URI (Section 5.3 of A cache MUST invalidate the effective Request URI (Section 5.3 of
[Semantics]) as well as the URI(s) in the Location and Content- [Semantics]) as well as the URI(s) in the Location and Content-
skipping to change at page 21, line 19 skipping to change at page 20, line 40
validation before they can be sent in response to a subsequent validation before they can be sent in response to a subsequent
request. 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, a state-changing request might invalidate invalidated. For example, a state-changing request might invalidate
responses in the caches it travels through, but relevant responses responses in the caches it travels through, but relevant responses
still might be stored in other caches that it has not. still might be stored in other caches that it has not.
5. Header Field Definitions 5. Header Field Definitions
This section defines the syntax and semantics of HTTP/1.1 header This section defines the syntax and semantics of HTTP header fields
fields related to caching. related to caching.
+-------------------+----------+----------+--------------+ +-------------------+----------+-----------+--------------+
| Header Field Name | Protocol | Status | Reference | | Header Field Name | Protocol | Status | Reference |
+-------------------+----------+----------+--------------+ +-------------------+----------+-----------+--------------+
| Age | http | standard | Section 5.1 | | Age | http | standard | Section 5.1 |
| Cache-Control | http | standard | Section 5.2 | | Cache-Control | http | standard | Section 5.2 |
| Expires | http | standard | Section 5.3 | | Expires | http | standard | Section 5.3 |
| Pragma | http | standard | Section 5.4 | | Pragma | http | standard | Section 5.4 |
| Warning | http | standard | Section 5.5 | | Warning | http | obsoleted | Section 5.5 |
+-------------------+----------+----------+--------------+ +-------------------+----------+-----------+--------------+
5.1. Age 5.1. Age
The "Age" header field conveys the sender's estimate of the amount of The "Age" header field conveys the sender's estimate of the amount of
time since the response was generated or successfully validated at time since the response was generated or successfully validated at
the origin server. Age values are calculated as specified in the origin server. Age values are calculated as specified in
Section 4.2.3. Section 4.2.3.
Age = delta-seconds Age = delta-seconds
skipping to change at page 22, line 10 skipping to change at page 21, line 28
generated or validated by the origin server for this request. generated or validated by the origin server for this request.
However, lack of an Age header field does not imply the origin was However, lack of an Age header field does not imply the origin was
contacted, since the response might have been received from an contacted, since the response might have been received from an
HTTP/1.0 cache that does not implement Age. HTTP/1.0 cache that does not implement Age.
5.2. Cache-Control 5.2. Cache-Control
The "Cache-Control" header field is used to specify directives for The "Cache-Control" header field is used to specify directives for
caches along the request/response chain. Such cache directives are caches along the request/response chain. Such cache directives are
unidirectional in that the presence of a directive in a request does unidirectional in that the presence of a directive in a request does
not imply that the same directive is to be given in the response. not imply that the same directive is present in the response, or to
be repeated in it.
A cache MUST obey the requirements of the Cache-Control directives A cache MUST obey the requirements of the Cache-Control directives
defined in this section. See Section 5.2.3 for information about how defined in this section. See Section 5.2.3 for information about how
Cache-Control directives defined elsewhere are handled. Cache-Control directives defined elsewhere are handled.
Note: Some HTTP/1.0 caches might not implement Cache-Control. Note: Some HTTP/1.0 caches might not implement Cache-Control.
A proxy, whether or not it implements a cache, MUST pass cache A proxy, whether or not it implements a cache, MUST pass cache
directives through in forwarded messages, regardless of their directives through in forwarded messages, regardless of their
significance to that application, since the directives might be significance to that application, since the directives might be
skipping to change at page 25, line 9 skipping to change at page 24, line 13
be vulnerable to eavesdropping. be vulnerable to eavesdropping.
Note that if a request containing this directive is satisfied from a Note that if a request containing this directive is satisfied from a
cache, the no-store request directive does not apply to the already cache, the no-store request directive does not apply to the already
stored response. stored response.
5.2.1.6. no-transform 5.2.1.6. no-transform
The "no-transform" request directive indicates that an intermediary The "no-transform" request directive indicates that an intermediary
(whether or not it implements a cache) MUST NOT transform the (whether or not it implements a cache) MUST NOT transform the
payload, as defined in Section 5.6.2 of [Semantics]. payload, as defined in Section 5.5.2 of [Semantics].
5.2.1.7. only-if-cached 5.2.1.7. only-if-cached
The "only-if-cached" request directive indicates that the client only The "only-if-cached" request directive indicates that the client only
wishes to obtain a stored response. If it receives this directive, a wishes to obtain a stored response. If it receives this directive, a
cache SHOULD either respond using a stored response that is cache SHOULD either respond using a stored response that is
consistent with the other constraints of the request, or respond with consistent with the other constraints of the request, or respond with
a 504 (Gateway Timeout) status code. If a group of caches is being a 504 (Gateway Timeout) status code. If a group of caches is being
operated as a unified system with good internal connectivity, a operated as a unified system with good internal connectivity, a
member cache MAY forward such a request within that group of caches. member cache MAY forward such a request within that group of caches.
5.2.2. Response Cache-Control Directives 5.2.2. Response Cache-Control Directives
5.2.2.1. must-revalidate 5.2.2.1. must-revalidate
The "must-revalidate" response directive indicates that once it has The "must-revalidate" response directive indicates that once it has
become stale, a cache MUST NOT use the response to satisfy subsequent become stale, the response MUST NOT be used to satisfy any other
requests without successful validation on the origin server. request without forwarding it for validation and receiving a
successful response; see Section 4.3.
The must-revalidate directive is necessary to support reliable The must-revalidate directive is necessary to support reliable
operation for certain protocol features. In all circumstances a operation for certain protocol features. In all circumstances a
cache MUST obey the must-revalidate directive; in particular, if a cache MUST obey the must-revalidate directive; in particular, if a
cache cannot reach the origin server for any reason, it MUST generate cache cannot reach the origin server for any reason, it MUST generate
a 504 (Gateway Timeout) response. a 504 (Gateway Timeout) response.
The must-revalidate directive ought to be used by servers if and only The must-revalidate directive ought to be used by servers if and only
if failure to validate a request on the representation could result if 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.
5.2.2.2. no-cache 5.2.2.2. no-cache
Argument syntax: Argument syntax:
#field-name #field-name
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 any other request without forwarding it for
validation on the origin server. This allows an origin server to validation and receiving a successful response; see Section 4.3.
prevent a cache from using it to satisfy a request without contacting
it, even by caches that have been configured to send stale responses. This allows an origin server to prevent a cache from using it to
satisfy a request without contacting it, even by caches that have
been configured to send stale responses.
If the no-cache response directive specifies one or more field-names, If the no-cache response directive specifies one or more field-names,
then a cache MAY use the response to satisfy a subsequent request, then a cache MAY use the response to satisfy a subsequent request,
subject to any other restrictions on caching. However, any header subject to any other restrictions on caching. However, any header
fields in the response that have the field-name(s) listed MUST NOT be fields in the response that have the field-name(s) listed MUST NOT be
sent in the response to a subsequent request without successful sent in the response to a subsequent request without successful
revalidation with the origin server. This allows an origin server to revalidation with the origin server. This allows an origin server to
prevent the re-use of certain header fields in a response, while prevent the re-use of certain header fields in a response, while
still allowing caching of the rest of the response. still allowing caching of the rest of the response.
skipping to change at page 26, line 31 skipping to change at page 25, line 39
Note: Although it has been back-ported to many implementations, some Note: Although it has been back-ported to many implementations, some
HTTP/1.0 caches will not recognize or obey this directive. Also, no- HTTP/1.0 caches will not recognize or obey this directive. Also, no-
cache response directives with field-names are often handled by cache response directives with field-names are often handled by
caches as if an unqualified no-cache directive was received; i.e., caches as if an unqualified no-cache directive was received; i.e.,
the special handling for the qualified form is not widely the special handling for the qualified form is not widely
implemented. implemented.
5.2.2.3. no-store 5.2.2.3. 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, and MUST
directive applies to both private and shared caches. "MUST NOT NOT use the response to satisfy any other request.
This directive applies to both private and shared caches. "MUST NOT
store" in this context means that the cache MUST NOT intentionally store" in this context means that the cache MUST NOT intentionally
store the information in non-volatile storage, and MUST make a best- store the information in non-volatile storage, and MUST make a best-
effort attempt to remove the information from volatile storage as effort attempt to remove the information from volatile storage as
promptly as possible after forwarding it. promptly as possible after forwarding it.
This directive is NOT a reliable or sufficient mechanism for ensuring This directive is NOT a reliable or sufficient mechanism for ensuring
privacy. In particular, malicious or compromised caches might not privacy. In particular, malicious or compromised caches might not
recognize or obey this directive, and communications networks might recognize or obey this directive, and communications networks might
be vulnerable to eavesdropping. be vulnerable to eavesdropping.
5.2.2.4. no-transform 5.2.2.4. no-transform
The "no-transform" response directive indicates that an intermediary The "no-transform" response directive indicates that an intermediary
(regardless of whether it implements a cache) MUST NOT transform the (regardless of whether it implements a cache) MUST NOT transform the
payload, as defined in Section 5.6.2 of [Semantics]. payload, as defined in Section 5.5.2 of [Semantics].
5.2.2.5. public 5.2.2.5. public
The "public" response directive indicates that any cache MAY store The "public" response directive indicates that any cache MAY store
the response, even if the response would normally be non-cacheable or the response, even if the response would normally be non-cacheable or
cacheable only within a private cache. (See Section 3.2 for cacheable only within a private cache. (See Section 3.2 for
additional details related to the use of public in response to a additional details related to the use of public in response to a
request containing Authorization, and Section 3 for details of how request containing Authorization, and Section 3 for details of how
public affects responses that would normally not be stored, due to public affects responses that would normally not be stored, due to
their status codes not being defined as cacheable by default; see their status codes not being defined as cacheable by default; see
skipping to change at page 31, line 17 skipping to change at page 30, line 29
extension-pragma = token [ "=" ( token / quoted-string ) ] extension-pragma = token [ "=" ( token / quoted-string ) ]
When the Cache-Control header field is not present in a request, When the Cache-Control header field is not present in a request,
caches MUST consider the no-cache request pragma-directive as having caches MUST consider the no-cache request pragma-directive as having
the same effect as if "Cache-Control: no-cache" were present (see the same effect as if "Cache-Control: no-cache" were present (see
Section 5.2.1). Section 5.2.1).
When sending a no-cache request, a client ought to include both the When sending a no-cache request, a client ought to include both the
pragma and cache-control directives, unless Cache-Control: no-cache pragma and cache-control directives, unless Cache-Control: no-cache
is purposefully omitted to target other Cache-Control request is purposefully omitted to target other Cache-Control request
directives at HTTP/1.1 caches. For example: directives at HTTP/1.1 or greater caches. For example:
GET / HTTP/1.1 GET / HTTP/1.1
Host: www.example.com Host: www.example.com
Cache-Control: max-age=30 Cache-Control: max-age=30
Pragma: no-cache Pragma: no-cache
will constrain HTTP/1.1 caches to serve a response no older than 30 will constrain HTTP/1.1 and greater caches to serve a response no
seconds, while precluding implementations that do not understand older than 30 seconds, while precluding implementations that do not
Cache-Control from serving a cached response. understand Cache-Control from serving a cached response.
Note: Because the meaning of "Pragma: no-cache" in responses is Note: Because the meaning of "Pragma: no-cache" in responses is
not specified, it does not provide a reliable replacement for not specified, it does not provide a reliable replacement for
"Cache-Control: no-cache" in them. "Cache-Control: no-cache" in them.
5.5. Warning 5.5. Warning
The "Warning" header field is used to carry additional information The "Warning" header field was used to carry additional information
about the status or transformation of a message that might not be about the status or transformation of a message that might not be
reflected in the status code. This information is typically used to reflected in the status code. This specification obsoletes it, as it
warn about possible incorrectness introduced by caching operations or is not widely generated or surfaced to users. The information it
transformations applied to the payload of the message. carried can be gleaned from examining other header fields, such as
Age.
Warnings can be used for other purposes, both cache-related and
otherwise. The use of a warning, rather than an error status code,
distinguishes these responses from true failures.
Warning header fields can in general be applied to any message,
however some warn-codes are specific to caches and can only be
applied to response messages.
Warning = 1#warning-value
warning-value = warn-code SP warn-agent SP warn-text
[ SP warn-date ]
warn-code = 3DIGIT
warn-agent = ( uri-host [ ":" port ] ) / pseudonym
; the name or pseudonym of the server adding
; the Warning header field, for use in debugging
; a single "-" is recommended when agent unknown
warn-text = quoted-string
warn-date = DQUOTE HTTP-date DQUOTE
Multiple warnings can be generated in a response (either by the
origin server or by a cache), including multiple warnings with the
same warn-code number that only differ in warn-text.
A user agent that receives one or more Warning header fields SHOULD
inform the user of as many of them as possible, in the order that
they appear in the response. Senders that generate multiple Warning
header fields are encouraged to order them with this user agent
behavior in mind. A sender that generates new Warning header fields
MUST append them after any existing Warning header fields.
Warnings are assigned three digit warn-codes. The first digit
indicates whether the Warning is required to be deleted from a stored
response after validation:
o 1xx warn-codes describe the freshness or validation status of the
response, and so they MUST be deleted by a cache after validation.
They can only be generated by a cache when validating a cached
entry, and MUST NOT be generated in any other situation.
o 2xx warn-codes describe some aspect of the representation that is
not rectified by a validation (for example, a lossy compression of
the representation) and they MUST NOT be deleted by a cache after
validation, unless a full response is sent, in which case they
MUST be.
If a sender generates one or more 1xx warn-codes in a message to be
sent to a recipient known to implement only HTTP/1.0, the sender MUST
include in each corresponding warning-value a warn-date that matches
the Date header field in the message. For example:
HTTP/1.1 200 OK
Date: Sat, 25 Aug 2012 23:34:45 GMT
Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
Warnings have accompanying warn-text that describes the error, e.g.,
for logging. It is advisory only, and its content does not affect
interpretation of the warn-code.
If a recipient that uses, evaluates, or displays Warning header
fields receives a warn-date that is different from the Date value in
the same message, the recipient MUST exclude the warning-value
containing that warn-date before storing, forwarding, or using the
message. This allows recipients to exclude warning-values that were
improperly retained after a cache validation. If all of the warning-
values are excluded, the recipient MUST exclude the Warning header
field as well.
The following warn-codes are defined by this specification, each with
a recommended warn-text in English, and a description of its meaning.
The procedure for defining additional warn codes is described in
Section 5.5.8.
+-----------+----------------------------------+----------------+
| Warn Code | Short Description | Reference |
+-----------+----------------------------------+----------------+
| 110 | Response is Stale | Section 5.5.1 |
| 111 | Revalidation Failed | Section 5.5.2 |
| 112 | Disconnected Operation | Section 5.5.3 |
| 113 | Heuristic Expiration | Section 5.5.4 |
| 199 | Miscellaneous Warning | Section 5.5.5 |
| 214 | Transformation Applied | Section 5.5.6 |
| 299 | Miscellaneous Persistent Warning | Section 5.5.7 |
+-----------+----------------------------------+----------------+
5.5.1. Warning: 110 - "Response is Stale"
A cache SHOULD generate this whenever the sent response is stale.
5.5.2. Warning: 111 - "Revalidation Failed"
A cache SHOULD generate this when sending a stale response because an
attempt to validate the response failed, due to an inability to reach
the server.
5.5.3. Warning: 112 - "Disconnected Operation"
A cache SHOULD generate this if it is intentionally disconnected from
the rest of the network for a period of time.
5.5.4. Warning: 113 - "Heuristic Expiration"
A cache SHOULD generate this if it heuristically chose a freshness
lifetime greater than 24 hours and the response's age is greater than
24 hours.
5.5.5. Warning: 199 - "Miscellaneous Warning"
The warning text can include arbitrary information to be presented to
a human user or logged. A system receiving this warning MUST NOT
take any automated action, besides presenting the warning to the
user.
5.5.6. Warning: 214 - "Transformation Applied"
This Warning code MUST be added by a proxy if it applies any
transformation to the representation, such as changing the content-
coding, media-type, or modifying the representation data, unless this
Warning code already appears in the response.
5.5.7. Warning: 299 - "Miscellaneous Persistent Warning"
The warning text can include arbitrary information to be presented to
a human user or logged. A system receiving this warning MUST NOT
take any automated action.
5.5.8. Warn Code Registry
The "Hypertext Transfer Protocol (HTTP) Warn Codes" registry defines
the namespace for warn codes. It has been created and is now
maintained at <https://www.iana.org/assignments/http-warn-codes>.
A registration MUST include the following fields:
o Warn Code (3 digits)
o Short Description
o Pointer to specification text
Values to be added to this namespace require IETF Review (see
[RFC8126], Section 4.8).
6. History Lists 6. Relationship to Applications
User agents often have history mechanisms, such as "Back" buttons and Applications using HTTP often specify additional forms of caching.
history lists, that can be used to redisplay a representation For example, Web browsers often have history mechanisms such as
"Back" buttons that can be used to redisplay a representation
retrieved earlier in a session. retrieved earlier in a session.
The freshness model (Section 4.2) does not necessarily apply to Likewise, some Web browsers implement caching of images and other
history mechanisms. That is, a history mechanism can display a assets within a page view; they may or may not honor HTTP caching
previous representation even if it has expired. semantics.
This does not prohibit the history mechanism from telling the user The requirements in this specification do not necessarily apply to
that a view might be stale or from honoring cache directives (e.g., how applications use data after it is retrieved from a HTTP cache.
Cache-Control: no-store). That is, a history mechanism can display a previous representation
even if it has expired, and an application can use cached data in
other ways beyond its freshness lifetime.
This does not prohibit the application from taking HTTP caching into
account; for example, a history mechanism might tell the user that a
view is stale, or it might honor cache directives (e.g., Cache-
Control: no-store).
7. Security Considerations 7. Security Considerations
This section is meant to inform developers, information providers, This section is meant to inform developers, information providers,
and users of known security concerns specific to HTTP caching. More and users of known security concerns specific to HTTP caching. More
general security considerations are addressed in HTTP messaging general security considerations are addressed in HTTP messaging
[Messaging] and semantics [Semantics]. [Messaging] and semantics [Semantics].
Caches expose additional potential vulnerabilities, since the Caches expose additional potential vulnerabilities, since the
contents of the cache represent an attractive target for malicious contents of the cache represent an attractive target for malicious
skipping to change at page 36, line 24 skipping to change at page 32, line 38
headers> with the header field names listed in the table of headers> with the header field names listed in the table of
Section 5. Section 5.
8.2. Cache Directive Registration 8.2. Cache Directive Registration
Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive Please update the "Hypertext Transfer Protocol (HTTP) Cache Directive
Registry" at <https://www.iana.org/assignments/http-cache-directives> Registry" at <https://www.iana.org/assignments/http-cache-directives>
with the registration procedure of Section 5.2.4 and the cache with the registration procedure of Section 5.2.4 and the cache
directive names summarized in the table of Section 5.2. directive names summarized in the table of Section 5.2.
8.3. Warn Code Registration 8.3. Warn Code Registry
Please update the "Hypertext Transfer Protocol (HTTP) Warn Codes" Please add a note to the "Hypertext Transfer Protocol (HTTP) Warn
registry at <https://www.iana.org/assignments/http-warn-codes> with Codes" registry at <https://www.iana.org/assignments/http-warn-codes>
the registration procedure of Section 5.5.8 and the warn code values to the effect that Warning is obsoleted.
summarized in the table of Section 5.5.
9. References 9. References
9.1. Normative References 9.1. Normative References
[Messaging] [Messaging]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-02 Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-03
(work in progress), July 2018. (work in progress), October 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008, DOI 10.17487/RFC5234, January 2008,
<https://www.rfc-editor.org/info/rfc5234>. <https://www.rfc-editor.org/info/rfc5234>.
[Semantics] [Semantics]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-02 Ed., "HTTP Semantics", draft-ietf-httpbis-semantics-03
(work in progress), July 2018. (work in progress), October 2018.
[USASCII] American National Standards Institute, "Coded Character [USASCII] American National Standards Institute, "Coded Character
Set -- 7-bit American Standard Code for Information Set -- 7-bit American Standard Code for Information
Interchange", ANSI X3.4, 1986. Interchange", ANSI X3.4, 1986.
9.2. Informative References 9.2. Informative References
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, Transfer Protocol -- HTTP/1.1", RFC 2616,
skipping to change at page 38, line 24 skipping to change at page 35, line 24
Expires = HTTP-date Expires = HTTP-date
HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1> HTTP-date = <HTTP-date, see [Semantics], Section 10.1.1.1>
OWS = <OWS, see [Semantics], Section 4.3> OWS = <OWS, see [Semantics], Section 4.3>
Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
pragma-directive ] ) pragma-directive ] )
Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
)
cache-directive = token [ "=" ( token / quoted-string ) ] cache-directive = token [ "=" ( token / quoted-string ) ]
delta-seconds = 1*DIGIT delta-seconds = 1*DIGIT
extension-pragma = token [ "=" ( token / quoted-string ) ] extension-pragma = token [ "=" ( token / quoted-string ) ]
field-name = <field-name, see [Semantics], Section 4.2> field-name = <field-name, see [Semantics], Section 4.2>
port = <port, see [RFC3986], Section 3.2.3> port = <port, see [RFC3986], Section 3.2.3>
pragma-directive = "no-cache" / extension-pragma pragma-directive = "no-cache" / extension-pragma
pseudonym = <pseudonym, see [Semantics], Section 5.6.1> pseudonym = <pseudonym, see [Semantics], Section 5.5.1>
quoted-string = <quoted-string, see [Semantics], Section 4.2.3> quoted-string = <quoted-string, see [Semantics], Section 4.2.3>
token = <token, see [Semantics], Section 4.2.3> token = <token, see [Semantics], Section 4.2.3>
uri-host = <host, see [RFC3986], Section 3.2.2> uri-host = <host, see [RFC3986], Section 3.2.2>
warn-agent = ( uri-host [ ":" port ] ) / pseudonym
warn-code = 3DIGIT
warn-date = DQUOTE HTTP-date DQUOTE
warn-text = quoted-string
warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
]
Appendix B. Changes from RFC 7234 Appendix B. Changes from RFC 7234
None yet. The Warning response header was obsoleted. Much of the information
supported by Warning could be gleaned by examining the response), and
the remaining warn-codes -- although potentially useful -- were
entirely advisory, and in practice were not added by caches or
intermediaries. (Section 5.5)
Appendix C. Change Log Appendix C. Change Log
This section is to be removed before publishing as an RFC. This section is to be removed before publishing as an RFC.
C.1. Between RFC7234 and draft 00 C.1. Between RFC7234 and draft 00
The changes were purely editorial: The changes were purely editorial:
o Change boilerplate and abstract to indicate the "draft" status, o Change boilerplate and abstract to indicate the "draft" status,
skipping to change at page 40, line 5 skipping to change at page 36, line 48
C.3. Since draft-ietf-httpbis-cache-01 C.3. Since draft-ietf-httpbis-cache-01
o Cite RFC 8126 instead of RFC 5226 (<https://github.com/httpwg/ o Cite RFC 8126 instead of RFC 5226 (<https://github.com/httpwg/
http-core/issues/75>) http-core/issues/75>)
o In Section 5.4, misleading statement about the relation between o In Section 5.4, misleading statement about the relation between
Pragma and Cache-Control (<https://github.com/httpwg/http-core/ Pragma and Cache-Control (<https://github.com/httpwg/http-core/
issues/92>, <https://www.rfc-editor.org/errata/eid4674>) issues/92>, <https://www.rfc-editor.org/errata/eid4674>)
Index C.4. Since draft-ietf-httpbis-cache-02
1 o In Section 3, explain that only final responses are cacheable
110 (warn-code) 33 (<https://github.com/httpwg/http-core/issues/29>)
111 (warn-code) 33
112 (warn-code) 33
113 (warn-code) 34
199 (warn-code) 34
2 o In Section 5.2.2, clarify what responses various directives apply
214 (warn-code) 34 to (<https://github.com/httpwg/http-core/issues/52>)
299 (warn-code) 34
o In Section 4.3.1, clarify the source of validators in conditional
requests (<https://github.com/httpwg/http-core/issues/110>)
o Revise Section 6 to apply to more than just History Lists
(<https://github.com/httpwg/http-core/issues/126>)
o In Section 5.5, deprecated "Warning" header field
(<https://github.com/httpwg/http-core/issues/139>)
o In Section 3.2, remove a spurious note
(<https://github.com/httpwg/http-core/issues/141>)
Index
A A
Age header field 21 Age header field 21
age 11 age 11
C C
Cache-Control header field 22 Cache-Control header field 21
cache 4 cache 4
cache entry 6 cache entry 6
cache key 6 cache key 6
D
Disconnected Operation (warn-text) 33
E E
Expires header field 29 Expires header field 29
explicit expiration time 11 explicit expiration time 11
F F
fresh 11 fresh 11
freshness lifetime 11 freshness lifetime 11
G G
Grammar Grammar
Age 21 Age 21
ALPHA 5 ALPHA 5
Cache-Control 22 Cache-Control 21
cache-directive 22 cache-directive 21
CR 5 CR 5
CRLF 5 CRLF 5
CTL 5 CTL 5
delta-seconds 5 delta-seconds 5
DIGIT 5 DIGIT 5
DQUOTE 5 DQUOTE 5
Expires 30 Expires 29
extension-pragma 31 extension-pragma 30
HEXDIG 5 HEXDIG 5
HTAB 5 HTAB 5
LF 5 LF 5
OCTET 5 OCTET 5
Pragma 31 Pragma 30
pragma-directive 31 pragma-directive 30
SP 5 SP 5
VCHAR 5 VCHAR 5
warn-agent 32
warn-code 32
warn-date 32
warn-text 32
Warning 32
warning-value 32
H H
Heuristic Expiration (warn-text) 34
heuristic expiration time 11 heuristic expiration time 11
M M
Miscellaneous Persistent Warning (warn-text) 34 max-age (cache directive) 22, 27
Miscellaneous Warning (warn-text) 34 max-stale (cache directive) 22
max-age (cache directive) 23, 28 min-fresh (cache directive) 23
max-stale (cache directive) 23 must-revalidate (cache directive) 24
min-fresh (cache directive) 24
must-revalidate (cache directive) 25
N N
no-cache (cache directive) 24-25 no-cache (cache directive) 23-24
no-store (cache directive) 24, 26 no-store (cache directive) 23, 25
no-transform (cache directive) 25-26 no-transform (cache directive) 24, 26
O O
only-if-cached (cache directive) 25 only-if-cached (cache directive) 24
P P
Pragma header field 30 Pragma header field 30
private (cache directive) 27 private (cache directive) 26
private cache 4 private cache 4
proxy-revalidate (cache directive) 27 proxy-revalidate (cache directive) 27
public (cache directive) 27 public (cache directive) 26
R
Response is Stale (warn-text) 33
Revalidation Failed (warn-text) 33
S S
s-maxage (cache directive) 28 s-maxage (cache directive) 27
shared cache 4 shared cache 4
stale 11 stale 11
strong validator 19 strong validator 18
T
Transformation Applied (warn-text) 34
V V
validator 16 validator 16
W W
Warning header field 31 Warning header field 30
Acknowledgments Acknowledgments
See Appendix "Acknowledgments" of [Semantics]. See Appendix "Acknowledgments" of [Semantics].
Authors' Addresses Authors' Addresses
Roy T. Fielding (editor) Roy T. Fielding (editor)
Adobe Adobe
345 Park Ave 345 Park Ave
 End of changes. 71 change blocks. 
392 lines changed or deleted 222 lines changed or added

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