source: draft-ietf-httpbis/24/draft-ietf-httpbis-p6-cache-24.txt @ 2656

Last change on this file since 2656 was 2414, checked in by julian.reschke@…, 7 years ago

Prepare release of -24 on Sept 25

  • Property svn:eol-style set to native
File size: 92.2 KB
Line 
1
2
3
4HTTPbis Working Group                                   R. Fielding, Ed.
5Internet-Draft                                                     Adobe
6Obsoletes: 2616 (if approved)                         M. Nottingham, Ed.
7Intended status: Standards Track                                  Akamai
8Expires: March 29, 2014                                  J. Reschke, Ed.
9                                                              greenbytes
10                                                      September 25, 2013
11
12
13            Hypertext Transfer Protocol (HTTP/1.1): Caching
14                     draft-ietf-httpbis-p6-cache-24
15
16Abstract
17
18   The Hypertext Transfer Protocol (HTTP) is an application-level
19   protocol for distributed, collaborative, hypertext information
20   systems.  This document defines requirements on HTTP caches and the
21   associated header fields that control cache behavior or indicate
22   cacheable response messages.
23
24Editorial Note (To be removed by RFC Editor)
25
26   Discussion of this draft takes place on the HTTPBIS working group
27   mailing list (ietf-http-wg@w3.org), which is archived at
28   <http://lists.w3.org/Archives/Public/ietf-http-wg/>.
29
30   The current issues list is at
31   <http://tools.ietf.org/wg/httpbis/trac/report/3> and related
32   documents (including fancy diffs) can be found at
33   <http://tools.ietf.org/wg/httpbis/>.
34
35   The changes in this draft are summarized in Appendix D.5.
36
37Status of This Memo
38
39   This Internet-Draft is submitted in full conformance with the
40   provisions of BCP 78 and BCP 79.
41
42   Internet-Drafts are working documents of the Internet Engineering
43   Task Force (IETF).  Note that other groups may also distribute
44   working documents as Internet-Drafts.  The list of current Internet-
45   Drafts is at http://datatracker.ietf.org/drafts/current/.
46
47   Internet-Drafts are draft documents valid for a maximum of six months
48   and may be updated, replaced, or obsoleted by other documents at any
49   time.  It is inappropriate to use Internet-Drafts as reference
50   material or to cite them other than as "work in progress."
51
52
53
54
55Fielding, et al.         Expires March 29, 2014                 [Page 1]
56
57Internet-Draft              HTTP/1.1 Caching              September 2013
58
59
60   This Internet-Draft will expire on March 29, 2014.
61
62Copyright Notice
63
64   Copyright (c) 2013 IETF Trust and the persons identified as the
65   document authors.  All rights reserved.
66
67   This document is subject to BCP 78 and the IETF Trust's Legal
68   Provisions Relating to IETF Documents
69   (http://trustee.ietf.org/license-info) in effect on the date of
70   publication of this document.  Please review these documents
71   carefully, as they describe your rights and restrictions with respect
72   to this document.  Code Components extracted from this document must
73   include Simplified BSD License text as described in Section 4.e of
74   the Trust Legal Provisions and are provided without warranty as
75   described in the Simplified BSD License.
76
77   This document may contain material from IETF Documents or IETF
78   Contributions published or made publicly available before November
79   10, 2008.  The person(s) controlling the copyright in some of this
80   material may not have granted the IETF Trust the right to allow
81   modifications of such material outside the IETF Standards Process.
82   Without obtaining an adequate license from the person(s) controlling
83   the copyright in such materials, this document may not be modified
84   outside the IETF Standards Process, and derivative works of it may
85   not be created outside the IETF Standards Process, except to format
86   it for publication as an RFC or to translate it into languages other
87   than English.
88
89Table of Contents
90
91   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
92     1.1.  Conformance and Error Handling . . . . . . . . . . . . . .  4
93     1.2.  Syntax Notation  . . . . . . . . . . . . . . . . . . . . .  4
94       1.2.1.  Delta Seconds  . . . . . . . . . . . . . . . . . . . .  5
95   2.  Overview of Cache Operation  . . . . . . . . . . . . . . . . .  5
96   3.  Storing Responses in Caches  . . . . . . . . . . . . . . . . .  6
97     3.1.  Storing Incomplete Responses . . . . . . . . . . . . . . .  7
98     3.2.  Storing Responses to Authenticated Requests  . . . . . . .  7
99     3.3.  Combining Partial Content  . . . . . . . . . . . . . . . .  7
100   4.  Constructing Responses from Caches . . . . . . . . . . . . . .  8
101     4.1.  Calculating Secondary Keys with Vary . . . . . . . . . . .  9
102     4.2.  Freshness  . . . . . . . . . . . . . . . . . . . . . . . . 10
103       4.2.1.  Calculating Freshness Lifetime . . . . . . . . . . . . 12
104       4.2.2.  Calculating Heuristic Freshness  . . . . . . . . . . . 12
105       4.2.3.  Calculating Age  . . . . . . . . . . . . . . . . . . . 13
106       4.2.4.  Serving Stale Responses  . . . . . . . . . . . . . . . 14
107     4.3.  Validation . . . . . . . . . . . . . . . . . . . . . . . . 15
108
109
110
111Fielding, et al.         Expires March 29, 2014                 [Page 2]
112
113Internet-Draft              HTTP/1.1 Caching              September 2013
114
115
116       4.3.1.  Sending a Validation Request . . . . . . . . . . . . . 15
117       4.3.2.  Handling a Received Validation Request . . . . . . . . 16
118       4.3.3.  Handling a Validation Response . . . . . . . . . . . . 17
119       4.3.4.  Freshening Stored Responses upon Validation  . . . . . 18
120       4.3.5.  Freshening Responses via HEAD  . . . . . . . . . . . . 18
121     4.4.  Invalidation . . . . . . . . . . . . . . . . . . . . . . . 19
122   5.  Header Field Definitions . . . . . . . . . . . . . . . . . . . 20
123     5.1.  Age  . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
124     5.2.  Cache-Control  . . . . . . . . . . . . . . . . . . . . . . 20
125       5.2.1.  Request Cache-Control Directives . . . . . . . . . . . 21
126       5.2.2.  Response Cache-Control Directives  . . . . . . . . . . 23
127       5.2.3.  Cache Control Extensions . . . . . . . . . . . . . . . 26
128     5.3.  Expires  . . . . . . . . . . . . . . . . . . . . . . . . . 27
129     5.4.  Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 28
130     5.5.  Warning  . . . . . . . . . . . . . . . . . . . . . . . . . 29
131       5.5.1.  Warning: 110 - "Response is Stale" . . . . . . . . . . 30
132       5.5.2.  Warning: 111 - "Revalidation Failed" . . . . . . . . . 31
133       5.5.3.  Warning: 112 - "Disconnected Operation"  . . . . . . . 31
134       5.5.4.  Warning: 113 - "Heuristic Expiration"  . . . . . . . . 31
135       5.5.5.  Warning: 199 - "Miscellaneous Warning" . . . . . . . . 31
136       5.5.6.  Warning: 214 - "Transformation Applied"  . . . . . . . 31
137       5.5.7.  Warning: 299 - "Miscellaneous Persistent Warning"  . . 31
138   6.  History Lists  . . . . . . . . . . . . . . . . . . . . . . . . 31
139   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 32
140     7.1.  Cache Directive Registry . . . . . . . . . . . . . . . . . 32
141       7.1.1.  Procedure  . . . . . . . . . . . . . . . . . . . . . . 32
142       7.1.2.  Considerations for New Cache Control Directives  . . . 32
143       7.1.3.  Registrations  . . . . . . . . . . . . . . . . . . . . 32
144     7.2.  Warn Code Registry . . . . . . . . . . . . . . . . . . . . 33
145       7.2.1.  Procedure  . . . . . . . . . . . . . . . . . . . . . . 33
146       7.2.2.  Registrations  . . . . . . . . . . . . . . . . . . . . 33
147     7.3.  Header Field Registration  . . . . . . . . . . . . . . . . 34
148   8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 34
149   9.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 35
150   10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 35
151     10.1. Normative References . . . . . . . . . . . . . . . . . . . 35
152     10.2. Informative References . . . . . . . . . . . . . . . . . . 36
153   Appendix A.  Changes from RFC 2616 . . . . . . . . . . . . . . . . 36
154   Appendix B.  Imported ABNF . . . . . . . . . . . . . . . . . . . . 38
155   Appendix C.  Collected ABNF  . . . . . . . . . . . . . . . . . . . 38
156   Appendix D.  Change Log (to be removed by RFC Editor before
157                publication)  . . . . . . . . . . . . . . . . . . . . 39
158     D.1.  Since draft-ietf-httpbis-p6-cache-19 . . . . . . . . . . . 40
159     D.2.  Since draft-ietf-httpbis-p6-cache-20 . . . . . . . . . . . 40
160     D.3.  Since draft-ietf-httpbis-p6-cache-21 . . . . . . . . . . . 41
161     D.4.  Since draft-ietf-httpbis-p6-cache-22 . . . . . . . . . . . 41
162     D.5.  Since draft-ietf-httpbis-p6-cache-23 . . . . . . . . . . . 41
163   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
164
165
166
167Fielding, et al.         Expires March 29, 2014                 [Page 3]
168
169Internet-Draft              HTTP/1.1 Caching              September 2013
170
171
1721.  Introduction
173
174   HTTP is typically used for distributed information systems, where
175   performance can be improved by the use of response caches.  This
176   document defines aspects of HTTP/1.1 related to caching and reusing
177   response messages.
178
179   An HTTP cache is a local store of response messages and the subsystem
180   that controls storage, retrieval, and deletion of messages in it.  A
181   cache stores cacheable responses in order to reduce the response time
182   and network bandwidth consumption on future, equivalent requests.
183   Any client or server MAY employ a cache, though a cache cannot be
184   used by a server that is acting as a tunnel.
185
186   A shared cache is a cache that stores responses to be reused by more
187   than one user; shared caches are usually (but not always) deployed as
188   a part of an intermediary.  A private cache, in contrast, is
189   dedicated to a single user.
190
191   The goal of caching in HTTP/1.1 is to significantly improve
192   performance by reusing a prior response message to satisfy a current
193   request.  A stored response is considered "fresh", as defined in
194   Section 4.2, if the response can be reused without "validation"
195   (checking with the origin server to see if the cached response
196   remains valid for this request).  A fresh response can therefore
197   reduce both latency and network overhead each time it is reused.
198   When a cached response is not fresh, it might still be reusable if it
199   can be freshened by validation (Section 4.3) or if the origin is
200   unavailable (Section 4.2.4).
201
2021.1.  Conformance and Error Handling
203
204   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
205   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
206   document are to be interpreted as described in [RFC2119].
207
208   Conformance criteria and considerations regarding error handling are
209   defined in Section 2.5 of [Part1].
210
2111.2.  Syntax Notation
212
213   This specification uses the Augmented Backus-Naur Form (ABNF)
214   notation of [RFC5234] with the list rule extension defined in Section
215   7 of [Part1].  Appendix B describes rules imported from other
216   documents.  Appendix C shows the collected ABNF with the list rule
217   expanded.
218
219
220
221
222
223Fielding, et al.         Expires March 29, 2014                 [Page 4]
224
225Internet-Draft              HTTP/1.1 Caching              September 2013
226
227
2281.2.1.  Delta Seconds
229
230   The delta-seconds rule specifies a non-negative integer, representing
231   time in seconds.
232
233     delta-seconds  = 1*DIGIT
234
235   If a cache receives a delta-seconds value larger than the largest
236   positive integer it can represent, or if any of its subsequent
237   calculations overflows, the cache MUST consider the value to be
238   2147483648 (2^31).  A recipient parsing a delta-seconds value MUST
239   use an arithmetic type of at least 31 bits of range, and a sender
240   MUST NOT generate delta-seconds with a value greater than 2147483648.
241
2422.  Overview of Cache Operation
243
244   Proper cache operation preserves the semantics of HTTP transfers
245   ([Part2]) while eliminating the transfer of information already held
246   in the cache.  Although caching is an entirely OPTIONAL feature of
247   HTTP, we assume that reusing the cached response is desirable and
248   that such reuse is the default behavior when no requirement or local
249   configuration prevents it.  Therefore, HTTP cache requirements are
250   focused on preventing a cache from either storing a non-reusable
251   response or reusing a stored response inappropriately, rather than
252   mandating that caches always store and reuse particular responses.
253
254   Each cache entry consists of a cache key and one or more HTTP
255   responses corresponding to prior requests that used the same key.
256   The most common form of cache entry is a successful result of a
257   retrieval request: i.e., a 200 (OK) response to a GET request, which
258   contains a representation of the resource identified by the request
259   target (Section 4.3.1 of [Part2]).  However, it is also possible to
260   cache permanent redirects, negative results (e.g., 404 (Not Found)),
261   incomplete results (e.g., 206 (Partial Content)), and responses to
262   methods other than GET if the method's definition allows such caching
263   and defines something suitable for use as a cache key.
264
265   The primary cache key consists of the request method and target URI.
266   However, since HTTP caches in common use today are typically limited
267   to caching responses to GET, many caches simply decline other methods
268   and use only the URI as the primary cache key.
269
270   If a request target is subject to content negotiation, its cache
271   entry might consist of multiple stored responses, each differentiated
272   by a secondary key for the values of the original request's selecting
273   header fields (Section 4.1).
274
275
276
277
278
279Fielding, et al.         Expires March 29, 2014                 [Page 5]
280
281Internet-Draft              HTTP/1.1 Caching              September 2013
282
283
2843.  Storing Responses in Caches
285
286   A cache MUST NOT store a response to any request, unless:
287
288   o  The request method is understood by the cache and defined as being
289      cacheable, and
290
291   o  the response status code is understood by the cache, and
292
293   o  the "no-store" cache directive (see Section 5.2) does not appear
294      in request or response header fields, and
295
296   o  the "private" cache response directive (see Section 5.2.2.6) does
297      not appear in the response, if the cache is shared, and
298
299   o  the Authorization header field (see Section 4.1 of [Part7]) does
300      not appear in the request, if the cache is shared, unless the
301      response explicitly allows it (see Section 3.2), and
302
303   o  the response either:
304
305      *  contains an Expires header field (see Section 5.3), or
306
307      *  contains a max-age response cache directive (see
308         Section 5.2.2.8), or
309
310      *  contains a s-maxage response cache directive (see
311         Section 5.2.2.9) and the cache is shared, or
312
313      *  contains a Cache Control Extension (see Section 5.2.3) that
314         allows it to be cached, or
315
316      *  has a status code that is defined as cacheable (see
317         Section 4.2.2), or
318
319      *  contains a public response cache directive (see
320         Section 5.2.2.5).
321
322   Note that any of the requirements listed above can be overridden by a
323   cache-control extension; see Section 5.2.3.
324
325   In this context, a cache has "understood" a request method or a
326   response status code if it recognizes it and implements all specified
327   caching-related behavior.
328
329   Note that, in normal operation, some caches will not store a response
330   that has neither a cache validator nor an explicit expiration time,
331   as such responses are not usually useful to store.  However, caches
332
333
334
335Fielding, et al.         Expires March 29, 2014                 [Page 6]
336
337Internet-Draft              HTTP/1.1 Caching              September 2013
338
339
340   are not prohibited from storing such responses.
341
3423.1.  Storing Incomplete Responses
343
344   A response message is considered complete when all of the octets
345   indicated by the message framing ([Part1]) are received prior to the
346   connection being closed.  If the request method is GET, the response
347   status code is 200 (OK), and the entire response header section has
348   been received, a cache MAY store an incomplete response message body
349   if the cache entry is recorded as incomplete.  Likewise, a 206
350   (Partial Content) response MAY be stored as if it were an incomplete
351   200 (OK) cache entry.  However, a cache MUST NOT store incomplete or
352   partial content responses if it does not support the Range and
353   Content-Range header fields or if it does not understand the range
354   units used in those fields.
355
356   A cache MAY complete a stored incomplete response by making a
357   subsequent range request ([Part5]) and combining the successful
358   response with the stored entry, as defined in Section 3.3.  A cache
359   MUST NOT use an incomplete response to answer requests unless the
360   response has been made complete or the request is partial and
361   specifies a range that is wholly within the incomplete response.  A
362   cache MUST NOT send a partial response to a client without explicitly
363   marking it as such using the 206 (Partial Content) status code.
364
3653.2.  Storing Responses to Authenticated Requests
366
367   A shared cache MUST NOT use a cached response to a request with an
368   Authorization header field (Section 4.1 of [Part7]) to satisfy any
369   subsequent request unless a cache directive that allows such
370   responses to be stored is present in the response.
371
372   In this specification, the following Cache-Control response
373   directives (Section 5.2.2) have such an effect: must-revalidate,
374   public, s-maxage.
375
376   Note that cached responses that contain the "must-revalidate" and/or
377   "s-maxage" response directives are not allowed to be served stale
378   (Section 4.2.4) by shared caches.  In particular, a response with
379   either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
380   satisfy a subsequent request without revalidating it on the origin
381   server.
382
3833.3.  Combining Partial Content
384
385   A response might transfer only a partial representation if the
386   connection closed prematurely or if the request used one or more
387   Range specifiers ([Part5]).  After several such transfers, a cache
388
389
390
391Fielding, et al.         Expires March 29, 2014                 [Page 7]
392
393Internet-Draft              HTTP/1.1 Caching              September 2013
394
395
396   might have received several ranges of the same representation.  A
397   cache MAY combine these ranges into a single stored response, and
398   reuse that response to satisfy later requests, if they all share the
399   same strong validator and the cache complies with the client
400   requirements in Section 4.3 of [Part5].
401
402   When combining the new response with one or more stored responses, a
403   cache MUST:
404
405   o  delete any Warning header fields in the stored response with warn-
406      code 1xx (see Section 5.5);
407
408   o  retain any Warning header fields in the stored response with warn-
409      code 2xx; and,
410
411   o  use other header fields provided in the new response, aside from
412      Content-Range, to replace all instances of the corresponding
413      header fields in the stored response.
414
4154.  Constructing Responses from Caches
416
417   When presented with a request, a cache MUST NOT reuse a stored
418   response, unless:
419
420   o  The presented effective request URI (Section 5.5 of [Part1]) and
421      that of the stored response match, and
422
423   o  the request method associated with the stored response allows it
424      to be used for the presented request, and
425
426   o  selecting header fields nominated by the stored response (if any)
427      match those presented (see Section 4.1), and
428
429   o  the presented request does not contain the no-cache pragma
430      (Section 5.4), nor the no-cache cache directive (Section 5.2.1),
431      unless the stored response is successfully validated
432      (Section 4.3), and
433
434   o  the stored response does not contain the no-cache cache directive
435      (Section 5.2.2.2), unless it is successfully validated
436      (Section 4.3), and
437
438   o  the stored response is either:
439
440      *  fresh (see Section 4.2), or
441
442      *  allowed to be served stale (see Section 4.2.4), or
443
444
445
446
447Fielding, et al.         Expires March 29, 2014                 [Page 8]
448
449Internet-Draft              HTTP/1.1 Caching              September 2013
450
451
452      *  successfully validated (see Section 4.3).
453
454   Note that any of the requirements listed above can be overridden by a
455   cache-control extension; see Section 5.2.3.
456
457   When a stored response is used to satisfy a request without
458   validation, a cache MUST generate an Age header field (Section 5.1),
459   replacing any present in the response with a value equal to the
460   stored response's current_age; see Section 4.2.3.
461
462   A cache MUST write through requests with methods that are unsafe
463   (Section 4.2.1 of [Part2]) to the origin server; i.e., a cache is not
464   allowed to generate a reply to such a request before having forwarded
465   the request and having received a corresponding response.
466
467   Also, note that unsafe requests might invalidate already stored
468   responses; see Section 4.4.
469
470   When more than one suitable response is stored, a cache MUST use the
471   most recent response (as determined by the Date header field).  It
472   can also forward the request with "Cache-Control: max-age=0" or
473   "Cache-Control: no-cache" to disambiguate which response to use.
474
475   A cache that does not have a clock available MUST NOT use stored
476   responses without revalidating them upon every use.
477
4784.1.  Calculating Secondary Keys with Vary
479
480   When a cache receives a request that can be satisfied by a stored
481   response that has a Vary header field (Section 7.1.4 of [Part2]), it
482   MUST NOT use that response unless all of the selecting header fields
483   nominated by the Vary header field match in both the original request
484   (i.e., that associated with the stored response), and the presented
485   request.
486
487   The selecting header fields from two requests are defined to match if
488   and only if those in the first request can be transformed to those in
489   the second request by applying any of the following:
490
491   o  adding or removing whitespace, where allowed in the header field's
492      syntax
493
494   o  combining multiple header fields with the same field name (see
495      Section 3.2 of [Part1])
496
497   o  normalizing both header field values in a way that is known to
498      have identical semantics, according to the header field's
499      specification (e.g., re-ordering field values when order is not
500
501
502
503Fielding, et al.         Expires March 29, 2014                 [Page 9]
504
505Internet-Draft              HTTP/1.1 Caching              September 2013
506
507
508      significant; case-normalization, where values are defined to be
509      case-insensitive)
510
511   If (after any normalization that might take place) a header field is
512   absent from a request, it can only match another request if it is
513   also absent there.
514
515   A Vary header field-value of "*" always fails to match.
516
517   The stored response with matching selecting header fields is known as
518   the selected response.
519
520   If multiple selected responses are available (potentially including
521   responses without a Vary header field), the cache will need to choose
522   one to use.  When a selecting header field has a known mechanism for
523   doing so (e.g., qvalues on Accept and similar request header fields),
524   that mechanism MAY be used to select preferred responses; of the
525   remainder, the most recent response (as determined by the Date header
526   field) is used, as per Section 4.
527
528   If no selected response is available, the cache cannot satisfy the
529   presented request.  Typically, it is forwarded to the origin server
530   in a (possibly conditional; see Section 4.3) request.
531
5324.2.  Freshness
533
534   A fresh response is one whose age has not yet exceeded its freshness
535   lifetime.  Conversely, a stale response is one where it has.
536
537   A response's freshness lifetime is the length of time between its
538   generation by the origin server and its expiration time.  An explicit
539   expiration time is the time at which the origin server intends that a
540   stored response can no longer be used by a cache without further
541   validation, whereas a heuristic expiration time is assigned by a
542   cache when no explicit expiration time is available.
543
544   A response's age is the time that has passed since it was generated
545   by, or successfully validated with, the origin server.
546
547   When a response is "fresh" in the cache, it can be used to satisfy
548   subsequent requests without contacting the origin server, thereby
549   improving efficiency.
550
551   The primary mechanism for determining freshness is for an origin
552   server to provide an explicit expiration time in the future, using
553   either the Expires header field (Section 5.3) or the max-age response
554   cache directive (Section 5.2.2.8).  Generally, origin servers will
555   assign future explicit expiration times to responses in the belief
556
557
558
559Fielding, et al.         Expires March 29, 2014                [Page 10]
560
561Internet-Draft              HTTP/1.1 Caching              September 2013
562
563
564   that the representation is not likely to change in a semantically
565   significant way before the expiration time is reached.
566
567   If an origin server wishes to force a cache to validate every
568   request, it can assign an explicit expiration time in the past to
569   indicate that the response is already stale.  Compliant caches will
570   normally validate a stale cached response before reusing it for
571   subsequent requests (see Section 4.2.4).
572
573   Since origin servers do not always provide explicit expiration times,
574   caches are also allowed to use a heuristic to determine an expiration
575   time under certain circumstances (see Section 4.2.2).
576
577   The calculation to determine if a response is fresh is:
578
579      response_is_fresh = (freshness_lifetime > current_age)
580
581   freshness_lifetime is defined in Section 4.2.1; current_age is
582   defined in Section 4.2.3.
583
584   Clients can send the max-age or min-fresh cache directives in a
585   request to constrain or relax freshness calculations for the
586   corresponding response (Section 5.2.1).
587
588   When calculating freshness, to avoid common problems in date parsing:
589
590   o  Although all date formats are specified to be case-sensitive, a
591      cache recipient SHOULD match day, week, and timezone names case-
592      insensitively.
593
594   o  If a cache recipient's internal implementation of time has less
595      resolution than the value of an HTTP-date, the recipient MUST
596      internally represent a parsed Expires date as the nearest time
597      equal to or earlier than the received value.
598
599   o  A cache recipient MUST NOT allow local time zones to influence the
600      calculation or comparison of an age or expiration time.
601
602   o  A cache recipient SHOULD consider a date with a zone abbreviation
603      other than GMT or UTC to be invalid for calculating expiration.
604
605   Note that freshness applies only to cache operation; it cannot be
606   used to force a user agent to refresh its display or reload a
607   resource.  See Section 6 for an explanation of the difference between
608   caches and history mechanisms.
609
610
611
612
613
614
615Fielding, et al.         Expires March 29, 2014                [Page 11]
616
617Internet-Draft              HTTP/1.1 Caching              September 2013
618
619
6204.2.1.  Calculating Freshness Lifetime
621
622   A cache can calculate the freshness lifetime (denoted as
623   freshness_lifetime) of a response by using the first match of:
624
625   o  If the cache is shared and the s-maxage response cache directive
626      (Section 5.2.2.9) is present, use its value, or
627
628   o  If the max-age response cache directive (Section 5.2.2.8) is
629      present, use its value, or
630
631   o  If the Expires response header field (Section 5.3) is present, use
632      its value minus the value of the Date response header field, or
633
634   o  Otherwise, no explicit expiration time is present in the response.
635      A heuristic freshness lifetime might be applicable; see
636      Section 4.2.2.
637
638   Note that this calculation is not vulnerable to clock skew, since all
639   of the information comes from the origin server.
640
641   When there is more than one value present for a given directive
642   (e.g., two Expires header fields, multiple Cache-Control: max-age
643   directives), the directive's value is considered invalid.  Caches are
644   encouraged to consider responses that have invalid freshness
645   information to be stale.
646
6474.2.2.  Calculating Heuristic Freshness
648
649   Since origin servers do not always provide explicit expiration times,
650   a cache MAY assign a heuristic expiration time when an explicit time
651   is not specified, employing algorithms that use other header field
652   values (such as the Last-Modified time) to estimate a plausible
653   expiration time.  This specification does not provide specific
654   algorithms, but does impose worst-case constraints on their results.
655
656   A cache MUST NOT use heuristics to determine freshness when an
657   explicit expiration time is present in the stored response.  Because
658   of the requirements in Section 3, this means that, effectively,
659   heuristics can only be used on responses without explicit freshness
660   whose status codes are defined as cacheable, and responses without
661   explicit freshness that have been marked as explicitly cacheable
662   (e.g., with a "public" response cache directive).
663
664   If the response has a Last-Modified header field (Section 2.2 of
665   [Part4]), caches are encouraged to use a heuristic expiration value
666   that is no more than some fraction of the interval since that time.
667   A typical setting of this fraction might be 10%.
668
669
670
671Fielding, et al.         Expires March 29, 2014                [Page 12]
672
673Internet-Draft              HTTP/1.1 Caching              September 2013
674
675
676   When a heuristic is used to calculate freshness lifetime, a cache
677   SHOULD generate a Warning header field with a 113 warn-code (see
678   Section 5.5.4) in the response if its current_age is more than 24
679   hours and such a warning is not already present.
680
681      Note: Section 13.9 of [RFC2616] prohibited caches from calculating
682      heuristic freshness for URIs with query components (i.e., those
683      containing '?').  In practice, this has not been widely
684      implemented.  Therefore, origin servers are encouraged to send
685      explicit directives (e.g., Cache-Control: no-cache) if they wish
686      to preclude caching.
687
6884.2.3.  Calculating Age
689
690   The Age header field is used to convey an estimated age of the
691   response message when obtained from a cache.  The Age field value is
692   the cache's estimate of the number of seconds since the response was
693   generated or validated by the origin server.  In essence, the Age
694   value is the sum of the time that the response has been resident in
695   each of the caches along the path from the origin server, plus the
696   amount of time it has been in transit along network paths.
697
698   The following data is used for the age calculation:
699
700   age_value
701
702      The term "age_value" denotes the value of the Age header field
703      (Section 5.1), in a form appropriate for arithmetic operation; or
704      0, if not available.
705
706   date_value
707
708      The term "date_value" denotes the value of the Date header field,
709      in a form appropriate for arithmetic operations.  See Section
710      7.1.1.2 of [Part2] for the definition of the Date header field,
711      and for requirements regarding responses without it.
712
713   now
714
715      The term "now" means "the current value of the clock at the host
716      performing the calculation".  A host ought to use NTP ([RFC1305])
717      or some similar protocol to synchronize its clocks to Coordinated
718      Universal Time.
719
720   request_time
721
722      The current value of the clock at the host at the time the request
723      resulting in the stored response was made.
724
725
726
727Fielding, et al.         Expires March 29, 2014                [Page 13]
728
729Internet-Draft              HTTP/1.1 Caching              September 2013
730
731
732   response_time
733
734      The current value of the clock at the host at the time the
735      response was received.
736
737   A response's age can be calculated in two entirely independent ways:
738
739   1.  the "apparent_age": response_time minus date_value, if the local
740       clock is reasonably well synchronized to the origin server's
741       clock.  If the result is negative, the result is replaced by
742       zero.
743
744   2.  the "corrected_age_value", if all of the caches along the
745       response path implement HTTP/1.1.  A cache MUST interpret this
746       value relative to the time the request was initiated, not the
747       time that the response was received.
748
749
750     apparent_age = max(0, response_time - date_value);
751
752     response_delay = response_time - request_time;
753     corrected_age_value = age_value + response_delay;
754
755   These are combined as
756
757     corrected_initial_age = max(apparent_age, corrected_age_value);
758
759   unless the cache is confident in the value of the Age header field
760   (e.g., because there are no HTTP/1.0 hops in the Via header field),
761   in which case the corrected_age_value MAY be used as the
762   corrected_initial_age.
763
764   The current_age of a stored response can then be calculated by adding
765   the amount of time (in seconds) since the stored response was last
766   validated by the origin server to the corrected_initial_age.
767
768     resident_time = now - response_time;
769     current_age = corrected_initial_age + resident_time;
770
7714.2.4.  Serving Stale Responses
772
773   A "stale" response is one that either has explicit expiry information
774   or is allowed to have heuristic expiry calculated, but is not fresh
775   according to the calculations in Section 4.2.
776
777   A cache MUST NOT generate a stale response if it is prohibited by an
778   explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
779   cache directive, a "must-revalidate" cache-response-directive, or an
780
781
782
783Fielding, et al.         Expires March 29, 2014                [Page 14]
784
785Internet-Draft              HTTP/1.1 Caching              September 2013
786
787
788   applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
789   see Section 5.2.2).
790
791   A cache MUST NOT send stale responses unless it is disconnected
792   (i.e., it cannot contact the origin server or otherwise find a
793   forward path) or doing so is explicitly allowed (e.g., by the max-
794   stale request directive; see Section 5.2.1).
795
796   A cache SHOULD generate a Warning header field with the 110 warn-code
797   (see Section 5.5.1) in stale responses.  Likewise, a cache SHOULD
798   generate a 112 warn-code (see Section 5.5.3) in stale responses if
799   the cache is disconnected.
800
801   A cache SHOULD NOT generate a new Warning header field when
802   forwarding a response that does not have an Age header field, even if
803   the response is already stale.  A cache need not validate a response
804   that merely became stale in transit.
805
8064.3.  Validation
807
808   When a cache has one or more stored responses for a requested URI,
809   but cannot serve any of them (e.g., because they are not fresh, or
810   one cannot be selected; see Section 4.1), it can use the conditional
811   request mechanism [Part4] in the forwarded request to give the next
812   inbound server an opportunity to select a valid stored response to
813   use, updating the stored metadata in the process, or to replace the
814   stored response(s) with a new response.  This process is known as
815   "validating" or "revalidating" the stored response.
816
8174.3.1.  Sending a Validation Request
818
819   When sending a conditional request for cache validation, a cache
820   sends one or more precondition header fields containing validator
821   metadata from its stored response(s), which is then compared by
822   recipients to determine whether a stored response is equivalent to a
823   current representation of the resource.
824
825   One such validator is the timestamp given in a Last-Modified header
826   field (Section 2.2 of [Part4]), which can be used in an If-Modified-
827   Since header field for response validation, or in an If-Unmodified-
828   Since or If-Range header field for representation selection (i.e.,
829   the client is referring specifically to a previously obtained
830   representation with that timestamp).
831
832   Another validator is the entity-tag given in an ETag header field
833   (Section 2.3 of [Part4]).  One or more entity-tags, indicating one or
834   more stored responses, can be used in an If-None-Match header field
835   for response validation, or in an If-Match or If-Range header field
836
837
838
839Fielding, et al.         Expires March 29, 2014                [Page 15]
840
841Internet-Draft              HTTP/1.1 Caching              September 2013
842
843
844   for representation selection (i.e., the client is referring
845   specifically to one or more previously obtained representations with
846   the listed entity-tags).
847
8484.3.2.  Handling a Received Validation Request
849
850   Each client in the request chain may have its own cache, so it is
851   common for a cache at an intermediary to receive conditional requests
852   from other (outbound) caches.  Likewise, some user agents make use of
853   conditional requests to limit data transfers to recently modified
854   representations or to complete the transfer of a partially retrieved
855   representation.
856
857   If a cache receives a request that can be satisfied by reusing one of
858   its stored 200 (OK) or 206 (Partial Content) responses, the cache
859   SHOULD evaluate any applicable conditional header field preconditions
860   received in that request with respect to the corresponding validators
861   contained within the selected response.  A cache MUST NOT evaluate
862   conditional header fields that are only applicable to an origin
863   server, found in a request with semantics that cannot be satisfied
864   with a cached response, or applied to a target resource for which it
865   has no stored responses; such preconditions are likely intended for
866   some other (inbound) server.
867
868   The proper evaluation of conditional requests by a cache depends on
869   the received precondition header fields and their precedence, as
870   defined in Section 6 of [Part4].  The If-Match and If-Unmodified-
871   Since conditional header fields are not applicable to a cache.
872
873   A request containing an If-None-Match header field (Section 3.2 of
874   [Part4]) indicates that the client wants to validate one or more of
875   its own stored responses in comparison to whichever stored response
876   is selected by the cache.  If the field-value is "*", or if the
877   field-value is a list of entity-tags and at least one of them match
878   the entity-tag of the selected stored response, a cache recipient
879   SHOULD generate a 304 (Not Modified) response (using the metadata of
880   the selected stored response) instead of sending that stored
881   response.
882
883   When a cache decides to revalidate its own stored responses for a
884   request that contains an If-None-Match list of entity-tags, the cache
885   MAY combine the received list with a list of entity-tags from its own
886   stored set of responses (fresh or stale) and send the union of the
887   two lists as a replacement If-None-Match header field value in the
888   forwarded request.  If a stored response contains only partial
889   content, the cache MUST NOT include its entity-tag in the union
890   unless the request is for a range that would be fully satisfied by
891   that partial stored response.  If the response to the forwarded
892
893
894
895Fielding, et al.         Expires March 29, 2014                [Page 16]
896
897Internet-Draft              HTTP/1.1 Caching              September 2013
898
899
900   request is 304 (Not Modified) and has an ETag header field value with
901   an entity-tag that is not in the client's list, the cache MUST
902   generate a 200 (OK) response for the client by reusing its
903   corresponding stored response, as updated by the 304 response
904   metadata (Section 4.3.4).
905
906   If an If-None-Match header field is not present, a request containing
907   an If-Modified-Since header field (Section 3.3 of [Part4]) indicates
908   that the client wants to validate one or more of its own stored
909   responses by modification date.  A cache recipient SHOULD generate a
910   304 (Not Modified) response (using the metadata of the selected
911   stored response) if one of the following cases is true: 1) the
912   selected stored response has a Last-Modified field-value that is
913   earlier than or equal to the conditional timestamp; 2) no Last-
914   Modified field is present in the selected stored response, but it has
915   a Date field-value that is earlier than or equal to the conditional
916   timestamp; or, 3) neither Last-Modified nor Date is present in the
917   selected stored response, but the cache recorded it as having been
918   received at a time earlier than or equal to the conditional
919   timestamp.
920
921   A cache that implements partial responses to range requests, as
922   defined in [Part5], also needs to evaluate a received If-Range header
923   field (Section 3.2 of [Part5]) with respect to its selected stored
924   response.
925
9264.3.3.  Handling a Validation Response
927
928   Cache handling of a response to a conditional request is dependent
929   upon its status code:
930
931   o  A 304 (Not Modified) response status code indicates that the
932      stored response can be updated and reused; see Section 4.3.4.
933
934   o  A full response (i.e., one with a payload body) indicates that
935      none of the stored responses nominated in the conditional request
936      is suitable.  Instead, the cache MUST use the full response to
937      satisfy the request and MAY replace the stored response(s).
938
939   o  However, if a cache receives a 5xx (Server Error) response while
940      attempting to validate a response, it can either forward this
941      response to the requesting client, or act as if the server failed
942      to respond.  In the latter case, the cache MAY send a previously
943      stored response (see Section 4.2.4).
944
945
946
947
948
949
950
951Fielding, et al.         Expires March 29, 2014                [Page 17]
952
953Internet-Draft              HTTP/1.1 Caching              September 2013
954
955
9564.3.4.  Freshening Stored Responses upon Validation
957
958   When a cache receives a 304 (Not Modified) response and already has
959   one or more stored 200 (OK) responses for the same cache key, the
960   cache needs to identify which of the stored responses are updated by
961   this new response and then update the stored response(s) with the new
962   information provided in the 304 response.
963
964   The stored response to update is identified by using the first match
965   (if any) of:
966
967   o  If the new response contains a strong validator (see Section 2.1
968      of [Part4]), then that strong validator identifies the selected
969      representation for update.  All of the stored responses with the
970      same strong validator are selected.  If none of the stored
971      responses contain the same strong validator, then the cache MUST
972      NOT use the new response to update any stored responses.
973
974   o  If the new response contains a weak validator and that validator
975      corresponds to one of the cache's stored responses, then the most
976      recent of those matching stored responses is selected for update.
977
978   o  If the new response does not include any form of validator (such
979      as in the case where a client generates an If-Modified-Since
980      request from a source other than the Last-Modified response header
981      field), and there is only one stored response, and that stored
982      response also lacks a validator, then that stored response is
983      selected for update.
984
985   If a stored response is selected for update, the cache MUST:
986
987   o  delete any Warning header fields in the stored response with warn-
988      code 1xx (see Section 5.5);
989
990   o  retain any Warning header fields in the stored response with warn-
991      code 2xx; and,
992
993   o  use other header fields provided in the 304 (Not Modified)
994      response to replace all instances of the corresponding header
995      fields in the stored response.
996
9974.3.5.  Freshening Responses via HEAD
998
999   A response to the HEAD method is identical to what an equivalent
1000   request made with a GET would have been, except it lacks a body.
1001   This property of HEAD responses can be used to invalidate or update a
1002   cached GET response if the more efficient conditional GET request
1003   mechanism is not available (due to no validators being present in the
1004
1005
1006
1007Fielding, et al.         Expires March 29, 2014                [Page 18]
1008
1009Internet-Draft              HTTP/1.1 Caching              September 2013
1010
1011
1012   stored response) or if transmission of the representation body is not
1013   desired even if it has changed.
1014
1015   When a cache makes an inbound HEAD request for a given request target
1016   and receives a 200 (OK) response, the cache SHOULD update or
1017   invalidate each of its stored GET responses that could have been
1018   selected for that request (see Section 4.1).
1019
1020   For each of the stored responses that could have been selected, if
1021   the stored response and HEAD response have matching values for any
1022   received validator fields (ETag and Last-Modified) and, if the HEAD
1023   response has a Content-Length header field, the value of Content-
1024   Length matches that of the stored response, the cache SHOULD update
1025   the stored response a described below; otherwise, the cache SHOULD
1026   consider the stored response to be stale.
1027
1028   If a cache updates a stored response with the metadata provided in a
1029   HEAD response, the cache MUST:
1030
1031   o  delete any Warning header fields in the stored response with warn-
1032      code 1xx (see Section 5.5);
1033
1034   o  retain any Warning header fields in the stored response with warn-
1035      code 2xx; and,
1036
1037   o  use other header fields provided in the HEAD response to replace
1038      all instances of the corresponding header fields in the stored
1039      response and append new header fields to the stored response's
1040      header section unless otherwise restricted by the Cache-Control
1041      header field.
1042
10434.4.  Invalidation
1044
1045   Because unsafe request methods (Section 4.2.1 of [Part2]) such as
1046   PUT, POST or DELETE have the potential for changing state on the
1047   origin server, intervening caches can use them to keep their contents
1048   up-to-date.
1049
1050   A cache MUST invalidate the effective Request URI (Section 5.5 of
1051   [Part1]) as well as the URI(s) in the Location and Content-Location
1052   response header fields (if present) when a non-error status code is
1053   received in response to an unsafe request method.
1054
1055   However, a cache MUST NOT invalidate a URI from a Location or
1056   Content-Location response header field if the host part of that URI
1057   differs from the host part in the effective request URI (Section 5.5
1058   of [Part1]).  This helps prevent denial of service attacks.
1059
1060
1061
1062
1063Fielding, et al.         Expires March 29, 2014                [Page 19]
1064
1065Internet-Draft              HTTP/1.1 Caching              September 2013
1066
1067
1068   A cache MUST invalidate the effective request URI (Section 5.5 of
1069   [Part1]) when it receives a non-error response to a request with a
1070   method whose safety is unknown.
1071
1072   Here, a "non-error response" is one with a 2xx (Successful) or 3xx
1073   (Redirection) status code.  "Invalidate" means that the cache will
1074   either remove all stored responses related to the effective request
1075   URI, or will mark these as "invalid" and in need of a mandatory
1076   validation before they can be sent in response to a subsequent
1077   request.
1078
1079   Note that this does not guarantee that all appropriate responses are
1080   invalidated.  For example, a state-changing request might invalidate
1081   responses in the caches it travels through, but relevant responses
1082   still might be stored in other caches that it has not.
1083
10845.  Header Field Definitions
1085
1086   This section defines the syntax and semantics of HTTP/1.1 header
1087   fields related to caching.
1088
10895.1.  Age
1090
1091   The "Age" header field conveys the sender's estimate of the amount of
1092   time since the response was generated or successfully validated at
1093   the origin server.  Age values are calculated as specified in
1094   Section 4.2.3.
1095
1096     Age = delta-seconds
1097
1098   The Age field-value is a non-negative integer, representing time in
1099   seconds (see Section 1.2.1).
1100
1101   The presence of an Age header field implies that the response was not
1102   generated or validated by the origin server for this request.
1103   However, lack of an Age header field does not imply the origin was
1104   contacted, since the response might have been received from an
1105   HTTP/1.0 cache that does not implement Age.
1106
11075.2.  Cache-Control
1108
1109   The "Cache-Control" header field is used to specify directives for
1110   caches along the request/response chain.  Such cache directives are
1111   unidirectional in that the presence of a directive in a request does
1112   not imply that the same directive is to be given in the response.
1113
1114   A cache MUST obey the requirements of the Cache-Control directives
1115   defined in this section.  See Section 5.2.3 for information about how
1116
1117
1118
1119Fielding, et al.         Expires March 29, 2014                [Page 20]
1120
1121Internet-Draft              HTTP/1.1 Caching              September 2013
1122
1123
1124   Cache-Control directives defined elsewhere are handled.
1125
1126      Note: Some HTTP/1.0 caches might not implement Cache-Control.
1127
1128   A proxy, whether or not it implements a cache, MUST pass cache
1129   directives through in forwarded messages, regardless of their
1130   significance to that application, since the directives might be
1131   applicable to all recipients along the request/response chain.  It is
1132   not possible to target a directive to a specific cache.
1133
1134   Cache directives are identified by a token, to be compared case-
1135   insensitively, and have an optional argument, that can use both token
1136   and quoted-string syntax.  For the directives defined below that
1137   define arguments, recipients ought to accept both forms, even if one
1138   is documented to be preferred.  For any directive not defined by this
1139   specification, a recipient MUST accept both forms.
1140
1141     Cache-Control   = 1#cache-directive
1142
1143     cache-directive = token [ "=" ( token / quoted-string ) ]
1144
1145   For the cache directives defined below, no argument is defined (nor
1146   allowed) unless stated otherwise.
1147
11485.2.1.  Request Cache-Control Directives
1149
11505.2.1.1.  max-age
1151
1152   Argument syntax:
1153
1154      delta-seconds (see Section 1.2.1)
1155
1156   The "max-age" request directive indicates that the client is
1157   unwilling to accept a response whose age is greater than the
1158   specified number of seconds.  Unless the max-stale request directive
1159   is also present, the client is not willing to accept a stale
1160   response.
1161
1162   Note: This directive uses the token form of the argument syntax;
1163   e.g., 'max-age=5', not 'max-age="5"'.  A sender SHOULD NOT generate
1164   the quoted-string form.
1165
11665.2.1.2.  max-stale
1167
1168   Argument syntax:
1169
1170      delta-seconds (see Section 1.2.1)
1171
1172
1173
1174
1175Fielding, et al.         Expires March 29, 2014                [Page 21]
1176
1177Internet-Draft              HTTP/1.1 Caching              September 2013
1178
1179
1180   The "max-stale" request directive indicates that the client is
1181   willing to accept a response that has exceeded its freshness
1182   lifetime.  If max-stale is assigned a value, then the client is
1183   willing to accept a response that has exceeded its freshness lifetime
1184   by no more than the specified number of seconds.  If no value is
1185   assigned to max-stale, then the client is willing to accept a stale
1186   response of any age.
1187
1188   Note: This directive uses the token form of the argument syntax;
1189   e.g., 'max-stale=10', not 'max-stale="10"'.  A sender SHOULD NOT
1190   generate the quoted-string form.
1191
11925.2.1.3.  min-fresh
1193
1194   Argument syntax:
1195
1196      delta-seconds (see Section 1.2.1)
1197
1198   The "min-fresh" request directive indicates that the client is
1199   willing to accept a response whose freshness lifetime is no less than
1200   its current age plus the specified time in seconds.  That is, the
1201   client wants a response that will still be fresh for at least the
1202   specified number of seconds.
1203
1204   Note: This directive uses the token form of the argument syntax;
1205   e.g., 'min-fresh=20', not 'min-fresh="20"'.  A sender SHOULD NOT
1206   generate the quoted-string form.
1207
12085.2.1.4.  no-cache
1209
1210   The "no-cache" request directive indicates that a cache MUST NOT use
1211   a stored response to satisfy the request without successful
1212   validation on the origin server.
1213
12145.2.1.5.  no-store
1215
1216   The "no-store" request directive indicates that a cache MUST NOT
1217   store any part of either this request or any response to it.  This
1218   directive applies to both private and shared caches.  "MUST NOT
1219   store" in this context means that the cache MUST NOT intentionally
1220   store the information in non-volatile storage, and MUST make a best-
1221   effort attempt to remove the information from volatile storage as
1222   promptly as possible after forwarding it.
1223
1224   This directive is NOT a reliable or sufficient mechanism for ensuring
1225   privacy.  In particular, malicious or compromised caches might not
1226   recognize or obey this directive, and communications networks might
1227   be vulnerable to eavesdropping.
1228
1229
1230
1231Fielding, et al.         Expires March 29, 2014                [Page 22]
1232
1233Internet-Draft              HTTP/1.1 Caching              September 2013
1234
1235
1236   Note that if a request containing this directive is satisfied from a
1237   cache, the no-store request directive does not apply to the already
1238   stored response.
1239
12405.2.1.6.  no-transform
1241
1242   The "no-transform" request directive indicates that an intermediary
1243   (whether or not it implements a cache) MUST NOT transform the
1244   payload, as defined in Section 5.7.2 of [Part1].
1245
12465.2.1.7.  only-if-cached
1247
1248   The "only-if-cached" request directive indicates that the client only
1249   wishes to obtain a stored response.  If it receives this directive, a
1250   cache SHOULD either respond using a stored response that is
1251   consistent with the other constraints of the request, or respond with
1252   a 504 (Gateway Timeout) status code.  If a group of caches is being
1253   operated as a unified system with good internal connectivity, a
1254   member cache MAY forward such a request within that group of caches.
1255
12565.2.2.  Response Cache-Control Directives
1257
12585.2.2.1.  must-revalidate
1259
1260   The "must-revalidate" response directive indicates that once it has
1261   become stale, a cache MUST NOT use the response to satisfy subsequent
1262   requests without successful validation on the origin server.
1263
1264   The must-revalidate directive is necessary to support reliable
1265   operation for certain protocol features.  In all circumstances a
1266   cache MUST obey the must-revalidate directive; in particular, if a
1267   cache cannot reach the origin server for any reason, it MUST generate
1268   a 504 (Gateway Timeout) response.
1269
1270   The must-revalidate directive ought to be used by servers if and only
1271   if failure to validate a request on the representation could result
1272   in incorrect operation, such as a silently unexecuted financial
1273   transaction.
1274
12755.2.2.2.  no-cache
1276
1277   Argument syntax:
1278
1279      #field-name
1280
1281   The "no-cache" response directive indicates that the response MUST
1282   NOT be used to satisfy a subsequent request without successful
1283   validation on the origin server.  This allows an origin server to
1284
1285
1286
1287Fielding, et al.         Expires March 29, 2014                [Page 23]
1288
1289Internet-Draft              HTTP/1.1 Caching              September 2013
1290
1291
1292   prevent a cache from using it to satisfy a request without contacting
1293   it, even by caches that have been configured to send stale responses.
1294
1295   If the no-cache response directive specifies one or more field-names,
1296   then a cache MAY use the response to satisfy a subsequent request,
1297   subject to any other restrictions on caching.  However, any header
1298   fields in the response that have the field-name(s) listed MUST NOT be
1299   sent in the response to a subsequent request without successful
1300   revalidation with the origin server.  This allows an origin server to
1301   prevent the re-use of certain header fields in a response, while
1302   still allowing caching of the rest of the response.
1303
1304   The field-names given are not limited to the set of header fields
1305   defined by this specification.  Field names are case-insensitive.
1306
1307   Note: Although it has been back-ported to many implementations, some
1308   HTTP/1.0 caches will not recognize or obey this directive.  Also, no-
1309   cache response directives with field-names are often handled by
1310   caches as if an unqualified no-cache directive was received; i.e.,
1311   the special handling for the qualified form is not widely
1312   implemented.
1313
1314   Note: This directive uses the quoted-string form of the argument
1315   syntax.  A sender SHOULD NOT generate the token form (even if quoting
1316   appears not to be needed for single-entry lists).
1317
13185.2.2.3.  no-store
1319
1320   The "no-store" response directive indicates that a cache MUST NOT
1321   store any part of either the immediate request or response.  This
1322   directive applies to both private and shared caches.  "MUST NOT
1323   store" in this context means that the cache MUST NOT intentionally
1324   store the information in non-volatile storage, and MUST make a best-
1325   effort attempt to remove the information from volatile storage as
1326   promptly as possible after forwarding it.
1327
1328   This directive is NOT a reliable or sufficient mechanism for ensuring
1329   privacy.  In particular, malicious or compromised caches might not
1330   recognize or obey this directive, and communications networks might
1331   be vulnerable to eavesdropping.
1332
13335.2.2.4.  no-transform
1334
1335   The "no-transform" response directive indicates that an intermediary
1336   (regardless of whether it implements a cache) MUST NOT transform the
1337   payload, as defined in Section 5.7.2 of [Part1].
1338
1339
1340
1341
1342
1343Fielding, et al.         Expires March 29, 2014                [Page 24]
1344
1345Internet-Draft              HTTP/1.1 Caching              September 2013
1346
1347
13485.2.2.5.  public
1349
1350   The "public" response directive indicates that any cache MAY store
1351   the response, even if the response would normally be non-cacheable or
1352   cacheable only within a private cache.  (See Section 3.2 for
1353   additional details related to the use of public in response to a
1354   request containing Authorization, and Section 3 for details of how
1355   public affects responses that would normally not be stored, due to
1356   their status codes not being defined as cacheable.)
1357
13585.2.2.6.  private
1359
1360   Argument syntax:
1361
1362      #field-name
1363
1364   The "private" response directive indicates that the response message
1365   is intended for a single user and MUST NOT be stored by a shared
1366   cache.  A private cache MAY store the response and reuse it for later
1367   requests, even if the response would normally be non-cacheable.
1368
1369   If the private response directive specifies one or more field-names,
1370   this requirement is limited to the field-values associated with the
1371   listed response header fields.  That is, a shared cache MUST NOT
1372   store the specified field-names(s), whereas it MAY store the
1373   remainder of the response message.
1374
1375   The field-names given are not limited to the set of header fields
1376   defined by this specification.  Field names are case-insensitive.
1377
1378   Note: This usage of the word "private" only controls where the
1379   response can be stored; it cannot ensure the privacy of the message
1380   content.  Also, private response directives with field-names are
1381   often handled by caches as if an unqualified private directive was
1382   received; i.e., the special handling for the qualified form is not
1383   widely implemented.
1384
1385   Note: This directive uses the quoted-string form of the argument
1386   syntax.  A sender SHOULD NOT generate the token form (even if quoting
1387   appears not to be needed for single-entry lists).
1388
13895.2.2.7.  proxy-revalidate
1390
1391   The "proxy-revalidate" response directive has the same meaning as the
1392   must-revalidate response directive, except that it does not apply to
1393   private caches.
1394
1395
1396
1397
1398
1399Fielding, et al.         Expires March 29, 2014                [Page 25]
1400
1401Internet-Draft              HTTP/1.1 Caching              September 2013
1402
1403
14045.2.2.8.  max-age
1405
1406   Argument syntax:
1407
1408      delta-seconds (see Section 1.2.1)
1409
1410   The "max-age" response directive indicates that the response is to be
1411   considered stale after its age is greater than the specified number
1412   of seconds.
1413
1414   Note: This directive uses the token form of the argument syntax;
1415   e.g., 'max-age=5', not 'max-age="5"'.  A sender SHOULD NOT generate
1416   the quoted-string form.
1417
14185.2.2.9.  s-maxage
1419
1420   Argument syntax:
1421
1422      delta-seconds (see Section 1.2.1)
1423
1424   The "s-maxage" response directive indicates that, in shared caches,
1425   the maximum age specified by this directive overrides the maximum age
1426   specified by either the max-age directive or the Expires header
1427   field.  The s-maxage directive also implies the semantics of the
1428   proxy-revalidate response directive.
1429
1430   Note: This directive uses the token form of the argument syntax;
1431   e.g., 's-maxage=10', not 's-maxage="10"'.  A sender SHOULD NOT
1432   generate the quoted-string form.
1433
14345.2.3.  Cache Control Extensions
1435
1436   The Cache-Control header field can be extended through the use of one
1437   or more cache-extension tokens, each with an optional value.
1438
1439   Informational extensions (those that do not require a change in cache
1440   behavior) can be added without changing the semantics of other
1441   directives.  Behavioral extensions are designed to work by acting as
1442   modifiers to the existing base of cache directives.
1443
1444   Both the new directive and the standard directive are supplied, such
1445   that applications that do not understand the new directive will
1446   default to the behavior specified by the standard directive, and
1447   those that understand the new directive will recognize it as
1448   modifying the requirements associated with the standard directive.
1449   In this way, extensions to the cache-control directives can be made
1450   without requiring changes to the base protocol.
1451
1452
1453
1454
1455Fielding, et al.         Expires March 29, 2014                [Page 26]
1456
1457Internet-Draft              HTTP/1.1 Caching              September 2013
1458
1459
1460   This extension mechanism depends on an HTTP cache obeying all of the
1461   cache-control directives defined for its native HTTP-version, obeying
1462   certain extensions, and ignoring all directives that it does not
1463   understand.
1464
1465   For example, consider a hypothetical new response directive called
1466   "community" that acts as a modifier to the private directive.  We
1467   define this new directive to mean that, in addition to any private
1468   cache, any cache that is shared only by members of the community
1469   named within its value is allowed to cache the response.  An origin
1470   server wishing to allow the UCI community to use an otherwise private
1471   response in their shared cache(s) could do so by including
1472
1473     Cache-Control: private, community="UCI"
1474
1475   A cache seeing this header field will act correctly even if the cache
1476   does not understand the community cache-extension, since it will also
1477   see and understand the private directive and thus default to the safe
1478   behavior.
1479
1480   A cache MUST ignore unrecognized cache directives; it is assumed that
1481   any cache directive likely to be unrecognized by an HTTP/1.1 cache
1482   will be combined with standard directives (or the response's default
1483   cacheability) such that the cache behavior will remain minimally
1484   correct even if the cache does not understand the extension(s).
1485
14865.3.  Expires
1487
1488   The "Expires" header field gives the date/time after which the
1489   response is considered stale.  See Section 4.2 for further discussion
1490   of the freshness model.
1491
1492   The presence of an Expires field does not imply that the original
1493   resource will change or cease to exist at, before, or after that
1494   time.
1495
1496   The Expires value is an HTTP-date timestamp, as defined in Section
1497   7.1.1.1 of [Part2].
1498
1499     Expires = HTTP-date
1500
1501   For example
1502
1503     Expires: Thu, 01 Dec 1994 16:00:00 GMT
1504
1505   A cache recipient MUST interpret invalid date formats, especially the
1506   value "0", as representing a time in the past (i.e., "already
1507   expired").
1508
1509
1510
1511Fielding, et al.         Expires March 29, 2014                [Page 27]
1512
1513Internet-Draft              HTTP/1.1 Caching              September 2013
1514
1515
1516   If a response includes a Cache-Control field with the max-age
1517   directive (Section 5.2.2.8), a recipient MUST ignore the Expires
1518   field.  Likewise, if a response includes the s-maxage directive
1519   (Section 5.2.2.9), a shared cache recipient MUST ignore the Expires
1520   field.  In both these cases, the value in Expires is only intended
1521   for recipients that have not yet implemented the Cache-Control field.
1522
1523   An origin server without a clock MUST NOT generate an Expires field
1524   unless its value represents a fixed time in the past (always expired)
1525   or its value has been associated with the resource by a system or
1526   user with a reliable clock.
1527
1528   Historically, HTTP required the Expires field-value to be no more
1529   than a year in the future.  While longer freshness lifetimes are no
1530   longer prohibited, extremely large values have been demonstrated to
1531   cause problems (e.g., clock overflows due to use of 32-bit integers
1532   for time values), and many caches will evict a response far sooner
1533   than that.
1534
15355.4.  Pragma
1536
1537   The "Pragma" header field allows backwards compatibility with
1538   HTTP/1.0 caches, so that clients can specify a "no-cache" request
1539   that they will understand (as Cache-Control was not defined until
1540   HTTP/1.1).  When the Cache-Control header field is also present and
1541   understood in a request, Pragma is ignored.
1542
1543   In HTTP/1.0, Pragma was defined as an extensible field for
1544   implementation-specified directives for recipients.  This
1545   specification deprecates such extensions to improve interoperability.
1546
1547     Pragma           = 1#pragma-directive
1548     pragma-directive = "no-cache" / extension-pragma
1549     extension-pragma = token [ "=" ( token / quoted-string ) ]
1550
1551   When the Cache-Control header field is not present in a request,
1552   caches MUST consider the no-cache request pragma-directive as having
1553   the same effect as if "Cache-Control: no-cache" were present (see
1554   Section 5.2.1).
1555
1556   When sending a no-cache request, a client ought to include both the
1557   pragma and cache-control directives, unless Cache-Control: no-cache
1558   is purposefully omitted to target other Cache-Control response
1559   directives at HTTP/1.1 caches.  For example:
1560
1561     GET / HTTP/1.1
1562     Host: www.example.com
1563     Cache-Control: max-age=30
1564
1565
1566
1567Fielding, et al.         Expires March 29, 2014                [Page 28]
1568
1569Internet-Draft              HTTP/1.1 Caching              September 2013
1570
1571
1572     Pragma: no-cache
1573
1574
1575   will constrain HTTP/1.1 caches to serve a response no older than 30
1576   seconds, while precluding implementations that do not understand
1577   Cache-Control from serving a cached response.
1578
1579      Note: Because the meaning of "Pragma: no-cache" in responses is
1580      not specified, it does not provide a reliable replacement for
1581      "Cache-Control: no-cache" in them.
1582
15835.5.  Warning
1584
1585   The "Warning" header field is used to carry additional information
1586   about the status or transformation of a message that might not be
1587   reflected in the status code.  This information is typically used to
1588   warn about possible incorrectness introduced by caching operations or
1589   transformations applied to the payload of the message.
1590
1591   Warnings can be used for other purposes, both cache-related and
1592   otherwise.  The use of a warning, rather than an error status code,
1593   distinguishes these responses from true failures.
1594
1595   Warning header fields can in general be applied to any message,
1596   however some warn-codes are specific to caches and can only be
1597   applied to response messages.
1598
1599     Warning       = 1#warning-value
1600
1601     warning-value = warn-code SP warn-agent SP warn-text
1602                                           [ SP warn-date ]
1603
1604     warn-code  = 3DIGIT
1605     warn-agent = ( uri-host [ ":" port ] ) / pseudonym
1606                     ; the name or pseudonym of the server adding
1607                     ; the Warning header field, for use in debugging
1608                     ; a single "-" is recommended when agent unknown
1609     warn-text  = quoted-string
1610     warn-date  = DQUOTE HTTP-date DQUOTE
1611
1612   Multiple warnings can be generated in a response (either by the
1613   origin server or by a cache), including multiple warnings with the
1614   same warn-code number that only differ in warn-text.
1615
1616   A user agent that receives one or more Warning header fields SHOULD
1617   inform the user of as many of them as possible, in the order that
1618   they appear in the response.  Senders that generate multiple Warning
1619   header fields are encouraged to order them with this user agent
1620
1621
1622
1623Fielding, et al.         Expires March 29, 2014                [Page 29]
1624
1625Internet-Draft              HTTP/1.1 Caching              September 2013
1626
1627
1628   behavior in mind.  A sender that generates new Warning header fields
1629   MUST append them after any existing Warning header fields.
1630
1631   Warnings are assigned three digit warn-codes.  The first digit
1632   indicates whether the Warning is required to be deleted from a stored
1633   response after validation:
1634
1635   o  1xx warn-codes describe the freshness or validation status of the
1636      response, and so MUST be deleted by a cache after validation.
1637      They can only be generated by a cache when validating a cached
1638      entry, and MUST NOT be generated in any other situation.
1639
1640   o  2xx warn-codes describe some aspect of the representation that is
1641      not rectified by a validation (for example, a lossy compression of
1642      the representation) and MUST NOT be deleted by a cache after
1643      validation, unless a full response is sent, in which case they
1644      MUST be.
1645
1646   If a sender generates one or more 1xx warn-codes in a message to be
1647   sent to a recipient known to implement only HTTP/1.0, the sender MUST
1648   include in each corresponding warning-value a warn-date that matches
1649   the Date header field in the message.  For example:
1650
1651     HTTP/1.1 200 OK
1652     Date: Sat, 25 Aug 2012 23:34:45 GMT
1653     Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
1654
1655
1656   If a recipient that uses, evaluates, or displays Warning header
1657   fields receives a warn-date that is different from the Date value in
1658   the same message, the recipient MUST exclude the warning-value
1659   containing that warn-date before storing, forwarding, or using the
1660   message.  This allows recipients to exclude warning-values that were
1661   improperly retained after a cache validation.  If all of the warning-
1662   values are excluded, the recipient MUST exclude the Warning header
1663   field as well.
1664
1665   The following warn-codes are defined by this specification, each with
1666   a recommended warn-text in English, and a description of its meaning.
1667   The procedure for defining additional warn codes is described in
1668   Section 7.2.1.
1669
16705.5.1.  Warning: 110 - "Response is Stale"
1671
1672   A cache SHOULD generate this whenever the sent response is stale.
1673
1674
1675
1676
1677
1678
1679Fielding, et al.         Expires March 29, 2014                [Page 30]
1680
1681Internet-Draft              HTTP/1.1 Caching              September 2013
1682
1683
16845.5.2.  Warning: 111 - "Revalidation Failed"
1685
1686   A cache SHOULD generate this when sending a stale response because an
1687   attempt to validate the response failed, due to an inability to reach
1688   the server.
1689
16905.5.3.  Warning: 112 - "Disconnected Operation"
1691
1692   A cache SHOULD generate this if it is intentionally disconnected from
1693   the rest of the network for a period of time.
1694
16955.5.4.  Warning: 113 - "Heuristic Expiration"
1696
1697   A cache SHOULD generate this if it heuristically chose a freshness
1698   lifetime greater than 24 hours and the response's age is greater than
1699   24 hours.
1700
17015.5.5.  Warning: 199 - "Miscellaneous Warning"
1702
1703   The warning text can include arbitrary information to be presented to
1704   a human user, or logged.  A system receiving this warning MUST NOT
1705   take any automated action, besides presenting the warning to the
1706   user.
1707
17085.5.6.  Warning: 214 - "Transformation Applied"
1709
1710   MUST be added by a proxy if it applies any transformation to the
1711   representation, such as changing the content-coding, media-type, or
1712   modifying the representation data, unless this Warning code already
1713   appears in the response.
1714
17155.5.7.  Warning: 299 - "Miscellaneous Persistent Warning"
1716
1717   The warning text can include arbitrary information to be presented to
1718   a human user, or logged.  A system receiving this warning MUST NOT
1719   take any automated action.
1720
17216.  History Lists
1722
1723   User agents often have history mechanisms, such as "Back" buttons and
1724   history lists, that can be used to redisplay a representation
1725   retrieved earlier in a session.
1726
1727   The freshness model (Section 4.2) does not necessarily apply to
1728   history mechanisms.  I.e., a history mechanism can display a previous
1729   representation even if it has expired.
1730
1731   This does not prohibit the history mechanism from telling the user
1732
1733
1734
1735Fielding, et al.         Expires March 29, 2014                [Page 31]
1736
1737Internet-Draft              HTTP/1.1 Caching              September 2013
1738
1739
1740   that a view might be stale, or from honoring cache directives (e.g.,
1741   Cache-Control: no-store).
1742
17437.  IANA Considerations
1744
17457.1.  Cache Directive Registry
1746
1747   The HTTP Cache Directive Registry defines the name space for the
1748   cache directives.  It will be created and maintained at
1749   <http://www.iana.org/assignments/http-cache-directives>.
1750
17517.1.1.  Procedure
1752
1753   A registration MUST include the following fields:
1754
1755   o  Cache Directive Name
1756
1757   o  Pointer to specification text
1758
1759   Values to be added to this name space require IETF Review (see
1760   [RFC5226], Section 4.1).
1761
17627.1.2.  Considerations for New Cache Control Directives
1763
1764   New extension directives ought to consider defining:
1765
1766   o  What it means for a directive to be specified multiple times,
1767
1768   o  When the directive does not take an argument, what it means when
1769      an argument is present,
1770
1771   o  When the directive requires an argument, what it means when it is
1772      missing,
1773
1774   o  Whether the directive is specific to requests, responses, or able
1775      to be used in either.
1776
1777   See also Section 5.2.3.
1778
17797.1.3.  Registrations
1780
1781   The HTTP Cache Directive Registry shall be populated with the
1782   registrations below:
1783
1784
1785
1786
1787
1788
1789
1790
1791Fielding, et al.         Expires March 29, 2014                [Page 32]
1792
1793Internet-Draft              HTTP/1.1 Caching              September 2013
1794
1795
1796   +------------------------+----------------------------------+
1797   | Cache Directive        | Reference                        |
1798   +------------------------+----------------------------------+
1799   | max-age                | Section 5.2.1.1, Section 5.2.2.8 |
1800   | max-stale              | Section 5.2.1.2                  |
1801   | min-fresh              | Section 5.2.1.3                  |
1802   | must-revalidate        | Section 5.2.2.1                  |
1803   | no-cache               | Section 5.2.1.4, Section 5.2.2.2 |
1804   | no-store               | Section 5.2.1.5, Section 5.2.2.3 |
1805   | no-transform           | Section 5.2.1.6, Section 5.2.2.4 |
1806   | only-if-cached         | Section 5.2.1.7                  |
1807   | private                | Section 5.2.2.6                  |
1808   | proxy-revalidate       | Section 5.2.2.7                  |
1809   | public                 | Section 5.2.2.5                  |
1810   | s-maxage               | Section 5.2.2.9                  |
1811   | stale-if-error         | [RFC5861], Section 4             |
1812   | stale-while-revalidate | [RFC5861], Section 3             |
1813   +------------------------+----------------------------------+
1814
18157.2.  Warn Code Registry
1816
1817   The HTTP Warn Code Registry defines the name space for warn codes.
1818   It will be created and maintained at
1819   <http://www.iana.org/assignments/http-warn-codes>.
1820
18217.2.1.  Procedure
1822
1823   A registration MUST include the following fields:
1824
1825   o  Warn Code (3 digits)
1826
1827   o  Short Description
1828
1829   o  Pointer to specification text
1830
1831   Values to be added to this name space require IETF Review (see
1832   [RFC5226], Section 4.1).
1833
18347.2.2.  Registrations
1835
1836   The HTTP Warn Code Registry shall be populated with the registrations
1837   below:
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847Fielding, et al.         Expires March 29, 2014                [Page 33]
1848
1849Internet-Draft              HTTP/1.1 Caching              September 2013
1850
1851
1852   +-----------+----------------------------------+---------------+
1853   | Warn Code | Short Description                | Reference     |
1854   +-----------+----------------------------------+---------------+
1855   | 110       | Response is Stale                | Section 5.5.1 |
1856   | 111       | Revalidation Failed              | Section 5.5.2 |
1857   | 112       | Disconnected Operation           | Section 5.5.3 |
1858   | 113       | Heuristic Expiration             | Section 5.5.4 |
1859   | 199       | Miscellaneous Warning            | Section 5.5.5 |
1860   | 214       | Transformation Applied           | Section 5.5.6 |
1861   | 299       | Miscellaneous Persistent Warning | Section 5.5.7 |
1862   +-----------+----------------------------------+---------------+
1863
18647.3.  Header Field Registration
1865
1866   HTTP header fields are registered within the Message Header Field
1867   Registry maintained at <http://www.iana.org/assignments/
1868   message-headers/message-header-index.html>.
1869
1870   This document defines the following HTTP header fields, so their
1871   associated registry entries shall be updated according to the
1872   permanent registrations below (see [BCP90]):
1873
1874   +-------------------+----------+----------+-------------+
1875   | Header Field Name | Protocol | Status   | Reference   |
1876   +-------------------+----------+----------+-------------+
1877   | Age               | http     | standard | Section 5.1 |
1878   | Cache-Control     | http     | standard | Section 5.2 |
1879   | Expires           | http     | standard | Section 5.3 |
1880   | Pragma            | http     | standard | Section 5.4 |
1881   | Warning           | http     | standard | Section 5.5 |
1882   +-------------------+----------+----------+-------------+
1883
1884   The change controller is: "IETF (iesg@ietf.org) - Internet
1885   Engineering Task Force".
1886
18878.  Security Considerations
1888
1889   This section is meant to inform developers, information providers,
1890   and users of known security concerns specific to HTTP/1.1 caching.
1891   More general security considerations are addressed in HTTP messaging
1892   [Part1] and semantics [Part2].
1893
1894   Caches expose additional potential vulnerabilities, since the
1895   contents of the cache represent an attractive target for malicious
1896   exploitation.  Because cache contents persist after an HTTP request
1897   is complete, an attack on the cache can reveal information long after
1898   a user believes that the information has been removed from the
1899   network.  Therefore, cache contents need to be protected as sensitive
1900
1901
1902
1903Fielding, et al.         Expires March 29, 2014                [Page 34]
1904
1905Internet-Draft              HTTP/1.1 Caching              September 2013
1906
1907
1908   information.
1909
1910   Furthermore, the very use of a cache can bring about privacy
1911   concerns.  For example, if two users share a cache, and the first one
1912   browses to a site, the second may be able to detect that the other
1913   has been to that site, because the resources from it load more
1914   quickly, thanks to the cache.
1915
1916   Implementation flaws might allow attackers to insert content into a
1917   cache ("cache poisoning"), leading to compromise of clients that
1918   trust that content.  Because of their nature, these attacks are
1919   difficult to mitigate.
1920
1921   Likewise, implementation flaws (as well as misunderstanding of cache
1922   operation) might lead to caching of sensitive information (e.g.,
1923   authentication credentials) that is thought to be private, exposing
1924   it to unauthorized parties.
1925
1926   Note that the Set-Cookie response header field [RFC6265] does not
1927   inhibit caching; a cacheable response with a Set-Cookie header field
1928   can be (and often is) used to satisfy subsequent requests to caches.
1929   Servers who wish to control caching of these responses are encouraged
1930   to emit appropriate Cache-Control response header fields.
1931
19329.  Acknowledgments
1933
1934   See Section 10 of [Part1].
1935
193610.  References
1937
193810.1.  Normative References
1939
1940   [Part1]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1941              Protocol (HTTP/1.1): Message Syntax and Routing",
1942              draft-ietf-httpbis-p1-messaging-24 (work in progress),
1943              September 2013.
1944
1945   [Part2]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1946              Protocol (HTTP/1.1): Semantics and Content",
1947              draft-ietf-httpbis-p2-semantics-24 (work in progress),
1948              September 2013.
1949
1950   [Part4]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1951              Protocol (HTTP/1.1): Conditional Requests",
1952              draft-ietf-httpbis-p4-conditional-24 (work in progress),
1953              September 2013.
1954
1955   [Part5]    Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
1956
1957
1958
1959Fielding, et al.         Expires March 29, 2014                [Page 35]
1960
1961Internet-Draft              HTTP/1.1 Caching              September 2013
1962
1963
1964              "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
1965              draft-ietf-httpbis-p5-range-24 (work in progress),
1966              September 2013.
1967
1968   [Part7]    Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
1969              Protocol (HTTP/1.1): Authentication",
1970              draft-ietf-httpbis-p7-auth-24 (work in progress),
1971              September 2013.
1972
1973   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
1974              Requirement Levels", BCP 14, RFC 2119, March 1997.
1975
1976   [RFC5234]  Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
1977              Specifications: ABNF", STD 68, RFC 5234, January 2008.
1978
197910.2.  Informative References
1980
1981   [BCP90]    Klyne, G., Nottingham, M., and J. Mogul, "Registration
1982              Procedures for Message Header Fields", BCP 90, RFC 3864,
1983              September 2004.
1984
1985   [RFC1305]  Mills, D., "Network Time Protocol (Version 3)
1986              Specification, Implementation", RFC 1305, March 1992.
1987
1988   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1989              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1990              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1991
1992   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
1993              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1994              May 2008.
1995
1996   [RFC5861]  Nottingham, M., "HTTP Cache-Control Extensions for Stale
1997              Content", RFC 5861, April 2010.
1998
1999   [RFC6265]  Barth, A., "HTTP State Management Mechanism", RFC 6265,
2000              April 2011.
2001
2002Appendix A.  Changes from RFC 2616
2003
2004   The specification has been substantially rewritten for clarity.
2005
2006   The conditions under which an authenticated response can be cached
2007   have been clarified.  (Section 3.2)
2008
2009   New status codes can now define that caches are allowed to use
2010   heuristic freshness with them.  Caches are now allowed to calculate
2011   heuristic freshness for URIs with query components.  (Section 4.2.2)
2012
2013
2014
2015Fielding, et al.         Expires March 29, 2014                [Page 36]
2016
2017Internet-Draft              HTTP/1.1 Caching              September 2013
2018
2019
2020   The algorithm for calculating age is now less conservative.  Caches
2021   are now required to handle dates with timezones as if they're
2022   invalid, because it's not possible to accurately guess.
2023   (Section 4.2.3)
2024
2025   The Content-Location response header field is no longer used to
2026   determine the appropriate response to use when validating.
2027   (Section 4.3)
2028
2029   The algorithm for selecting a cached negotiated response to use has
2030   been clarified in several ways.  In particular, it now explicitly
2031   allows header-specific canonicalization when processing selecting
2032   header fields.  (Section 4.1)
2033
2034   Requirements regarding denial of service attack avoidance when
2035   performing invalidation have been clarified.  (Section 4.4)
2036
2037   Cache invalidation only occurs when a successful response is
2038   received.  (Section 4.4)
2039
2040   Cache directives are explicitly defined to be case-insensitive.
2041   Handling of multiple instances of cache directives when only one is
2042   expected is now defined.  (Section 5.2)
2043
2044   The "no-store" cache request directive doesn't apply to responses;
2045   i.e., a cache can satisfy a request with no-store on it, and does not
2046   invalidate it.  (Section 5.2.1.5)
2047
2048   The qualified forms of the private and no-cache cache directives are
2049   noted to not be widely implemented; e.g., "private=foo" is
2050   interpreted by many caches as simply "private".  Additionally, the
2051   meaning of the qualified form of no-cache has been clarified.
2052   (Section 5.2.2)
2053
2054   The "no-cache" response cache directive's meaning has been clarified.
2055   (Section 5.2.2.2)
2056
2057   The one-year limit on Expires header field values has been removed;
2058   instead, the reasoning for using a sensible value is given.
2059   (Section 5.3)
2060
2061   The Pragma header field is now only defined for backwards
2062   compatibility; future pragmas are deprecated.  (Section 5.4)
2063
2064   Some requirements regarding production and processing of the Warning
2065   header fields have been relaxed, as it is not widely implemented.
2066   Furthermore, the Warning header field no longer uses RFC 2047
2067   encoding, nor allows multiple languages, as these aspects were not
2068
2069
2070
2071Fielding, et al.         Expires March 29, 2014                [Page 37]
2072
2073Internet-Draft              HTTP/1.1 Caching              September 2013
2074
2075
2076   implemented.  (Section 5.5)
2077
2078   This specification introduces the Cache Directive and Warn Code
2079   Registries, and defines considerations for new cache directives.
2080   (Section 7.1 and Section 7.2)
2081
2082Appendix B.  Imported ABNF
2083
2084   The following core rules are included by reference, as defined in
2085   Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
2086   CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
2087   quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
2088   8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
2089   character).
2090
2091   The rules below are defined in [Part1]:
2092
2093     OWS           = <OWS, defined in [Part1], Section 3.2.3>
2094     field-name    = <field-name, defined in [Part1], Section 3.2>
2095     quoted-string = <quoted-string, defined in [Part1], Section 3.2.6>
2096     token         = <token, defined in [Part1], Section 3.2.6>
2097
2098     port          = <port, defined in [Part1], Section 2.7>
2099     pseudonym     = <pseudonym, defined in [Part1], Section 5.7.1>
2100     uri-host      = <uri-host, defined in [Part1], Section 2.7>
2101
2102   The rules below are defined in other parts:
2103
2104     HTTP-date     = <HTTP-date, defined in [Part2], Section 7.1.1.1>
2105
2106Appendix C.  Collected ABNF
2107
2108   In the collected ABNF below, list rules are expanded as per Section
2109   1.2 of [Part1].
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127Fielding, et al.         Expires March 29, 2014                [Page 38]
2128
2129Internet-Draft              HTTP/1.1 Caching              September 2013
2130
2131
2132   Age = delta-seconds
2133
2134   Cache-Control = *( "," OWS ) cache-directive *( OWS "," [ OWS
2135    cache-directive ] )
2136
2137   Expires = HTTP-date
2138
2139   HTTP-date = <HTTP-date, defined in [Part2], Section 7.1.1.1>
2140
2141   OWS = <OWS, defined in [Part1], Section 3.2.3>
2142
2143   Pragma = *( "," OWS ) pragma-directive *( OWS "," [ OWS
2144    pragma-directive ] )
2145
2146   Warning = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value ]
2147    )
2148
2149   cache-directive = token [ "=" ( token / quoted-string ) ]
2150
2151   delta-seconds = 1*DIGIT
2152
2153   extension-pragma = token [ "=" ( token / quoted-string ) ]
2154
2155   field-name = <field-name, defined in [Part1], Section 3.2>
2156
2157   port = <port, defined in [Part1], Section 2.7>
2158   pragma-directive = "no-cache" / extension-pragma
2159   pseudonym = <pseudonym, defined in [Part1], Section 5.7.1>
2160
2161   quoted-string = <quoted-string, defined in [Part1], Section 3.2.6>
2162
2163   token = <token, defined in [Part1], Section 3.2.6>
2164
2165   uri-host = <uri-host, defined in [Part1], Section 2.7>
2166
2167   warn-agent = ( uri-host [ ":" port ] ) / pseudonym
2168   warn-code = 3DIGIT
2169   warn-date = DQUOTE HTTP-date DQUOTE
2170   warn-text = quoted-string
2171   warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date
2172    ]
2173
2174Appendix D.  Change Log (to be removed by RFC Editor before publication)
2175
2176   Changes up to the first Working Group Last Call draft are summarized
2177   in <http://trac.tools.ietf.org/html/
2178   draft-ietf-httpbis-p6-cache-19#appendix-C>.
2179
2180
2181
2182
2183Fielding, et al.         Expires March 29, 2014                [Page 39]
2184
2185Internet-Draft              HTTP/1.1 Caching              September 2013
2186
2187
2188D.1.  Since draft-ietf-httpbis-p6-cache-19
2189
2190   Closed issues:
2191
2192   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/307>: "untangle
2193      Cache-Control ABNF"
2194
2195   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/353>: "Multiple
2196      values in Cache-Control header fields"
2197
2198   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/355>: "Case
2199      sensitivity of header fields in CC values"
2200
2201   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/356>: "Spurious
2202      'MAYs'"
2203
2204   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/360>: "enhance
2205      considerations for new cache control directives"
2206
2207   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/361>: "ABNF
2208      requirements for recipients"
2209
2210   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/368>: "note
2211      introduction of new IANA registries as normative changes"
2212
2213   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/373>: "broken prose
2214      in description of 'Vary'"
2215
2216D.2.  Since draft-ietf-httpbis-p6-cache-20
2217
2218   Closed issues:
2219
2220   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/375>: "'Most
2221      Conservative'"
2222
2223   Other changes:
2224
2225   o  Conformance criteria and considerations regarding error handling
2226      are now defined in Part 1.
2227
2228   o  Move definition of "Vary" header field into Part 2.
2229
2230   o  Add security considerations with respect to cache poisoning and
2231      the "Set-Cookie" header field.
2232
2233
2234
2235
2236
2237
2238
2239Fielding, et al.         Expires March 29, 2014                [Page 40]
2240
2241Internet-Draft              HTTP/1.1 Caching              September 2013
2242
2243
2244D.3.  Since draft-ietf-httpbis-p6-cache-21
2245
2246   Closed issues:
2247
2248   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/223>: "Allowing
2249      heuristic caching for new status codes"
2250
2251   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/406>: "304 without
2252      validator"
2253
2254   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/418>: "No-Transform"
2255
2256   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/430>: "Revert prior
2257      change to the meaning of the public cache response directive.
2258
2259D.4.  Since draft-ietf-httpbis-p6-cache-22
2260
2261   Closed issues:
2262
2263   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/436>: "explain list
2264      expansion in ABNF appendices"
2265
2266   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/453>: "Returning the
2267      freshest response"
2268
2269   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/464>: "placement of
2270      extension point considerations"
2271
2272   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/469>: "Editorial
2273      notes for p6"
2274
2275   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/471>: "Vary and
2276      future requests"
2277
2278D.5.  Since draft-ietf-httpbis-p6-cache-23
2279
2280   Closed issues:
2281
2282   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/486>: "Requiring
2283      proxies to process warn-date"
2284
2285   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/496>: "add Warning
2286      header field examples"
2287
2288Index
2289
2290   1
2291      110 (warn-code)  30
2292
2293
2294
2295Fielding, et al.         Expires March 29, 2014                [Page 41]
2296
2297Internet-Draft              HTTP/1.1 Caching              September 2013
2298
2299
2300      111 (warn-code)  31
2301      112 (warn-code)  31
2302      113 (warn-code)  31
2303      199 (warn-code)  31
2304
2305   2
2306      214 (warn-code)  31
2307      299 (warn-code)  31
2308
2309   A
2310      age  10
2311      Age header field  20
2312
2313   C
2314      cache  4
2315      cache entry  5
2316      cache key  5
2317      Cache-Control header field  20
2318
2319   D
2320      Disconnected Operation (warn-text)  31
2321
2322   E
2323      Expires header field  27
2324      explicit expiration time  10
2325
2326   F
2327      fresh  10
2328      freshness lifetime  10
2329
2330   G
2331      Grammar
2332         Age  20
2333         Cache-Control  21
2334         cache-directive  21
2335         delta-seconds  5
2336         Expires  27
2337         extension-pragma  28
2338         Pragma  28
2339         pragma-directive  28
2340         warn-agent  29
2341         warn-code  29
2342         warn-date  29
2343         warn-text  29
2344         Warning  29
2345         warning-value  29
2346
2347   H
2348
2349
2350
2351Fielding, et al.         Expires March 29, 2014                [Page 42]
2352
2353Internet-Draft              HTTP/1.1 Caching              September 2013
2354
2355
2356      Heuristic Expiration (warn-text)  31
2357      heuristic expiration time  10
2358
2359   M
2360      max-age (cache directive)  21, 26
2361      max-stale (cache directive)  21
2362      min-fresh (cache directive)  22
2363      Miscellaneous Persistent Warning (warn-text)  31
2364      Miscellaneous Warning (warn-text)  31
2365      must-revalidate (cache directive)  23
2366
2367   N
2368      no-cache (cache directive)  22-23
2369      no-store (cache directive)  22, 24
2370      no-transform (cache directive)  23-24
2371
2372   O
2373      only-if-cached (cache directive)  23
2374
2375   P
2376      Pragma header field  28
2377      private (cache directive)  25
2378      private cache  4
2379      proxy-revalidate (cache directive)  25
2380      public (cache directive)  25
2381
2382   R
2383      Response is Stale (warn-text)  30
2384      Revalidation Failed (warn-text)  31
2385
2386   S
2387      s-maxage (cache directive)  26
2388      shared cache  4
2389      stale  10
2390      strong validator  18
2391
2392   T
2393      Transformation Applied (warn-text)  31
2394
2395   V
2396      validator  15
2397
2398   W
2399      Warning header field  29
2400
2401
2402
2403
2404
2405
2406
2407Fielding, et al.         Expires March 29, 2014                [Page 43]
2408
2409Internet-Draft              HTTP/1.1 Caching              September 2013
2410
2411
2412Authors' Addresses
2413
2414   Roy T. Fielding (editor)
2415   Adobe Systems Incorporated
2416   345 Park Ave
2417   San Jose, CA  95110
2418   USA
2419
2420   EMail: fielding@gbiv.com
2421   URI:   http://roy.gbiv.com/
2422
2423
2424   Mark Nottingham (editor)
2425   Akamai
2426
2427   EMail: mnot@mnot.net
2428   URI:   http://www.mnot.net/
2429
2430
2431   Julian F. Reschke (editor)
2432   greenbytes GmbH
2433   Hafenweg 16
2434   Muenster, NW  48155
2435   Germany
2436
2437   EMail: julian.reschke@greenbytes.de
2438   URI:   http://greenbytes.de/tech/webdav/
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463Fielding, et al.         Expires March 29, 2014                [Page 44]
2464
Note: See TracBrowser for help on using the repository browser.