idnits 2.17.1
draft-ietf-httpbis-p6-cache-15.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document seems to contain a disclaimer for pre-RFC5378 work, and may
have content which was first submitted before 10 November 2008. The
disclaimer is necessary when there are original authors that you have
been unable to contact, or if some do not wish to grant the BCP78 rights
to the IETF Trust. If you are able to get all authors (current and
original) to grant those rights, you can and should remove the
disclaimer; otherwise, the disclaimer is needed and you can ignore this
comment. (See the Legal Provisions document at
https://trustee.ietf.org/license-info for more information.)
-- The document date (July 11, 2011) is 4672 days in the past. Is this
intentional?
Checking references for intended status: Proposed Standard
----------------------------------------------------------------------------
(See RFCs 3967 and 4897 for information about using normative references
to lower-maturity documents in RFCs)
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p1-messaging-15
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p2-semantics-15
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p4-conditional-15
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p5-range-15
== Outdated reference: A later version (-26) exists of
draft-ietf-httpbis-p7-auth-15
-- Obsolete informational reference (is this intentional?): RFC 1305
(Obsoleted by RFC 5905)
-- Obsolete informational reference (is this intentional?): RFC 2616
(Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235)
-- Obsolete informational reference (is this intentional?): RFC 5226
(Obsoleted by RFC 8126)
Summary: 0 errors (**), 0 flaws (~~), 6 warnings (==), 5 comments (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 HTTPbis Working Group R. Fielding, Ed.
3 Internet-Draft Adobe
4 Obsoletes: 2616 (if approved) J. Gettys
5 Intended status: Standards Track Alcatel-Lucent
6 Expires: January 12, 2012 J. Mogul
7 HP
8 H. Frystyk
9 Microsoft
10 L. Masinter
11 Adobe
12 P. Leach
13 Microsoft
14 T. Berners-Lee
15 W3C/MIT
16 Y. Lafon, Ed.
17 W3C
18 M. Nottingham, Ed.
20 J. Reschke, Ed.
21 greenbytes
22 July 11, 2011
24 HTTP/1.1, part 6: Caching
25 draft-ietf-httpbis-p6-cache-15
27 Abstract
29 The Hypertext Transfer Protocol (HTTP) is an application-level
30 protocol for distributed, collaborative, hypermedia information
31 systems. This document is Part 6 of the seven-part specification
32 that defines the protocol referred to as "HTTP/1.1" and, taken
33 together, obsoletes RFC 2616. Part 6 defines requirements on HTTP
34 caches and the associated header fields that control cache behavior
35 or indicate cacheable response messages.
37 Editorial Note (To be removed by RFC Editor)
39 Discussion of this draft should take place on the HTTPBIS working
40 group mailing list (ietf-http-wg@w3.org), which is archived at
41 .
43 The current issues list is at
44 and related
45 documents (including fancy diffs) can be found at
46 .
48 The changes in this draft are summarized in Appendix C.16.
50 Status of This Memo
52 This Internet-Draft is submitted in full conformance with the
53 provisions of BCP 78 and BCP 79.
55 Internet-Drafts are working documents of the Internet Engineering
56 Task Force (IETF). Note that other groups may also distribute
57 working documents as Internet-Drafts. The list of current Internet-
58 Drafts is at http://datatracker.ietf.org/drafts/current/.
60 Internet-Drafts are draft documents valid for a maximum of six months
61 and may be updated, replaced, or obsoleted by other documents at any
62 time. It is inappropriate to use Internet-Drafts as reference
63 material or to cite them other than as "work in progress."
65 This Internet-Draft will expire on January 12, 2012.
67 Copyright Notice
69 Copyright (c) 2011 IETF Trust and the persons identified as the
70 document authors. All rights reserved.
72 This document is subject to BCP 78 and the IETF Trust's Legal
73 Provisions Relating to IETF Documents
74 (http://trustee.ietf.org/license-info) in effect on the date of
75 publication of this document. Please review these documents
76 carefully, as they describe your rights and restrictions with respect
77 to this document. Code Components extracted from this document must
78 include Simplified BSD License text as described in Section 4.e of
79 the Trust Legal Provisions and are provided without warranty as
80 described in the Simplified BSD License.
82 This document may contain material from IETF Documents or IETF
83 Contributions published or made publicly available before November
84 10, 2008. The person(s) controlling the copyright in some of this
85 material may not have granted the IETF Trust the right to allow
86 modifications of such material outside the IETF Standards Process.
87 Without obtaining an adequate license from the person(s) controlling
88 the copyright in such materials, this document may not be modified
89 outside the IETF Standards Process, and derivative works of it may
90 not be created outside the IETF Standards Process, except to format
91 it for publication as an RFC or to translate it into languages other
92 than English.
94 Table of Contents
96 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5
97 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5
98 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5
99 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7
100 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7
101 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7
102 1.4.2. ABNF Rules defined in other Parts of the
103 Specification . . . . . . . . . . . . . . . . . . . . 7
104 1.5. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 8
105 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 8
106 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 8
107 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 9
108 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9
109 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10
110 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11
111 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12
112 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 14
113 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14
114 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 15
115 2.6. Shared Caching of Authenticated Responses . . . . . . . . 16
116 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16
117 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 17
118 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 18
119 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
120 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18
121 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19
122 3.2.2. Response Cache-Control Directives . . . . . . . . . . 21
123 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23
124 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24
125 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25
126 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
127 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 27
128 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29
129 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29
130 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29
131 5.2. Header Field Registration . . . . . . . . . . . . . . . . 30
132 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30
133 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31
134 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31
135 8.1. Normative References . . . . . . . . . . . . . . . . . . . 31
136 8.2. Informative References . . . . . . . . . . . . . . . . . . 32
137 Appendix A. Changes from RFC 2616 . . . . . . . . . . . . . . . . 32
138 Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32
139 Appendix C. Change Log (to be removed by RFC Editor before
140 publication) . . . . . . . . . . . . . . . . . . . . 34
141 C.1. Since RFC 2616 . . . . . . . . . . . . . . . . . . . . . . 34
142 C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34
143 C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35
144 C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35
145 C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35
146 C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35
147 C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36
148 C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36
149 C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36
150 C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37
151 C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37
152 C.12. Since draft-ietf-httpbis-p6-cache-10 . . . . . . . . . . . 38
153 C.13. Since draft-ietf-httpbis-p6-cache-11 . . . . . . . . . . . 38
154 C.14. Since draft-ietf-httpbis-p6-cache-12 . . . . . . . . . . . 38
155 C.15. Since draft-ietf-httpbis-p6-cache-13 . . . . . . . . . . . 38
156 C.16. Since draft-ietf-httpbis-p6-cache-14 . . . . . . . . . . . 38
157 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
159 1. Introduction
161 HTTP is typically used for distributed information systems, where
162 performance can be improved by the use of response caches. This
163 document defines aspects of HTTP/1.1 related to caching and reusing
164 response messages.
166 1.1. Purpose
168 An HTTP cache is a local store of response messages and the subsystem
169 that controls its message storage, retrieval, and deletion. A cache
170 stores cacheable responses in order to reduce the response time and
171 network bandwidth consumption on future, equivalent requests. Any
172 client or server MAY employ a cache, though a cache cannot be used by
173 a server that is acting as a tunnel.
175 Caching would be useless if it did not significantly improve
176 performance. The goal of caching in HTTP/1.1 is to reuse a prior
177 response message to satisfy a current request. In some cases, a
178 stored response can be reused without the need for a network request,
179 reducing latency and network round-trips; a "freshness" mechanism is
180 used for this purpose (see Section 2.3). Even when a new request is
181 required, it is often possible to reuse all or parts of the payload
182 of a prior response to satisfy the request, thereby reducing network
183 bandwidth usage; a "validation" mechanism is used for this purpose
184 (see Section 2.4).
186 1.2. Terminology
188 This specification uses a number of terms to refer to the roles
189 played by participants in, and objects of, HTTP caching.
191 cache
193 A conformant implementation of a HTTP cache. Note that this
194 implies an HTTP/1.1 cache; this specification does not define
195 conformance for HTTP/1.0 caches.
197 shared cache
199 A cache that is accessible to more than one user; usually (but not
200 always) deployed as part of an intermediary.
202 private cache
204 A cache that is dedicated to a single user.
206 cacheable
208 A response is cacheable if a cache is allowed to store a copy of
209 the response message for use in answering subsequent requests.
210 Even when a response is cacheable, there might be additional
211 constraints on whether a cache can use the stored copy to satisfy
212 a particular request.
214 explicit expiration time
216 The time at which the origin server intends that a representation
217 no longer be returned by a cache without further validation.
219 heuristic expiration time
221 An expiration time assigned by a cache when no explicit expiration
222 time is available.
224 age
226 The age of a response is the time since it was sent by, or
227 successfully validated with, the origin server.
229 first-hand
231 A response is first-hand if the freshness model is not in use;
232 i.e., its age is 0.
234 freshness lifetime
236 The length of time between the generation of a response and its
237 expiration time.
239 fresh
241 A response is fresh if its age has not yet exceeded its freshness
242 lifetime.
244 stale
246 A response is stale if its age has passed its freshness lifetime
247 (either explicit or heuristic).
249 validator
251 A protocol element (e.g., an entity-tag or a Last-Modified time)
252 that is used to find out whether a stored response is an
253 equivalent copy of a representation.
255 1.3. Requirements
257 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
258 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
259 document are to be interpreted as described in [RFC2119].
261 An implementation is not compliant if it fails to satisfy one or more
262 of the "MUST" or "REQUIRED" level requirements for the protocols it
263 implements. An implementation that satisfies all the "MUST" or
264 "REQUIRED" level and all the "SHOULD" level requirements for its
265 protocols is said to be "unconditionally compliant"; one that
266 satisfies all the "MUST" level requirements but not all the "SHOULD"
267 level requirements for its protocols is said to be "conditionally
268 compliant".
270 1.4. Syntax Notation
272 This specification uses the ABNF syntax defined in Section 1.2 of
273 [Part1] (which extends the syntax defined in [RFC5234] with a list
274 rule). Appendix B shows the collected ABNF, with the list rule
275 expanded.
277 The following core rules are included by reference, as defined in
278 [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF
279 (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote),
280 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit
281 sequence of data), SP (space), VCHAR (any visible USASCII character),
282 and WSP (whitespace).
284 1.4.1. Core Rules
286 The core rules below are defined in Section 1.2.2 of [Part1]:
288 quoted-string =
289 token =
290 OWS =
292 1.4.2. ABNF Rules defined in other Parts of the Specification
294 The ABNF rules below are defined in other parts:
296 field-name =
297 HTTP-date =
298 port =
299 pseudonym =
300 uri-host =
302 1.5. Delta Seconds
304 The delta-seconds rule specifies a non-negative integer, representing
305 time in seconds.
307 delta-seconds = 1*DIGIT
309 If an implementation receives a delta-seconds value larger than the
310 largest positive integer it can represent, or if any of its
311 subsequent calculations overflows, it MUST consider the value to be
312 2147483648 (2^31). Recipients parsing a delta-seconds value SHOULD
313 use an arithmetic type of at least 31 bits of range, and senders MUST
314 NOT send delta-seconds with a value greater than 2147483648.
316 2. Cache Operation
318 2.1. Response Cacheability
320 A cache MUST NOT store a response to any request, unless:
322 o The request method is understood by the cache and defined as being
323 cacheable, and
325 o the response status code is understood by the cache, and
327 o the "no-store" cache directive (see Section 3.2) does not appear
328 in request or response header fields, and
330 o the "private" cache response directive (see Section 3.2.2 does not
331 appear in the response, if the cache is shared, and
333 o the "Authorization" header field (see Section 4.1 of [Part7]) does
334 not appear in the request, if the cache is shared, unless the
335 response explicitly allows it (see Section 2.6), and
337 o the response either:
339 * contains an Expires header field (see Section 3.3), or
341 * contains a max-age response cache directive (see
342 Section 3.2.2), or
344 * contains a s-maxage response cache directive and the cache is
345 shared, or
347 * contains a Cache Control Extension (see Section 3.2.3) that
348 allows it to be cached, or
350 * has a status code that can be served with heuristic freshness
351 (see Section 2.3.1.1).
353 Note that any of the requirements listed above can be overridden by a
354 cache-control extension; see Section 3.2.3.
356 In this context, a cache has "understood" a request method or a
357 response status code if it recognises it and implements any cache-
358 specific behavior. In particular, 206 Partial Content responses
359 cannot be cached by an implementation that does not handle partial
360 content (see Section 2.1.1).
362 Note that in normal operation, most caches will not store a response
363 that has neither a cache validator nor an explicit expiration time,
364 as such responses are not usually useful to store. However, caches
365 are not prohibited from storing such responses.
367 2.1.1. Storing Partial and Incomplete Responses
369 A cache that receives an incomplete response (for example, with fewer
370 bytes of data than specified in a Content-Length header field) can
371 store the response, but MUST treat it as a partial response [Part5].
372 Partial responses can be combined as described in Section 4 of
373 [Part5]; the result might be a full response or might still be
374 partial. A cache MUST NOT return a partial response to a client
375 without explicitly marking it as such using the 206 (Partial Content)
376 status code.
378 A cache that does not support the Range and Content-Range header
379 fields MUST NOT store incomplete or partial responses.
381 2.2. Constructing Responses from Caches
383 For a presented request, a cache MUST NOT return a stored response,
384 unless:
386 o The presented effective request URI (Section 4.3 of [Part1]) and
387 that of the stored response match, and
389 o the request method associated with the stored response allows it
390 to be used for the presented request, and
392 o selecting header fields nominated by the stored response (if any)
393 match those presented (see Section 2.7), and
395 o the presented request and stored response are free from directives
396 that would prevent its use (see Section 3.2 and Section 3.4), and
398 o the stored response is either:
400 * fresh (see Section 2.3), or
402 * allowed to be served stale (see Section 2.3.3), or
404 * successfully validated (see Section 2.4).
406 Note that any of the requirements listed above can be overridden by a
407 cache-control extension; see Section 3.2.3.
409 When a stored response is used to satisfy a request without
410 validation, a cache MUST include a single Age header field
411 (Section 3.1) in the response with a value equal to the stored
412 response's current_age; see Section 2.3.2.
414 A cache MUST write through requests with methods that are unsafe
415 (Section 7.1.1 of [Part2]) to the origin server; i.e., a cache must
416 not generate a reply to such a request before having forwarded the
417 request and having received a corresponding response.
419 Also, note that unsafe requests might invalidate already stored
420 responses; see Section 2.5.
422 When more than one suitable response is stored, a cache MUST use the
423 most recent response (as determined by the Date header field). It
424 can also forward a request with "Cache-Control: max-age=0" or "Cache-
425 Control: no-cache" to disambiguate which response to use.
427 A cache that does not have a clock available MUST NOT use stored
428 responses without revalidating them on every use. A cache,
429 especially a shared cache, SHOULD use a mechanism, such as NTP
430 [RFC1305], to synchronize its clock with a reliable external
431 standard.
433 2.3. Freshness Model
435 When a response is "fresh" in the cache, it can be used to satisfy
436 subsequent requests without contacting the origin server, thereby
437 improving efficiency.
439 The primary mechanism for determining freshness is for an origin
440 server to provide an explicit expiration time in the future, using
441 either the Expires header field (Section 3.3) or the max-age response
442 cache directive (Section 3.2.2). Generally, origin servers will
443 assign future explicit expiration times to responses in the belief
444 that the representation is not likely to change in a semantically
445 significant way before the expiration time is reached.
447 If an origin server wishes to force a cache to validate every
448 request, it can assign an explicit expiration time in the past to
449 indicate that the response is already stale. Compliant caches will
450 normally validate the cached response before reusing it for
451 subsequent requests (see Section 2.3.3).
453 Since origin servers do not always provide explicit expiration times,
454 a cache MAY assign a heuristic expiration time when an explicit time
455 is not specified, employing algorithms that use other header field
456 values (such as the Last-Modified time) to estimate a plausible
457 expiration time. This specification does not provide specific
458 algorithms, but does impose worst-case constraints on their results.
460 The calculation to determine if a response is fresh is:
462 response_is_fresh = (freshness_lifetime > current_age)
464 The freshness_lifetime is defined in Section 2.3.1; the current_age
465 is defined in Section 2.3.2.
467 Additionally, clients might need to influence freshness calculation.
468 They can do this using several request cache directives, with the
469 effect of either increasing or loosening constraints on freshness.
470 See Section 3.2.1.
472 Note that freshness applies only to cache operation; it cannot be
473 used to force a user agent to refresh its display or reload a
474 resource. See Section 4 for an explanation of the difference between
475 caches and history mechanisms.
477 2.3.1. Calculating Freshness Lifetime
479 A cache can calculate the freshness lifetime (denoted as
480 freshness_lifetime) of a response by using the first match of:
482 o If the cache is shared and the s-maxage response cache directive
483 (Section 3.2.2) is present, use its value, or
485 o If the max-age response cache directive (Section 3.2.2) is
486 present, use its value, or
488 o If the Expires response header field (Section 3.3) is present, use
489 its value minus the value of the Date response header field, or
491 o Otherwise, no explicit expiration time is present in the response.
492 A heuristic freshness lifetime might be applicable; see
493 Section 2.3.1.1.
495 Note that this calculation is not vulnerable to clock skew, since all
496 of the information comes from the origin server.
498 2.3.1.1. Calculating Heuristic Freshness
500 If no explicit expiration time is present in a stored response that
501 has a status code whose definition allows heuristic freshness to be
502 used (including the following in Section 8 of [Part2]: 200, 203, 206,
503 300, 301 and 410), a cache MAY calculate a heuristic expiration time.
504 A cache MUST NOT use heuristics to determine freshness for responses
505 with status codes that do not explicitly allow it.
507 When a heuristic is used to calculate freshness lifetime, a cache
508 SHOULD attach a Warning header field with a 113 warn-code to the
509 response if its current_age is more than 24 hours and such a warning
510 is not already present.
512 Also, if the response has a Last-Modified header field (Section 2.1
513 of [Part4]), a cache SHOULD NOT use a heuristic expiration value that
514 is more than some fraction of the interval since that time. A
515 typical setting of this fraction might be 10%.
517 Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do
518 not calculate heuristic freshness for URIs with query components
519 (i.e., those containing '?'). In practice, this has not been
520 widely implemented. Therefore, servers are encouraged to send
521 explicit directives (e.g., Cache-Control: no-cache) if they wish
522 to preclude caching.
524 2.3.2. Calculating Age
526 HTTP/1.1 uses the Age header field to convey the estimated age of the
527 response message when obtained from a cache. The Age field value is
528 the cache's estimate of the amount of time since the response was
529 generated or validated by the origin server. In essence, the Age
530 value is the sum of the time that the response has been resident in
531 each of the caches along the path from the origin server, plus the
532 amount of time it has been in transit along network paths.
534 The following data is used for the age calculation:
536 age_value
538 The term "age_value" denotes the value of the Age header field
539 (Section 3.1), in a form appropriate for arithmetic operation; or
540 0, if not available.
542 date_value
544 HTTP/1.1 requires origin servers to send a Date header field, if
545 possible, with every response, giving the time at which the
546 response was generated. The term "date_value" denotes the value
547 of the Date header field, in a form appropriate for arithmetic
548 operations. See Section 9.3 of [Part1] for the definition of the
549 Date header field, and for requirements regarding responses
550 without it.
552 now
554 The term "now" means "the current value of the clock at the host
555 performing the calculation". A cache SHOULD use NTP ([RFC1305])
556 or some similar protocol to synchronize its clocks to a globally
557 accurate time standard.
559 request_time
561 The current value of the clock at the host at the time the request
562 resulting in the stored response was made.
564 response_time
566 The current value of the clock at the host at the time the
567 response was received.
569 A response's age can be calculated in two entirely independent ways:
571 1. the "apparent_age": response_time minus date_value, if the local
572 clock is reasonably well synchronized to the origin server's
573 clock. If the result is negative, the result is replaced by
574 zero.
576 2. the "corrected_age_value", if all of the caches along the
577 response path implement HTTP/1.1. A cache MUST interpret this
578 value relative to the time the request was initiated, not the
579 time that the response was received.
581 apparent_age = max(0, response_time - date_value);
583 response_delay = response_time - request_time;
584 corrected_age_value = age_value + response_delay;
586 These are combined as
588 corrected_initial_age = max(apparent_age, corrected_age_value);
590 The current_age of a stored response can then be calculated by adding
591 the amount of time (in seconds) since the stored response was last
592 validated by the origin server to the corrected_initial_age.
594 resident_time = now - response_time;
595 current_age = corrected_initial_age + resident_time;
597 2.3.3. Serving Stale Responses
599 A "stale" response is one that either has explicit expiry information
600 or is allowed to have heuristic expiry calculated, but is not fresh
601 according to the calculations in Section 2.3.
603 A cache MUST NOT return a stale response if it is prohibited by an
604 explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
605 cache directive, a "must-revalidate" cache-response-directive, or an
606 applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
607 see Section 3.2.2).
609 A cache SHOULD NOT return stale responses unless it is disconnected
610 (i.e., it cannot contact the origin server or otherwise find a
611 forward path) or doing so is explicitly allowed (e.g., by the max-
612 stale request directive; see Section 3.2.1).
614 A cache SHOULD append a Warning header field with the 110 warn-code
615 (see Section 3.6) to stale responses. Likewise, a cache SHOULD add
616 the 112 warn-code to stale responses if the cache is disconnected.
618 If a cache receives a first-hand response (either an entire response,
619 or a 304 (Not Modified) response) that it would normally forward to
620 the requesting client, and the received response is no longer fresh,
621 the cache SHOULD forward it to the requesting client without adding a
622 new Warning (but without removing any existing Warning header
623 fields). A cache SHOULD NOT attempt to validate a response simply
624 because that response became stale in transit.
626 2.4. Validation Model
628 When a cache has one or more stored responses for a requested URI,
629 but cannot serve any of them (e.g., because they are not fresh, or
630 one cannot be selected; see Section 2.7), it can use the conditional
631 request mechanism [Part4] in the forwarded request to give the origin
632 server an opportunity to both select a valid stored response to be
633 used, and to update it. This process is known as "validating" or
634 "revalidating" the stored response.
636 When sending such a conditional request, a cache SHOULD add an If-
637 Modified-Since header field whose value is that of the Last-Modified
638 header field from the selected (see Section 2.7) stored response, if
639 available.
641 Additionally, a cache SHOULD add an If-None-Match header field whose
642 value is that of the ETag header field(s) from all responses stored
643 for the requested URI, if present. However, if any of the stored
644 responses contains only partial content, the cache SHOULD NOT include
645 its entity-tag in the If-None-Match header field unless the request
646 is for a range that would be fully satisfied by that stored response.
648 A 304 (Not Modified) response status code indicates that the stored
649 response can be updated and reused; see Section 2.8.
651 A full response (i.e., one with a response body) indicates that none
652 of the stored responses nominated in the conditional request is
653 suitable. Instead, a cache SHOULD use the full response to satisfy
654 the request and MAY replace the stored response.
656 If a cache receives a 5xx response while attempting to validate a
657 response, it MAY either forward this response to the requesting
658 client, or act as if the server failed to respond. In the latter
659 case, it MAY return a previously stored response (see Section 2.3.3).
661 2.5. Request Methods that Invalidate
663 Because unsafe request methods (Section 7.1.1 of [Part2]) such as
664 PUT, POST or DELETE have the potential for changing state on the
665 origin server, intervening caches can use them to keep their contents
666 up-to-date.
668 A cache MUST invalidate the effective Request URI (Section 4.3 of
669 [Part1]) as well as the URI(s) in the Location and Content-Location
670 header fields (if present) when a non-error response to a request
671 with an unsafe method is received.
673 However, a cache MUST NOT invalidate a URI from a Location or
674 Content-Location header field if the host part of that URI differs
675 from the host part in the effective request URI (Section 4.3 of
676 [Part1]). This helps prevent denial of service attacks.
678 A cache SHOULD invalidate the effective request URI (Section 4.3 of
679 [Part1]) when it receives a non-error response to a request with a
680 method whose safety is unknown.
682 Here, a "non-error response" is one with a 2xx or 3xx status code.
683 "Invalidate" means that the cache will either remove all stored
684 responses related to the effective request URI, or will mark these as
685 "invalid" and in need of a mandatory validation before they can be
686 returned in response to a subsequent request.
688 Note that this does not guarantee that all appropriate responses are
689 invalidated. For example, the request that caused the change at the
690 origin server might not have gone through the cache where a response
691 is stored.
693 2.6. Shared Caching of Authenticated Responses
695 A shared cache MUST NOT use a cached response to a request with an
696 Authorization header field (Section 4.1 of [Part7]) to satisfy any
697 subsequent request unless a cache directive that allows such
698 responses to be stored is present in the response.
700 In this specification, the following Cache-Control response
701 directives (Section 3.2.2) have such an effect: must-revalidate,
702 public, s-maxage.
704 Note that cached responses that contain the "must-revalidate" and/or
705 "s-maxage" response directives are not allowed to be served stale
706 (Section 2.3.3) by shared caches. In particular, a response with
707 either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
708 satisfy a subsequent request without revalidating it on the origin
709 server.
711 2.7. Caching Negotiated Responses
713 When a cache receives a request that can be satisfied by a stored
714 response that has a Vary header field (Section 3.5), it MUST NOT use
715 that response unless all of the selecting header fields nominated by
716 the Vary header field match in both the original request (i.e., that
717 associated with the stored response), and the presented request.
719 The selecting header fields from two requests are defined to match if
720 and only if those in the first request can be transformed to those in
721 the second request by applying any of the following:
723 o adding or removing whitespace, where allowed in the header field's
724 syntax
726 o combining multiple header fields with the same field name (see
727 Section 3.2 of [Part1])
729 o normalizing both header field values in a way that is known to
730 have identical semantics, according to the header field's
731 specification (e.g., re-ordering field values when order is not
732 significant; case-normalization, where values are defined to be
733 case-insensitive)
735 If (after any normalization that might take place) a header field is
736 absent from a request, it can only match another request if it is
737 also absent there.
739 A Vary header field-value of "*" always fails to match, and
740 subsequent requests to that resource can only be properly interpreted
741 by the origin server.
743 The stored response with matching selecting header fields is known as
744 the selected response.
746 If multiple selected responses are available, the most recent
747 response (as determined by the Date header field) is used; see
748 Section 2.2.
750 If no selected response is available, the cache MAY forward the
751 presented request to the origin server in a conditional request; see
752 Section 2.4.
754 2.8. Combining Responses
756 When a cache receives a 304 (Not Modified) response or a 206 (Partial
757 Content) response (in this section, the "new" response"), it needs to
758 create an updated response by combining the stored response with the
759 new one, so that the updated response can be used to satisfy the
760 request, and potentially update the cached response.
762 If the new response contains an ETag, it identifies the stored
763 response to use. [[TODO-mention-CL: might need language about
764 Content-Location here]][[TODO-select-for-combine: Shouldn't this be
765 the selected response?]]
767 When the new response's status code is 206 (partial content), a cache
768 MUST NOT combine it with the old response if either response does not
769 have a validator, and MUST NOT combine it with the old response when
770 those validators do not match with the strong comparison function
771 (see Section 2.2.2 of [Part4]).
773 The stored response header fields are used as those of the updated
774 response, except that
775 o a cache MUST delete any stored Warning header fields with warn-
776 code 1xx (see Section 3.6).
778 o a cache MUST retain any stored Warning header fields with warn-
779 code 2xx.
781 o a cache MUST use other header fields provided in the new response
782 to replace all instances of the corresponding header fields from
783 the stored response.
785 A cache MUST use the updated response header fields to replace those
786 of the stored response (unless the stored response is removed). In
787 the case of a 206 response, a cache MAY store the combined
788 representation.
790 3. Header Field Definitions
792 This section defines the syntax and semantics of HTTP/1.1 header
793 fields related to caching.
795 3.1. Age
797 The "Age" header field conveys the sender's estimate of the amount of
798 time since the response was generated or successfully validated at
799 the origin server. Age values are calculated as specified in
800 Section 2.3.2.
802 Age = delta-seconds
804 Age field-values are non-negative integers, representing time in
805 seconds (see Section 1.5).
807 The presence of an Age header field in a response implies that a
808 response is not first-hand. However, the converse is not true, since
809 HTTP/1.0 caches might not implement the Age header field.
811 3.2. Cache-Control
813 The "Cache-Control" header field is used to specify directives for
814 caches along the request/response chain. Such cache directives are
815 unidirectional in that the presence of a directive in a request does
816 not imply that the same directive is to be given in the response.
818 A cache MUST obey the requirements of the Cache-Control directives
819 defined in this section. See Section 3.2.3 for information about how
820 Cache-Control directives defined elsewhere are handled.
822 Note: HTTP/1.0 caches might not implement Cache-Control and might
823 only implement Pragma: no-cache (see Section 3.4).
825 A proxy, whether or not it implements a cache, MUST pass cache
826 directives through in forwarded messages, regardless of their
827 significance to that application, since the directives might be
828 applicable to all recipients along the request/response chain. It is
829 not possible to target a directive to a specific cache.
831 Cache-Control = 1#cache-directive
833 cache-directive = cache-request-directive
834 / cache-response-directive
836 cache-extension = token [ "=" ( token / quoted-string ) ]
838 3.2.1. Request Cache-Control Directives
840 cache-request-directive =
841 "no-cache"
842 / "no-store"
843 / "max-age" "=" delta-seconds
844 / "max-stale" [ "=" delta-seconds ]
845 / "min-fresh" "=" delta-seconds
846 / "no-transform"
847 / "only-if-cached"
848 / cache-extension
850 no-cache
852 The no-cache request directive indicates that a cache MUST NOT use
853 a stored response to satisfy the request without successful
854 validation on the origin server.
856 no-store
858 The no-store request directive indicates that a cache MUST NOT
859 store any part of either this request or any response to it. This
860 directive applies to both private and shared caches. "MUST NOT
861 store" in this context means that the cache MUST NOT intentionally
862 store the information in non-volatile storage, and MUST make a
863 best-effort attempt to remove the information from volatile
864 storage as promptly as possible after forwarding it.
866 This directive is NOT a reliable or sufficient mechanism for
867 ensuring privacy. In particular, malicious or compromised caches
868 might not recognize or obey this directive, and communications
869 networks might be vulnerable to eavesdropping.
871 Note that if a request containing this directive is satisfied from
872 a cache, the no-store request directive does not apply to the
873 already stored response.
875 max-age
877 The max-age request directive indicates that the client is
878 unwilling to accept a response whose age is greater than the
879 specified number of seconds. Unless the max-stale request
880 directive is also present, the client is not willing to accept a
881 stale response.
883 max-stale
885 The max-stale request directive indicates that the client is
886 willing to accept a response that has exceeded its expiration
887 time. If max-stale is assigned a value, then the client is
888 willing to accept a response that has exceeded its expiration time
889 by no more than the specified number of seconds. If no value is
890 assigned to max-stale, then the client is willing to accept a
891 stale response of any age.
893 min-fresh
895 The min-fresh request directive indicates that the client is
896 willing to accept a response whose freshness lifetime is no less
897 than its current age plus the specified time in seconds. That is,
898 the client wants a response that will still be fresh for at least
899 the specified number of seconds.
901 no-transform
903 The no-transform request directive indicates that an intermediary
904 (whether or not it implements a cache) MUST NOT change the
905 Content-Encoding, Content-Range or Content-Type request header
906 fields, nor the request representation.
908 only-if-cached
910 The only-if-cached request directive indicates that the client
911 only wishes to obtain a stored response. If it receives this
912 directive, a cache SHOULD either respond using a stored response
913 that is consistent with the other constraints of the request, or
914 respond with a 504 (Gateway Timeout) status code. If a group of
915 caches is being operated as a unified system with good internal
916 connectivity, a member cache MAY forward such a request within
917 that group of caches.
919 3.2.2. Response Cache-Control Directives
921 cache-response-directive =
922 "public"
923 / "private" [ "=" DQUOTE 1#field-name DQUOTE ]
924 / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ]
925 / "no-store"
926 / "no-transform"
927 / "must-revalidate"
928 / "proxy-revalidate"
929 / "max-age" "=" delta-seconds
930 / "s-maxage" "=" delta-seconds
931 / cache-extension
933 public
935 The public response directive indicates that a response whose
936 associated request contains an 'Authentication' header MAY be
937 stored (see Section 2.6).
939 private
941 The private response directive indicates that the response message
942 is intended for a single user and MUST NOT be stored by a shared
943 cache. A private cache MAY store the response.
945 If the private response directive specifies one or more field-
946 names, this requirement is limited to the field-values associated
947 with the listed response header fields. That is, a shared cache
948 MUST NOT store the specified field-names(s), whereas it MAY store
949 the remainder of the response message.
951 Note: This usage of the word private only controls where the
952 response can be stored; it cannot ensure the privacy of the
953 message content. Also, private response directives with field-
954 names are often handled by implementations as if an unqualified
955 private directive was received; i.e., the special handling for the
956 qualified form is not widely implemented.
958 no-cache
960 The no-cache response directive indicates that the response MUST
961 NOT be used to satisfy a subsequent request without successful
962 validation on the origin server. This allows an origin server to
963 prevent a cache from using it to satisfy a request without
964 contacting it, even by caches that have been configured to return
965 stale responses.
967 If the no-cache response directive specifies one or more field-
968 names, this requirement is limited to the field-values associated
969 with the listed response header fields. That is, a cache MUST NOT
970 send the specified field-name(s) in the response to a subsequent
971 request without successful validation on the origin server. This
972 allows an origin server to prevent the re-use of certain header
973 fields in a response, while still allowing caching of the rest of
974 the response.
976 Note: Most HTTP/1.0 caches will not recognize or obey this
977 directive. Also, no-cache response directives with field-names
978 are often handled by implementations as if an unqualified no-cache
979 directive was received; i.e., the special handling for the
980 qualified form is not widely implemented.
982 no-store
984 The no-store response directive indicates that a cache MUST NOT
985 store any part of either the immediate request or response. This
986 directive applies to both private and shared caches. "MUST NOT
987 store" in this context means that the cache MUST NOT intentionally
988 store the information in non-volatile storage, and MUST make a
989 best-effort attempt to remove the information from volatile
990 storage as promptly as possible after forwarding it.
992 This directive is NOT a reliable or sufficient mechanism for
993 ensuring privacy. In particular, malicious or compromised caches
994 might not recognize or obey this directive, and communications
995 networks might be vulnerable to eavesdropping.
997 must-revalidate
999 The must-revalidate response directive indicates that once it has
1000 become stale, a cache MUST NOT use the response to satisfy
1001 subsequent requests without successful validation on the origin
1002 server.
1004 The must-revalidate directive is necessary to support reliable
1005 operation for certain protocol features. In all circumstances a
1006 cache MUST obey the must-revalidate directive; in particular, if a
1007 cache cannot reach the origin server for any reason, it MUST
1008 generate a 504 (Gateway Timeout) response.
1010 A server SHOULD send the must-revalidate directive if and only if
1011 failure to validate a request on the representation could result
1012 in incorrect operation, such as a silently unexecuted financial
1013 transaction.
1015 proxy-revalidate
1017 The proxy-revalidate response directive has the same meaning as
1018 the must-revalidate response directive, except that it does not
1019 apply to private caches.
1021 max-age
1023 The max-age response directive indicates that the response is to
1024 be considered stale after its age is greater than the specified
1025 number of seconds.
1027 s-maxage
1029 The s-maxage response directive indicates that, in shared caches,
1030 the maximum age specified by this directive overrides the maximum
1031 age specified by either the max-age directive or the Expires
1032 header field. The s-maxage directive also implies the semantics
1033 of the proxy-revalidate response directive.
1035 no-transform
1037 The no-transform response directive indicates that an intermediary
1038 (regardless of whether it implements a cache) MUST NOT change the
1039 Content-Encoding, Content-Range or Content-Type response header
1040 fields, nor the response representation.
1042 3.2.3. Cache Control Extensions
1044 The Cache-Control header field can be extended through the use of one
1045 or more cache-extension tokens, each with an optional value.
1046 Informational extensions (those that do not require a change in cache
1047 behavior) can be added without changing the semantics of other
1048 directives. Behavioral extensions are designed to work by acting as
1049 modifiers to the existing base of cache directives. Both the new
1050 directive and the standard directive are supplied, such that
1051 applications that do not understand the new directive will default to
1052 the behavior specified by the standard directive, and those that
1053 understand the new directive will recognize it as modifying the
1054 requirements associated with the standard directive. In this way,
1055 extensions to the cache-control directives can be made without
1056 requiring changes to the base protocol.
1058 This extension mechanism depends on an HTTP cache obeying all of the
1059 cache-control directives defined for its native HTTP-version, obeying
1060 certain extensions, and ignoring all directives that it does not
1061 understand.
1063 For example, consider a hypothetical new response directive called
1064 "community" that acts as a modifier to the private directive. We
1065 define this new directive to mean that, in addition to any private
1066 cache, any cache that is shared only by members of the community
1067 named within its value may cache the response. An origin server
1068 wishing to allow the UCI community to use an otherwise private
1069 response in their shared cache(s) could do so by including
1071 Cache-Control: private, community="UCI"
1073 A cache seeing this header field will act correctly even if the cache
1074 does not understand the community cache-extension, since it will also
1075 see and understand the private directive and thus default to the safe
1076 behavior.
1078 A cache MUST ignore unrecognized cache directives; it is assumed that
1079 any cache directive likely to be unrecognized by an HTTP/1.1 cache
1080 will be combined with standard directives (or the response's default
1081 cacheability) such that the cache behavior will remain minimally
1082 correct even if the cache does not understand the extension(s).
1084 The HTTP Cache Directive Registry defines the name space for the
1085 cache directives.
1087 A registration MUST include the following fields:
1089 o Cache Directive Name
1091 o Pointer to specification text
1093 Values to be added to this name space are subject to IETF review
1094 ([RFC5226], Section 4.1).
1096 The registry itself is maintained at
1097 .
1099 3.3. Expires
1101 The "Expires" header field gives the date/time after which the
1102 response is considered stale. See Section 2.3 for further discussion
1103 of the freshness model.
1105 The presence of an Expires field does not imply that the original
1106 resource will change or cease to exist at, before, or after that
1107 time.
1109 The field-value is an absolute date and time as defined by HTTP-date
1110 in Section 6.1 of [Part1]; a sender MUST use the rfc1123-date format.
1112 Expires = HTTP-date
1114 For example
1116 Expires: Thu, 01 Dec 1994 16:00:00 GMT
1118 Note: If a response includes a Cache-Control field with the max-
1119 age directive (see Section 3.2.2), that directive overrides the
1120 Expires field. Likewise, the s-maxage directive overrides Expires
1121 in shared caches.
1123 A server SHOULD NOT send Expires dates more than one year in the
1124 future.
1126 A cache MUST treat other invalid date formats, especially including
1127 the value "0", as in the past (i.e., "already expired").
1129 3.4. Pragma
1131 The "Pragma" header field allows backwards compatibility with
1132 HTTP/1.0 caches, so that clients can specify a "no-cache" request
1133 that they will understand (as Cache-Control was not defined until
1134 HTTP/1.1). When the Cache-Control header is also present and
1135 understood in a request, Pragma is ignored.
1137 In HTTP/1.0, Pragma was defined as an extensible field for
1138 implementation-specified directives for recipients. This
1139 specification deprecates such extensions to improve interoperability.
1141 Pragma = 1#pragma-directive
1142 pragma-directive = "no-cache" / extension-pragma
1143 extension-pragma = token [ "=" ( token / quoted-string ) ]
1145 When the Cache-Control header is not present in a request, the no-
1146 cache request pragma-directive MUST have the same effect on caches as
1147 if "Cache-Control: no-cache" were present (see Section 3.2.1).
1149 When sending a no-cache request, a client SHOULD include both pragma
1150 and cache-control directives unless Cache-Control: no-cache is
1151 purposefully omitted to target other Cache-Control response
1152 directives at HTTP/1.1 caches. For example:
1154 GET / HTTP/1.1
1155 Host: www.example.com
1156 Cache-Control: max-age=30
1157 Pragma: no-cache
1159 will constrain HTTP/1.1 caches to serve a response no older than 30
1160 seconds, while precluding implementations that do not understand
1161 Cache-Control from serving a cached response.
1163 Note: Because the meaning of "Pragma: no-cache" in responses is
1164 not specified, it does not provide a reliable replacement for
1165 "Cache-Control: no-cache" in them.
1167 3.5. Vary
1169 The "Vary" header field conveys the set of header fields that were
1170 used to select the representation.
1172 Caches use this information, in part, to determine whether a stored
1173 response can be used to satisfy a given request; see Section 2.7.
1174 determines, while the response is fresh, whether a cache is permitted
1175 to use the response to reply to a subsequent request without
1176 validation; see Section 2.7.
1178 In uncacheable or stale responses, the Vary field value advises the
1179 user agent about the criteria that were used to select the
1180 representation.
1182 Vary = "*" / 1#field-name
1184 The set of header fields named by the Vary field value is known as
1185 the selecting header fields.
1187 A server SHOULD include a Vary header field with any cacheable
1188 response that is subject to server-driven negotiation. Doing so
1189 allows a cache to properly interpret future requests on that resource
1190 and informs the user agent about the presence of negotiation on that
1191 resource. A server MAY include a Vary header field with a non-
1192 cacheable response that is subject to server-driven negotiation,
1193 since this might provide the user agent with useful information about
1194 the dimensions over which the response varies at the time of the
1195 response.
1197 A Vary field value of "*" signals that unspecified parameters not
1198 limited to the header fields (e.g., the network address of the
1199 client), play a role in the selection of the response representation;
1200 therefore, a cache cannot determine whether this response is
1201 appropriate. A proxy MUST NOT generate the "*" value.
1203 The field-names given are not limited to the set of standard header
1204 fields defined by this specification. Field names are case-
1205 insensitive.
1207 3.6. Warning
1209 The "Warning" header field is used to carry additional information
1210 about the status or transformation of a message that might not be
1211 reflected in the message. This information is typically used to warn
1212 about possible incorrectness introduced by caching operations or
1213 transformations applied to the payload of the message.
1215 Warnings can be used for other purposes, both cache-related and
1216 otherwise. The use of a warning, rather than an error status code,
1217 distinguishes these responses from true failures.
1219 Warning header fields can in general be applied to any message,
1220 however some warn-codes are specific to caches and can only be
1221 applied to response messages.
1223 Warning = 1#warning-value
1225 warning-value = warn-code SP warn-agent SP warn-text
1226 [SP warn-date]
1228 warn-code = 3DIGIT
1229 warn-agent = ( uri-host [ ":" port ] ) / pseudonym
1230 ; the name or pseudonym of the server adding
1231 ; the Warning header field, for use in debugging
1232 warn-text = quoted-string
1233 warn-date = DQUOTE HTTP-date DQUOTE
1235 Multiple warnings can be attached to a response (either by the origin
1236 server or by a cache), including multiple warnings with the same code
1237 number, only differing in warn-text.
1239 When this occurs, the user agent SHOULD inform the user of as many of
1240 them as possible, in the order that they appear in the response.
1242 Systems that generate multiple Warning header fields SHOULD order
1243 them with this user agent behavior in mind. New Warning header
1244 fields SHOULD be added after any existing Warning headers fields.
1246 Warnings are assigned three digit warn-codes. The first digit
1247 indicates whether the Warning is required to be deleted from a stored
1248 response after validation:
1250 o 1xx Warnings describe the freshness or validation status of the
1251 response, and so MUST be deleted by a cache after validation.
1252 They can only be generated by a cache when validating a cached
1253 entry, and MUST NOT be generated in any other situation.
1255 o 2xx Warnings describe some aspect of the representation that is
1256 not rectified by a validation (for example, a lossy compression of
1257 the representation) and MUST NOT be deleted by a cache after
1258 validation, unless a full response is returned, in which case they
1259 MUST be.
1261 If an implementation sends a message with one or more Warning header
1262 fields to a receiver whose version is HTTP/1.0 or lower, then the
1263 sender MUST include in each warning-value a warn-date that matches
1264 the Date header field in the message.
1266 If a system receives a message with a warning-value that includes a
1267 warn-date, and that warn-date is different from the Date value in the
1268 response, then that warning-value MUST be deleted from the message
1269 before storing, forwarding, or using it. (preventing the consequences
1270 of naive caching of Warning header fields.) If all of the warning-
1271 values are deleted for this reason, the Warning header field MUST be
1272 deleted as well.
1274 The following warn-codes are defined by this specification, each with
1275 a recommended warn-text in English, and a description of its meaning.
1277 110 Response is stale
1279 A cache SHOULD include this whenever the returned response is
1280 stale.
1282 111 Revalidation failed
1284 A cache SHOULD include this when returning a stale response
1285 because an attempt to validate the response failed, due to an
1286 inability to reach the server.
1288 112 Disconnected operation
1290 A cache SHOULD b include this if it is intentionally disconnected
1291 from the rest of the network for a period of time.
1293 113 Heuristic expiration
1295 A cache SHOULD include this if it heuristically chose a freshness
1296 lifetime greater than 24 hours and the response's age is greater
1297 than 24 hours.
1299 199 Miscellaneous warning
1301 The warning text can include arbitrary information to be presented
1302 to a human user, or logged. A system receiving this warning MUST
1303 NOT take any automated action, besides presenting the warning to
1304 the user.
1306 214 Transformation applied
1308 MUST be added by a proxy if it applies any transformation to the
1309 representation, such as changing the content-coding, media-type,
1310 or modifying the representation data, unless this Warning code
1311 already appears in the response.
1313 299 Miscellaneous persistent warning
1315 The warning text can include arbitrary information to be presented
1316 to a human user, or logged. A system receiving this warning MUST
1317 NOT take any automated action.
1319 4. History Lists
1321 User agents often have history mechanisms, such as "Back" buttons and
1322 history lists, that can be used to redisplay a representation
1323 retrieved earlier in a session.
1325 The freshness model (Section 2.3) does not necessarily apply to
1326 history mechanisms. I.e., a history mechanism can display a previous
1327 representation even if it has expired.
1329 This does not prohibit the history mechanism from telling the user
1330 that a view might be stale, or from honoring cache directives (e.g.,
1331 Cache-Control: no-store).
1333 5. IANA Considerations
1335 5.1. Cache Directive Registry
1337 The registration procedure for HTTP Cache Directives is defined by
1338 Section 3.2.3 of this document.
1340 The HTTP Cache Directive Registry shall be created at
1341 and be
1342 populated with the registrations below:
1344 +------------------------+------------------------------+
1345 | Cache Directive | Reference |
1346 +------------------------+------------------------------+
1347 | max-age | Section 3.2.1, Section 3.2.2 |
1348 | max-stale | Section 3.2.1 |
1349 | min-fresh | Section 3.2.1 |
1350 | must-revalidate | Section 3.2.2 |
1351 | no-cache | Section 3.2.1, Section 3.2.2 |
1352 | no-store | Section 3.2.1, Section 3.2.2 |
1353 | no-transform | Section 3.2.1, Section 3.2.2 |
1354 | only-if-cached | Section 3.2.1 |
1355 | private | Section 3.2.2 |
1356 | proxy-revalidate | Section 3.2.2 |
1357 | public | Section 3.2.2 |
1358 | s-maxage | Section 3.2.2 |
1359 | stale-if-error | [RFC5861], Section 4 |
1360 | stale-while-revalidate | [RFC5861], Section 3 |
1361 +------------------------+------------------------------+
1363 5.2. Header Field Registration
1365 The Message Header Field Registry located at shall be
1367 updated with the permanent registrations below (see [RFC3864]):
1369 +-------------------+----------+----------+-------------+
1370 | Header Field Name | Protocol | Status | Reference |
1371 +-------------------+----------+----------+-------------+
1372 | Age | http | standard | Section 3.1 |
1373 | Cache-Control | http | standard | Section 3.2 |
1374 | Expires | http | standard | Section 3.3 |
1375 | Pragma | http | standard | Section 3.4 |
1376 | Vary | http | standard | Section 3.5 |
1377 | Warning | http | standard | Section 3.6 |
1378 +-------------------+----------+----------+-------------+
1380 The change controller is: "IETF (iesg@ietf.org) - Internet
1381 Engineering Task Force".
1383 6. Security Considerations
1385 Caches expose additional potential vulnerabilities, since the
1386 contents of the cache represent an attractive target for malicious
1387 exploitation. Because cache contents persist after an HTTP request
1388 is complete, an attack on the cache can reveal information long after
1389 a user believes that the information has been removed from the
1390 network. Therefore, cache contents need to be protected as sensitive
1391 information.
1393 7. Acknowledgments
1395 Much of the content and presentation of the caching design is due to
1396 suggestions and comments from individuals including: Shel Kaphan,
1397 Paul Leach, Koen Holtman, David Morris, and Larry Masinter.
1399 8. References
1401 8.1. Normative References
1403 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1404 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1405 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections,
1406 and Message Parsing", draft-ietf-httpbis-p1-messaging-15
1407 (work in progress), July 2011.
1409 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1410 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1411 and J. Reschke, Ed., "HTTP/1.1, part 2: Message
1412 Semantics", draft-ietf-httpbis-p2-semantics-15 (work in
1413 progress), July 2011.
1415 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1416 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1417 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional
1418 Requests", draft-ietf-httpbis-p4-conditional-15 (work in
1419 progress), July 2011.
1421 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1422 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1423 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and
1424 Partial Responses", draft-ietf-httpbis-p5-range-15 (work
1425 in progress), July 2011.
1427 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H.,
1428 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed.,
1429 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication",
1430 draft-ietf-httpbis-p7-auth-15 (work in progress),
1431 July 2011.
1433 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1434 Requirement Levels", BCP 14, RFC 2119, March 1997.
1436 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
1437 Specifications: ABNF", STD 68, RFC 5234, January 2008.
1439 8.2. Informative References
1441 [RFC1305] Mills, D., "Network Time Protocol (Version 3)
1442 Specification, Implementation", RFC 1305, March 1992.
1444 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1445 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1446 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1448 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
1449 Procedures for Message Header Fields", BCP 90, RFC 3864,
1450 September 2004.
1452 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
1453 IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1454 May 2008.
1456 [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale
1457 Content", RFC 5861, April 2010.
1459 Appendix A. Changes from RFC 2616
1461 Make the specified age calculation algorithm less conservative.
1462 (Section 2.3.2)
1464 Remove requirement to consider Content-Location in successful
1465 responses in order to determine the appropriate response to use.
1466 (Section 2.4)
1468 Clarify denial of service attack avoidance requirement.
1469 (Section 2.5)
1471 Change ABNF productions for header fields to only define the field
1472 value. (Section 3)
1474 Do not mention RFC 2047 encoding and multiple languages in Warning
1475 header fields anymore, as these aspects never were implemented.
1476 (Section 3.6)
1478 Appendix B. Collected ABNF
1480 Age = delta-seconds
1482 Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS
1483 cache-directive ] )
1485 Expires = HTTP-date
1486 HTTP-date =
1488 OWS =
1490 Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
1491 pragma-directive ] )
1493 Vary = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name ]
1494 ) )
1496 Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
1497 )
1499 cache-directive = cache-request-directive / cache-response-directive
1500 cache-extension = token [ "=" ( token / quoted-string ) ]
1501 cache-request-directive = "no-cache" / "no-store" / ( "max-age="
1502 delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / (
1503 "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" /
1504 cache-extension
1505 cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( ","
1506 OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / (
1507 "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS
1508 field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" /
1509 "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds
1510 ) / ( "s-maxage=" delta-seconds ) / cache-extension
1512 delta-seconds = 1*DIGIT
1514 extension-pragma = token [ "=" ( token / quoted-string ) ]
1516 field-name =
1518 port =
1519 pragma-directive = "no-cache" / extension-pragma
1520 pseudonym =
1522 quoted-string =
1524 token =
1526 uri-host =
1528 warn-agent = ( uri-host [ ":" port ] ) / pseudonym
1529 warn-code = 3DIGIT
1530 warn-date = DQUOTE HTTP-date DQUOTE
1531 warn-text = quoted-string
1532 warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
1533 ]
1535 ABNF diagnostics:
1537 ; Age defined but not used
1538 ; Cache-Control defined but not used
1539 ; Expires defined but not used
1540 ; Pragma defined but not used
1541 ; Vary defined but not used
1542 ; Warning defined but not used
1544 Appendix C. Change Log (to be removed by RFC Editor before publication)
1546 C.1. Since RFC 2616
1548 Extracted relevant partitions from [RFC2616].
1550 C.2. Since draft-ietf-httpbis-p6-cache-00
1552 Closed issues:
1554 o : "Trailer"
1555 ()
1557 o : "Invalidation
1558 after Update or Delete"
1559 ()
1561 o : "Normative and
1562 Informative references"
1564 o : "Date reference
1565 typo"
1567 o : "Connection
1568 header text"
1570 o : "Informative
1571 references"
1573 o : "ISO-8859-1
1574 Reference"
1576 o : "Normative up-
1577 to-date references"
1579 o : "typo in
1580 13.2.2"
1582 Other changes:
1584 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress
1585 on )
1587 C.3. Since draft-ietf-httpbis-p6-cache-01
1589 Closed issues:
1591 o : "rel_path not
1592 used"
1594 Other changes:
1596 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work
1597 in progress on )
1599 o Add explicit references to BNF syntax and rules imported from
1600 other parts of the specification.
1602 C.4. Since draft-ietf-httpbis-p6-cache-02
1604 Ongoing work on IANA Message Header Field Registration
1605 ():
1607 o Reference RFC 3984, and update header field registrations for
1608 header fields defined in this document.
1610 C.5. Since draft-ietf-httpbis-p6-cache-03
1612 Closed issues:
1614 o : "Vary header
1615 classification"
1617 C.6. Since draft-ietf-httpbis-p6-cache-04
1619 Ongoing work on ABNF conversion
1620 ():
1622 o Use "/" instead of "|" for alternatives.
1624 o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional
1625 whitespace ("OWS") and required whitespace ("RWS").
1627 o Rewrite ABNFs to spell out whitespace rules, factor out header
1628 field value format definitions.
1630 C.7. Since draft-ietf-httpbis-p6-cache-05
1632 This is a total rewrite of this part of the specification.
1634 Affected issues:
1636 o : "Definition of
1637 1xx Warn-Codes"
1639 o : "Placement of
1640 13.5.1 and 13.5.2"
1642 o : "The role of
1643 Warning and Semantic Transparency in Caching"
1645 o : "Methods and
1646 Caching"
1648 In addition: Final work on ABNF conversion
1649 ():
1651 o Add appendix containing collected and expanded ABNF, reorganize
1652 ABNF introduction.
1654 C.8. Since draft-ietf-httpbis-p6-cache-06
1656 Closed issues:
1658 o : "base for
1659 numeric protocol elements"
1661 Affected issues:
1663 o : "Vary and non-
1664 existant headers"
1666 C.9. Since draft-ietf-httpbis-p6-cache-07
1668 Closed issues:
1670 o : "Definition of
1671 1xx Warn-Codes"
1673 o : "Content-
1674 Location on 304 responses"
1676 o : "private and
1677 no-cache CC directives with headers"
1679 o : "RFC2047 and
1680 warn-text"
1682 C.10. Since draft-ietf-httpbis-p6-cache-08
1684 Closed issues:
1686 o : "serving
1687 negotiated responses from cache: header-specific canonicalization"
1689 o : "Effect of CC
1690 directives on history lists"
1692 o : "Cache
1693 Extensions can override no-store, etc."
1695 Affected issues:
1697 o : Status codes
1698 and caching
1700 Partly resolved issues:
1702 o : "Placement of
1703 13.5.1 and 13.5.2"
1705 C.11. Since draft-ietf-httpbis-p6-cache-09
1707 Closed issues:
1709 o : "Age
1710 calculation"
1712 o : "Clarify
1713 differences between / requirements for request and response CC
1714 directives"
1716 o : "Caching
1717 authenticated responses"
1719 o : "IANA registry
1720 for cache-control directives"
1722 o : "Heuristic
1723 caching of URLs with query components"
1725 Partly resolved issues:
1727 o : "Term for the
1728 requested resource's URI"
1730 C.12. Since draft-ietf-httpbis-p6-cache-10
1732 Closed issues:
1734 o : "Clarify
1735 entity / representation / variant terminology"
1737 o : "consider
1738 removing the 'changes from 2068' sections"
1740 o : "Allowing
1741 heuristic caching for new status codes"
1743 o Clean up TODOs and prose in "Combining Responses."
1745 C.13. Since draft-ietf-httpbis-p6-cache-11
1747 Closed issues:
1749 o : "Text about
1750 clock requirement for caches belongs in p6"
1752 C.14. Since draft-ietf-httpbis-p6-cache-12
1754 Closed issues:
1756 o : "Header
1757 Classification"
1759 o : "Clarify
1760 'public'"
1762 C.15. Since draft-ietf-httpbis-p6-cache-13
1764 Closed issues:
1766 o : "untangle
1767 ABNFs for header fields"
1769 C.16. Since draft-ietf-httpbis-p6-cache-14
1771 Closed issues:
1773 o : "Mismatch Vary"
1774 o : "Cache
1775 Invalidation only happens upon successful responses"
1777 o : "Recommend
1778 minimum sizes for protocol elements"
1780 o : "Proxies don't
1781 'understand' methods"
1783 o : "Pragma"
1785 Index
1787 A
1788 age 6
1789 Age header field 18
1791 C
1792 cache 5
1793 Cache Directives
1794 max-age 20, 23
1795 max-stale 20
1796 min-fresh 20
1797 must-revalidate 22
1798 no-cache 19, 21
1799 no-store 19, 22
1800 no-transform 20, 23
1801 only-if-cached 20
1802 private 21
1803 proxy-revalidate 23
1804 public 21
1805 s-maxage 23
1806 Cache-Control header field 18
1807 cacheable 5
1809 E
1810 Expires header field 24
1811 explicit expiration time 6
1813 F
1814 first-hand 6
1815 fresh 6
1816 freshness lifetime 6
1818 G
1819 Grammar
1820 Age 18
1821 Cache-Control 19
1822 cache-extension 19
1823 cache-request-directive 19
1824 cache-response-directive 21
1825 delta-seconds 8
1826 Expires 25
1827 extension-pragma 25
1828 Pragma 25
1829 pragma-directive 25
1830 Vary 26
1831 warn-agent 27
1832 warn-code 27
1833 warn-date 27
1834 warn-text 27
1835 Warning 27
1836 warning-value 27
1838 H
1839 Header Fields
1840 Age 18
1841 Cache-Control 18
1842 Expires 24
1843 Pragma 25
1844 Vary 26
1845 Warning 27
1846 heuristic expiration time 6
1848 M
1849 max-age
1850 Cache Directive 20, 23
1851 max-stale
1852 Cache Directive 20
1853 min-fresh
1854 Cache Directive 20
1855 must-revalidate
1856 Cache Directive 22
1858 N
1859 no-cache
1860 Cache Directive 19, 21
1861 no-store
1862 Cache Directive 19, 22
1863 no-transform
1864 Cache Directive 20, 23
1866 O
1867 only-if-cached
1868 Cache Directive 20
1870 P
1871 Pragma header field 25
1872 private
1873 Cache Directive 21
1874 private cache 5
1875 proxy-revalidate
1876 Cache Directive 23
1877 public
1878 Cache Directive 21
1880 S
1881 s-maxage
1882 Cache Directive 23
1883 shared cache 5
1884 stale 6
1886 V
1887 validator 6
1888 Vary header field 26
1890 W
1891 Warning header field 27
1893 Authors' Addresses
1895 Roy T. Fielding (editor)
1896 Adobe Systems Incorporated
1897 345 Park Ave
1898 San Jose, CA 95110
1899 USA
1901 EMail: fielding@gbiv.com
1902 URI: http://roy.gbiv.com/
1904 Jim Gettys
1905 Alcatel-Lucent Bell Labs
1906 21 Oak Knoll Road
1907 Carlisle, MA 01741
1908 USA
1910 EMail: jg@freedesktop.org
1911 URI: http://gettys.wordpress.com/
1912 Jeffrey C. Mogul
1913 Hewlett-Packard Company
1914 HP Labs, Large Scale Systems Group
1915 1501 Page Mill Road, MS 1177
1916 Palo Alto, CA 94304
1917 USA
1919 EMail: JeffMogul@acm.org
1921 Henrik Frystyk Nielsen
1922 Microsoft Corporation
1923 1 Microsoft Way
1924 Redmond, WA 98052
1925 USA
1927 EMail: henrikn@microsoft.com
1929 Larry Masinter
1930 Adobe Systems Incorporated
1931 345 Park Ave
1932 San Jose, CA 95110
1933 USA
1935 EMail: LMM@acm.org
1936 URI: http://larry.masinter.net/
1938 Paul J. Leach
1939 Microsoft Corporation
1940 1 Microsoft Way
1941 Redmond, WA 98052
1943 EMail: paulle@microsoft.com
1945 Tim Berners-Lee
1946 World Wide Web Consortium
1947 MIT Computer Science and Artificial Intelligence Laboratory
1948 The Stata Center, Building 32
1949 32 Vassar Street
1950 Cambridge, MA 02139
1951 USA
1953 EMail: timbl@w3.org
1954 URI: http://www.w3.org/People/Berners-Lee/
1955 Yves Lafon (editor)
1956 World Wide Web Consortium
1957 W3C / ERCIM
1958 2004, rte des Lucioles
1959 Sophia-Antipolis, AM 06902
1960 France
1962 EMail: ylafon@w3.org
1963 URI: http://www.raubacapeu.net/people/yves/
1965 Mark Nottingham (editor)
1967 EMail: mnot@mnot.net
1968 URI: http://www.mnot.net/
1970 Julian F. Reschke (editor)
1971 greenbytes GmbH
1972 Hafenweg 16
1973 Muenster, NW 48155
1974 Germany
1976 Phone: +49 251 2807760
1977 Fax: +49 251 2807761
1978 EMail: julian.reschke@greenbytes.de
1979 URI: http://greenbytes.de/tech/webdav/