source: draft-ietf-httpbis/25/draft-ietf-httpbis-p6-cache-25.txt @ 2719

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

prepare publication of -25 drafts on 2013-11-17

  • Property svn:eol-style set to native
File size: 90.0 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: May 21, 2014                                    J. Reschke, Ed.
9                                                              greenbytes
10                                                       November 17, 2013
11
12
13            Hypertext Transfer Protocol (HTTP/1.1): Caching
14                     draft-ietf-httpbis-p6-cache-25
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.1.
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 May 21, 2014                  [Page 1]
56
57Internet-Draft              HTTP/1.1 Caching               November 2013
58
59
60   This Internet-Draft will expire on May 21, 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  . . . . . . . . . . . . . . . .  8
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  . . . . . . . . . . . . . . . 15
107     4.3.  Validation . . . . . . . . . . . . . . . . . . . . . . . . 15
108
109
110
111Fielding, et al.          Expires May 21, 2014                  [Page 2]
112
113Internet-Draft              HTTP/1.1 Caching               November 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  . . . . . . . . . . . . 19
121     4.4.  Invalidation . . . . . . . . . . . . . . . . . . . . . . . 19
122   5.  Header Field Definitions . . . . . . . . . . . . . . . . . . . 20
123     5.1.  Age  . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
124     5.2.  Cache-Control  . . . . . . . . . . . . . . . . . . . . . . 21
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" . . . . . . . . . . 31
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  . . . . . . . . . . . . . . . . . . . . 33
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-24 . . . . . . . . . . . 40
159   Index  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
160
161
162
163
164
165
166
167Fielding, et al.          Expires May 21, 2014                  [Page 3]
168
169Internet-Draft              HTTP/1.1 Caching               November 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 May 21, 2014                  [Page 4]
224
225Internet-Draft              HTTP/1.1 Caching               November 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   A recipient parsing a delta-seconds value and converting it to binary
236   form ought to use an arithmetic type of at least 31 bits of non-
237   negative integer range.  If a cache receives a delta-seconds value
238   greater than the greatest integer it can represent, or if any of its
239   subsequent calculations overflows, the cache MUST consider the value
240   to be either 2147483648 (2^31) or the greatest positive integer it
241   can conveniently represent.
242
243      Note: The value 2147483648 is here for historical reasons,
244      effectively represents infinity (over 68 years), and does not need
245      to be stored in binary form; an implementation could produce it as
246      a canned string if any overflow occurs, even if the calculations
247      are performed with an arithmetic type incapable of directly
248      representing that number.  What matters here is that an overflow
249      be detected and not treated as a negative value in later
250      calculations.
251
2522.  Overview of Cache Operation
253
254   Proper cache operation preserves the semantics of HTTP transfers
255   ([Part2]) while eliminating the transfer of information already held
256   in the cache.  Although caching is an entirely OPTIONAL feature of
257   HTTP, we assume that reusing the cached response is desirable and
258   that such reuse is the default behavior when no requirement or local
259   configuration prevents it.  Therefore, HTTP cache requirements are
260   focused on preventing a cache from either storing a non-reusable
261   response or reusing a stored response inappropriately, rather than
262   mandating that caches always store and reuse particular responses.
263
264   Each cache entry consists of a cache key and one or more HTTP
265   responses corresponding to prior requests that used the same key.
266   The most common form of cache entry is a successful result of a
267   retrieval request: i.e., a 200 (OK) response to a GET request, which
268   contains a representation of the resource identified by the request
269   target (Section 4.3.1 of [Part2]).  However, it is also possible to
270   cache permanent redirects, negative results (e.g., 404 (Not Found)),
271   incomplete results (e.g., 206 (Partial Content)), and responses to
272   methods other than GET if the method's definition allows such caching
273   and defines something suitable for use as a cache key.
274
275   The primary cache key consists of the request method and target URI.
276
277
278
279Fielding, et al.          Expires May 21, 2014                  [Page 5]
280
281Internet-Draft              HTTP/1.1 Caching               November 2013
282
283
284   However, since HTTP caches in common use today are typically limited
285   to caching responses to GET, many caches simply decline other methods
286   and use only the URI as the primary cache key.
287
288   If a request target is subject to content negotiation, its cache
289   entry might consist of multiple stored responses, each differentiated
290   by a secondary key for the values of the original request's selecting
291   header fields (Section 4.1).
292
2933.  Storing Responses in Caches
294
295   A cache MUST NOT store a response to any request, unless:
296
297   o  The request method is understood by the cache and defined as being
298      cacheable, and
299
300   o  the response status code is understood by the cache, and
301
302   o  the "no-store" cache directive (see Section 5.2) does not appear
303      in request or response header fields, and
304
305   o  the "private" cache response directive (see Section 5.2.2.6) does
306      not appear in the response, if the cache is shared, and
307
308   o  the Authorization header field (see Section 4.1 of [Part7]) does
309      not appear in the request, if the cache is shared, unless the
310      response explicitly allows it (see Section 3.2), and
311
312   o  the response either:
313
314      *  contains an Expires header field (see Section 5.3), or
315
316      *  contains a max-age response cache directive (see
317         Section 5.2.2.8), or
318
319      *  contains a s-maxage response cache directive (see
320         Section 5.2.2.9) and the cache is shared, or
321
322      *  contains a Cache Control Extension (see Section 5.2.3) that
323         allows it to be cached, or
324
325      *  has a status code that is defined as cacheable by default (see
326         Section 4.2.2), or
327
328      *  contains a public response cache directive (see
329         Section 5.2.2.5).
330
331   Note that any of the requirements listed above can be overridden by a
332
333
334
335Fielding, et al.          Expires May 21, 2014                  [Page 6]
336
337Internet-Draft              HTTP/1.1 Caching               November 2013
338
339
340   cache-control extension; see Section 5.2.3.
341
342   In this context, a cache has "understood" a request method or a
343   response status code if it recognizes it and implements all specified
344   caching-related behavior.
345
346   Note that, in normal operation, some caches will not store a response
347   that has neither a cache validator nor an explicit expiration time,
348   as such responses are not usually useful to store.  However, caches
349   are not prohibited from storing such responses.
350
3513.1.  Storing Incomplete Responses
352
353   A response message is considered complete when all of the octets
354   indicated by the message framing ([Part1]) are received prior to the
355   connection being closed.  If the request method is GET, the response
356   status code is 200 (OK), and the entire response header section has
357   been received, a cache MAY store an incomplete response message body
358   if the cache entry is recorded as incomplete.  Likewise, a 206
359   (Partial Content) response MAY be stored as if it were an incomplete
360   200 (OK) cache entry.  However, a cache MUST NOT store incomplete or
361   partial content responses if it does not support the Range and
362   Content-Range header fields or if it does not understand the range
363   units used in those fields.
364
365   A cache MAY complete a stored incomplete response by making a
366   subsequent range request ([Part5]) and combining the successful
367   response with the stored entry, as defined in Section 3.3.  A cache
368   MUST NOT use an incomplete response to answer requests unless the
369   response has been made complete or the request is partial and
370   specifies a range that is wholly within the incomplete response.  A
371   cache MUST NOT send a partial response to a client without explicitly
372   marking it as such using the 206 (Partial Content) status code.
373
3743.2.  Storing Responses to Authenticated Requests
375
376   A shared cache MUST NOT use a cached response to a request with an
377   Authorization header field (Section 4.1 of [Part7]) to satisfy any
378   subsequent request unless a cache directive that allows such
379   responses to be stored is present in the response.
380
381   In this specification, the following Cache-Control response
382   directives (Section 5.2.2) have such an effect: must-revalidate,
383   public, s-maxage.
384
385   Note that cached responses that contain the "must-revalidate" and/or
386   "s-maxage" response directives are not allowed to be served stale
387   (Section 4.2.4) by shared caches.  In particular, a response with
388
389
390
391Fielding, et al.          Expires May 21, 2014                  [Page 7]
392
393Internet-Draft              HTTP/1.1 Caching               November 2013
394
395
396   either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to
397   satisfy a subsequent request without revalidating it on the origin
398   server.
399
4003.3.  Combining Partial Content
401
402   A response might transfer only a partial representation if the
403   connection closed prematurely or if the request used one or more
404   Range specifiers ([Part5]).  After several such transfers, a cache
405   might have received several ranges of the same representation.  A
406   cache MAY combine these ranges into a single stored response, and
407   reuse that response to satisfy later requests, if they all share the
408   same strong validator and the cache complies with the client
409   requirements in Section 4.3 of [Part5].
410
411   When combining the new response with one or more stored responses, a
412   cache MUST:
413
414   o  delete any Warning header fields in the stored response with warn-
415      code 1xx (see Section 5.5);
416
417   o  retain any Warning header fields in the stored response with warn-
418      code 2xx; and,
419
420   o  use other header fields provided in the new response, aside from
421      Content-Range, to replace all instances of the corresponding
422      header fields in the stored response.
423
4244.  Constructing Responses from Caches
425
426   When presented with a request, a cache MUST NOT reuse a stored
427   response, unless:
428
429   o  The presented effective request URI (Section 5.5 of [Part1]) and
430      that of the stored response match, and
431
432   o  the request method associated with the stored response allows it
433      to be used for the presented request, and
434
435   o  selecting header fields nominated by the stored response (if any)
436      match those presented (see Section 4.1), and
437
438   o  the presented request does not contain the no-cache pragma
439      (Section 5.4), nor the no-cache cache directive (Section 5.2.1),
440      unless the stored response is successfully validated
441      (Section 4.3), and
442
443
444
445
446
447Fielding, et al.          Expires May 21, 2014                  [Page 8]
448
449Internet-Draft              HTTP/1.1 Caching               November 2013
450
451
452   o  the stored response does not contain the no-cache cache directive
453      (Section 5.2.2.2), unless it is successfully validated
454      (Section 4.3), and
455
456   o  the stored response is either:
457
458      *  fresh (see Section 4.2), or
459
460      *  allowed to be served stale (see Section 4.2.4), or
461
462      *  successfully validated (see Section 4.3).
463
464   Note that any of the requirements listed above can be overridden by a
465   cache-control extension; see Section 5.2.3.
466
467   When a stored response is used to satisfy a request without
468   validation, a cache MUST generate an Age header field (Section 5.1),
469   replacing any present in the response with a value equal to the
470   stored response's current_age; see Section 4.2.3.
471
472   A cache MUST write through requests with methods that are unsafe
473   (Section 4.2.1 of [Part2]) to the origin server; i.e., a cache is not
474   allowed to generate a reply to such a request before having forwarded
475   the request and having received a corresponding response.
476
477   Also, note that unsafe requests might invalidate already stored
478   responses; see Section 4.4.
479
480   When more than one suitable response is stored, a cache MUST use the
481   most recent response (as determined by the Date header field).  It
482   can also forward the request with "Cache-Control: max-age=0" or
483   "Cache-Control: no-cache" to disambiguate which response to use.
484
485   A cache that does not have a clock available MUST NOT use stored
486   responses without revalidating them upon every use.
487
4884.1.  Calculating Secondary Keys with Vary
489
490   When a cache receives a request that can be satisfied by a stored
491   response that has a Vary header field (Section 7.1.4 of [Part2]), it
492   MUST NOT use that response unless all of the selecting header fields
493   nominated by the Vary header field match in both the original request
494   (i.e., that associated with the stored response), and the presented
495   request.
496
497   The selecting header fields from two requests are defined to match if
498   and only if those in the first request can be transformed to those in
499   the second request by applying any of the following:
500
501
502
503Fielding, et al.          Expires May 21, 2014                  [Page 9]
504
505Internet-Draft              HTTP/1.1 Caching               November 2013
506
507
508   o  adding or removing whitespace, where allowed in the header field's
509      syntax
510
511   o  combining multiple header fields with the same field name (see
512      Section 3.2 of [Part1])
513
514   o  normalizing both header field values in a way that is known to
515      have identical semantics, according to the header field's
516      specification (e.g., re-ordering field values when order is not
517      significant; case-normalization, where values are defined to be
518      case-insensitive)
519
520   If (after any normalization that might take place) a header field is
521   absent from a request, it can only match another request if it is
522   also absent there.
523
524   A Vary header field-value of "*" always fails to match.
525
526   The stored response with matching selecting header fields is known as
527   the selected response.
528
529   If multiple selected responses are available (potentially including
530   responses without a Vary header field), the cache will need to choose
531   one to use.  When a selecting header field has a known mechanism for
532   doing so (e.g., qvalues on Accept and similar request header fields),
533   that mechanism MAY be used to select preferred responses; of the
534   remainder, the most recent response (as determined by the Date header
535   field) is used, as per Section 4.
536
537   If no selected response is available, the cache cannot satisfy the
538   presented request.  Typically, it is forwarded to the origin server
539   in a (possibly conditional; see Section 4.3) request.
540
5414.2.  Freshness
542
543   A fresh response is one whose age has not yet exceeded its freshness
544   lifetime.  Conversely, a stale response is one where it has.
545
546   A response's freshness lifetime is the length of time between its
547   generation by the origin server and its expiration time.  An explicit
548   expiration time is the time at which the origin server intends that a
549   stored response can no longer be used by a cache without further
550   validation, whereas a heuristic expiration time is assigned by a
551   cache when no explicit expiration time is available.
552
553   A response's age is the time that has passed since it was generated
554   by, or successfully validated with, the origin server.
555
556
557
558
559Fielding, et al.          Expires May 21, 2014                 [Page 10]
560
561Internet-Draft              HTTP/1.1 Caching               November 2013
562
563
564   When a response is "fresh" in the cache, it can be used to satisfy
565   subsequent requests without contacting the origin server, thereby
566   improving efficiency.
567
568   The primary mechanism for determining freshness is for an origin
569   server to provide an explicit expiration time in the future, using
570   either the Expires header field (Section 5.3) or the max-age response
571   cache directive (Section 5.2.2.8).  Generally, origin servers will
572   assign future explicit expiration times to responses in the belief
573   that the representation is not likely to change in a semantically
574   significant way before the expiration time is reached.
575
576   If an origin server wishes to force a cache to validate every
577   request, it can assign an explicit expiration time in the past to
578   indicate that the response is already stale.  Compliant caches will
579   normally validate a stale cached response before reusing it for
580   subsequent requests (see Section 4.2.4).
581
582   Since origin servers do not always provide explicit expiration times,
583   caches are also allowed to use a heuristic to determine an expiration
584   time under certain circumstances (see Section 4.2.2).
585
586   The calculation to determine if a response is fresh is:
587
588      response_is_fresh = (freshness_lifetime > current_age)
589
590   freshness_lifetime is defined in Section 4.2.1; current_age is
591   defined in Section 4.2.3.
592
593   Clients can send the max-age or min-fresh cache directives in a
594   request to constrain or relax freshness calculations for the
595   corresponding response (Section 5.2.1).
596
597   When calculating freshness, to avoid common problems in date parsing:
598
599   o  Although all date formats are specified to be case-sensitive, a
600      cache recipient SHOULD match day, week, and timezone names case-
601      insensitively.
602
603   o  If a cache recipient's internal implementation of time has less
604      resolution than the value of an HTTP-date, the recipient MUST
605      internally represent a parsed Expires date as the nearest time
606      equal to or earlier than the received value.
607
608   o  A cache recipient MUST NOT allow local time zones to influence the
609      calculation or comparison of an age or expiration time.
610
611
612
613
614
615Fielding, et al.          Expires May 21, 2014                 [Page 11]
616
617Internet-Draft              HTTP/1.1 Caching               November 2013
618
619
620   o  A cache recipient SHOULD consider a date with a zone abbreviation
621      other than GMT or UTC to be invalid for calculating expiration.
622
623   Note that freshness applies only to cache operation; it cannot be
624   used to force a user agent to refresh its display or reload a
625   resource.  See Section 6 for an explanation of the difference between
626   caches and history mechanisms.
627
6284.2.1.  Calculating Freshness Lifetime
629
630   A cache can calculate the freshness lifetime (denoted as
631   freshness_lifetime) of a response by using the first match of:
632
633   o  If the cache is shared and the s-maxage response cache directive
634      (Section 5.2.2.9) is present, use its value, or
635
636   o  If the max-age response cache directive (Section 5.2.2.8) is
637      present, use its value, or
638
639   o  If the Expires response header field (Section 5.3) is present, use
640      its value minus the value of the Date response header field, or
641
642   o  Otherwise, no explicit expiration time is present in the response.
643      A heuristic freshness lifetime might be applicable; see
644      Section 4.2.2.
645
646   Note that this calculation is not vulnerable to clock skew, since all
647   of the information comes from the origin server.
648
649   When there is more than one value present for a given directive
650   (e.g., two Expires header fields, multiple Cache-Control: max-age
651   directives), the directive's value is considered invalid.  Caches are
652   encouraged to consider responses that have invalid freshness
653   information to be stale.
654
6554.2.2.  Calculating Heuristic Freshness
656
657   Since origin servers do not always provide explicit expiration times,
658   a cache MAY assign a heuristic expiration time when an explicit time
659   is not specified, employing algorithms that use other header field
660   values (such as the Last-Modified time) to estimate a plausible
661   expiration time.  This specification does not provide specific
662   algorithms, but does impose worst-case constraints on their results.
663
664   A cache MUST NOT use heuristics to determine freshness when an
665   explicit expiration time is present in the stored response.  Because
666   of the requirements in Section 3, this means that, effectively,
667   heuristics can only be used on responses without explicit freshness
668
669
670
671Fielding, et al.          Expires May 21, 2014                 [Page 12]
672
673Internet-Draft              HTTP/1.1 Caching               November 2013
674
675
676   whose status codes are defined as cacheable by default (see Section
677   6.1 of [Part2]), and those responses without explicit freshness that
678   have been marked as explicitly cacheable (e.g., with a "public"
679   response cache directive).
680
681   If the response has a Last-Modified header field (Section 2.2 of
682   [Part4]), caches are encouraged to use a heuristic expiration value
683   that is no more than some fraction of the interval since that time.
684   A typical setting of this fraction might be 10%.
685
686   When a heuristic is used to calculate freshness lifetime, a cache
687   SHOULD generate a Warning header field with a 113 warn-code (see
688   Section 5.5.4) in the response if its current_age is more than 24
689   hours and such a warning is not already present.
690
691      Note: Section 13.9 of [RFC2616] prohibited caches from calculating
692      heuristic freshness for URIs with query components (i.e., those
693      containing '?').  In practice, this has not been widely
694      implemented.  Therefore, origin servers are encouraged to send
695      explicit directives (e.g., Cache-Control: no-cache) if they wish
696      to preclude caching.
697
6984.2.3.  Calculating Age
699
700   The Age header field is used to convey an estimated age of the
701   response message when obtained from a cache.  The Age field value is
702   the cache's estimate of the number of seconds since the response was
703   generated or validated by the origin server.  In essence, the Age
704   value is the sum of the time that the response has been resident in
705   each of the caches along the path from the origin server, plus the
706   amount of time it has been in transit along network paths.
707
708   The following data is used for the age calculation:
709
710   age_value
711
712      The term "age_value" denotes the value of the Age header field
713      (Section 5.1), in a form appropriate for arithmetic operation; or
714      0, if not available.
715
716   date_value
717
718      The term "date_value" denotes the value of the Date header field,
719      in a form appropriate for arithmetic operations.  See Section
720      7.1.1.2 of [Part2] for the definition of the Date header field,
721      and for requirements regarding responses without it.
722
723
724
725
726
727Fielding, et al.          Expires May 21, 2014                 [Page 13]
728
729Internet-Draft              HTTP/1.1 Caching               November 2013
730
731
732   now
733
734      The term "now" means "the current value of the clock at the host
735      performing the calculation".  A host ought to use NTP ([RFC5905])
736      or some similar protocol to synchronize its clocks to Coordinated
737      Universal Time.
738
739   request_time
740
741      The current value of the clock at the host at the time the request
742      resulting in the stored response was made.
743
744   response_time
745
746      The current value of the clock at the host at the time the
747      response was received.
748
749   A response's age can be calculated in two entirely independent ways:
750
751   1.  the "apparent_age": response_time minus date_value, if the local
752       clock is reasonably well synchronized to the origin server's
753       clock.  If the result is negative, the result is replaced by
754       zero.
755
756   2.  the "corrected_age_value", if all of the caches along the
757       response path implement HTTP/1.1.  A cache MUST interpret this
758       value relative to the time the request was initiated, not the
759       time that the response was received.
760
761
762     apparent_age = max(0, response_time - date_value);
763
764     response_delay = response_time - request_time;
765     corrected_age_value = age_value + response_delay;
766
767   These are combined as
768
769     corrected_initial_age = max(apparent_age, corrected_age_value);
770
771   unless the cache is confident in the value of the Age header field
772   (e.g., because there are no HTTP/1.0 hops in the Via header field),
773   in which case the corrected_age_value MAY be used as the
774   corrected_initial_age.
775
776   The current_age of a stored response can then be calculated by adding
777   the amount of time (in seconds) since the stored response was last
778   validated by the origin server to the corrected_initial_age.
779
780
781
782
783Fielding, et al.          Expires May 21, 2014                 [Page 14]
784
785Internet-Draft              HTTP/1.1 Caching               November 2013
786
787
788     resident_time = now - response_time;
789     current_age = corrected_initial_age + resident_time;
790
7914.2.4.  Serving Stale Responses
792
793   A "stale" response is one that either has explicit expiry information
794   or is allowed to have heuristic expiry calculated, but is not fresh
795   according to the calculations in Section 4.2.
796
797   A cache MUST NOT generate a stale response if it is prohibited by an
798   explicit in-protocol directive (e.g., by a "no-store" or "no-cache"
799   cache directive, a "must-revalidate" cache-response-directive, or an
800   applicable "s-maxage" or "proxy-revalidate" cache-response-directive;
801   see Section 5.2.2).
802
803   A cache MUST NOT send stale responses unless it is disconnected
804   (i.e., it cannot contact the origin server or otherwise find a
805   forward path) or doing so is explicitly allowed (e.g., by the max-
806   stale request directive; see Section 5.2.1).
807
808   A cache SHOULD generate a Warning header field with the 110 warn-code
809   (see Section 5.5.1) in stale responses.  Likewise, a cache SHOULD
810   generate a 112 warn-code (see Section 5.5.3) in stale responses if
811   the cache is disconnected.
812
813   A cache SHOULD NOT generate a new Warning header field when
814   forwarding a response that does not have an Age header field, even if
815   the response is already stale.  A cache need not validate a response
816   that merely became stale in transit.
817
8184.3.  Validation
819
820   When a cache has one or more stored responses for a requested URI,
821   but cannot serve any of them (e.g., because they are not fresh, or
822   one cannot be selected; see Section 4.1), it can use the conditional
823   request mechanism [Part4] in the forwarded request to give the next
824   inbound server an opportunity to select a valid stored response to
825   use, updating the stored metadata in the process, or to replace the
826   stored response(s) with a new response.  This process is known as
827   "validating" or "revalidating" the stored response.
828
8294.3.1.  Sending a Validation Request
830
831   When sending a conditional request for cache validation, a cache
832   sends one or more precondition header fields containing validator
833   metadata from its stored response(s), which is then compared by
834   recipients to determine whether a stored response is equivalent to a
835   current representation of the resource.
836
837
838
839Fielding, et al.          Expires May 21, 2014                 [Page 15]
840
841Internet-Draft              HTTP/1.1 Caching               November 2013
842
843
844   One such validator is the timestamp given in a Last-Modified header
845   field (Section 2.2 of [Part4]), which can be used in an If-Modified-
846   Since header field for response validation, or in an If-Unmodified-
847   Since or If-Range header field for representation selection (i.e.,
848   the client is referring specifically to a previously obtained
849   representation with that timestamp).
850
851   Another validator is the entity-tag given in an ETag header field
852   (Section 2.3 of [Part4]).  One or more entity-tags, indicating one or
853   more stored responses, can be used in an If-None-Match header field
854   for response validation, or in an If-Match or If-Range header field
855   for representation selection (i.e., the client is referring
856   specifically to one or more previously obtained representations with
857   the listed entity-tags).
858
8594.3.2.  Handling a Received Validation Request
860
861   Each client in the request chain may have its own cache, so it is
862   common for a cache at an intermediary to receive conditional requests
863   from other (outbound) caches.  Likewise, some user agents make use of
864   conditional requests to limit data transfers to recently modified
865   representations or to complete the transfer of a partially retrieved
866   representation.
867
868   If a cache receives a request that can be satisfied by reusing one of
869   its stored 200 (OK) or 206 (Partial Content) responses, the cache
870   SHOULD evaluate any applicable conditional header field preconditions
871   received in that request with respect to the corresponding validators
872   contained within the selected response.  A cache MUST NOT evaluate
873   conditional header fields that are only applicable to an origin
874   server, found in a request with semantics that cannot be satisfied
875   with a cached response, or applied to a target resource for which it
876   has no stored responses; such preconditions are likely intended for
877   some other (inbound) server.
878
879   The proper evaluation of conditional requests by a cache depends on
880   the received precondition header fields and their precedence, as
881   defined in Section 6 of [Part4].  The If-Match and If-Unmodified-
882   Since conditional header fields are not applicable to a cache.
883
884   A request containing an If-None-Match header field (Section 3.2 of
885   [Part4]) indicates that the client wants to validate one or more of
886   its own stored responses in comparison to whichever stored response
887   is selected by the cache.  If the field-value is "*", or if the
888   field-value is a list of entity-tags and at least one of them match
889   the entity-tag of the selected stored response, a cache recipient
890   SHOULD generate a 304 (Not Modified) response (using the metadata of
891   the selected stored response) instead of sending that stored
892
893
894
895Fielding, et al.          Expires May 21, 2014                 [Page 16]
896
897Internet-Draft              HTTP/1.1 Caching               November 2013
898
899
900   response.
901
902   When a cache decides to revalidate its own stored responses for a
903   request that contains an If-None-Match list of entity-tags, the cache
904   MAY combine the received list with a list of entity-tags from its own
905   stored set of responses (fresh or stale) and send the union of the
906   two lists as a replacement If-None-Match header field value in the
907   forwarded request.  If a stored response contains only partial
908   content, the cache MUST NOT include its entity-tag in the union
909   unless the request is for a range that would be fully satisfied by
910   that partial stored response.  If the response to the forwarded
911   request is 304 (Not Modified) and has an ETag header field value with
912   an entity-tag that is not in the client's list, the cache MUST
913   generate a 200 (OK) response for the client by reusing its
914   corresponding stored response, as updated by the 304 response
915   metadata (Section 4.3.4).
916
917   If an If-None-Match header field is not present, a request containing
918   an If-Modified-Since header field (Section 3.3 of [Part4]) indicates
919   that the client wants to validate one or more of its own stored
920   responses by modification date.  A cache recipient SHOULD generate a
921   304 (Not Modified) response (using the metadata of the selected
922   stored response) if one of the following cases is true: 1) the
923   selected stored response has a Last-Modified field-value that is
924   earlier than or equal to the conditional timestamp; 2) no Last-
925   Modified field is present in the selected stored response, but it has
926   a Date field-value that is earlier than or equal to the conditional
927   timestamp; or, 3) neither Last-Modified nor Date is present in the
928   selected stored response, but the cache recorded it as having been
929   received at a time earlier than or equal to the conditional
930   timestamp.
931
932   A cache that implements partial responses to range requests, as
933   defined in [Part5], also needs to evaluate a received If-Range header
934   field (Section 3.2 of [Part5]) with respect to its selected stored
935   response.
936
9374.3.3.  Handling a Validation Response
938
939   Cache handling of a response to a conditional request is dependent
940   upon its status code:
941
942   o  A 304 (Not Modified) response status code indicates that the
943      stored response can be updated and reused; see Section 4.3.4.
944
945   o  A full response (i.e., one with a payload body) indicates that
946      none of the stored responses nominated in the conditional request
947      is suitable.  Instead, the cache MUST use the full response to
948
949
950
951Fielding, et al.          Expires May 21, 2014                 [Page 17]
952
953Internet-Draft              HTTP/1.1 Caching               November 2013
954
955
956      satisfy the request and MAY replace the stored response(s).
957
958   o  However, if a cache receives a 5xx (Server Error) response while
959      attempting to validate a response, it can either forward this
960      response to the requesting client, or act as if the server failed
961      to respond.  In the latter case, the cache MAY send a previously
962      stored response (see Section 4.2.4).
963
9644.3.4.  Freshening Stored Responses upon Validation
965
966   When a cache receives a 304 (Not Modified) response and already has
967   one or more stored 200 (OK) responses for the same cache key, the
968   cache needs to identify which of the stored responses are updated by
969   this new response and then update the stored response(s) with the new
970   information provided in the 304 response.
971
972   The stored response to update is identified by using the first match
973   (if any) of:
974
975   o  If the new response contains a strong validator (see Section 2.1
976      of [Part4]), then that strong validator identifies the selected
977      representation for update.  All of the stored responses with the
978      same strong validator are selected.  If none of the stored
979      responses contain the same strong validator, then the cache MUST
980      NOT use the new response to update any stored responses.
981
982   o  If the new response contains a weak validator and that validator
983      corresponds to one of the cache's stored responses, then the most
984      recent of those matching stored responses is selected for update.
985
986   o  If the new response does not include any form of validator (such
987      as in the case where a client generates an If-Modified-Since
988      request from a source other than the Last-Modified response header
989      field), and there is only one stored response, and that stored
990      response also lacks a validator, then that stored response is
991      selected for update.
992
993   If a stored response is selected for update, the cache MUST:
994
995   o  delete any Warning header fields in the stored response with warn-
996      code 1xx (see Section 5.5);
997
998   o  retain any Warning header fields in the stored response with warn-
999      code 2xx; and,
1000
1001   o  use other header fields provided in the 304 (Not Modified)
1002      response to replace all instances of the corresponding header
1003      fields in the stored response.
1004
1005
1006
1007Fielding, et al.          Expires May 21, 2014                 [Page 18]
1008
1009Internet-Draft              HTTP/1.1 Caching               November 2013
1010
1011
10124.3.5.  Freshening Responses via HEAD
1013
1014   A response to the HEAD method is identical to what an equivalent
1015   request made with a GET would have been, except it lacks a body.
1016   This property of HEAD responses can be used to invalidate or update a
1017   cached GET response if the more efficient conditional GET request
1018   mechanism is not available (due to no validators being present in the
1019   stored response) or if transmission of the representation body is not
1020   desired even if it has changed.
1021
1022   When a cache makes an inbound HEAD request for a given request target
1023   and receives a 200 (OK) response, the cache SHOULD update or
1024   invalidate each of its stored GET responses that could have been
1025   selected for that request (see Section 4.1).
1026
1027   For each of the stored responses that could have been selected, if
1028   the stored response and HEAD response have matching values for any
1029   received validator fields (ETag and Last-Modified) and, if the HEAD
1030   response has a Content-Length header field, the value of Content-
1031   Length matches that of the stored response, the cache SHOULD update
1032   the stored response a described below; otherwise, the cache SHOULD
1033   consider the stored response to be stale.
1034
1035   If a cache updates a stored response with the metadata provided in a
1036   HEAD response, the cache MUST:
1037
1038   o  delete any Warning header fields in the stored response with warn-
1039      code 1xx (see Section 5.5);
1040
1041   o  retain any Warning header fields in the stored response with warn-
1042      code 2xx; and,
1043
1044   o  use other header fields provided in the HEAD response to replace
1045      all instances of the corresponding header fields in the stored
1046      response and append new header fields to the stored response's
1047      header section unless otherwise restricted by the Cache-Control
1048      header field.
1049
10504.4.  Invalidation
1051
1052   Because unsafe request methods (Section 4.2.1 of [Part2]) such as
1053   PUT, POST or DELETE have the potential for changing state on the
1054   origin server, intervening caches can use them to keep their contents
1055   up-to-date.
1056
1057   A cache MUST invalidate the effective Request URI (Section 5.5 of
1058   [Part1]) as well as the URI(s) in the Location and Content-Location
1059   response header fields (if present) when a non-error status code is
1060
1061
1062
1063Fielding, et al.          Expires May 21, 2014                 [Page 19]
1064
1065Internet-Draft              HTTP/1.1 Caching               November 2013
1066
1067
1068   received in response to an unsafe request method.
1069
1070   However, a cache MUST NOT invalidate a URI from a Location or
1071   Content-Location response header field if the host part of that URI
1072   differs from the host part in the effective request URI (Section 5.5
1073   of [Part1]).  This helps prevent denial of service attacks.
1074
1075   A cache MUST invalidate the effective request URI (Section 5.5 of
1076   [Part1]) when it receives a non-error response to a request with a
1077   method whose safety is unknown.
1078
1079   Here, a "non-error response" is one with a 2xx (Successful) or 3xx
1080   (Redirection) status code.  "Invalidate" means that the cache will
1081   either remove all stored responses related to the effective request
1082   URI, or will mark these as "invalid" and in need of a mandatory
1083   validation before they can be sent in response to a subsequent
1084   request.
1085
1086   Note that this does not guarantee that all appropriate responses are
1087   invalidated.  For example, a state-changing request might invalidate
1088   responses in the caches it travels through, but relevant responses
1089   still might be stored in other caches that it has not.
1090
10915.  Header Field Definitions
1092
1093   This section defines the syntax and semantics of HTTP/1.1 header
1094   fields related to caching.
1095
10965.1.  Age
1097
1098   The "Age" header field conveys the sender's estimate of the amount of
1099   time since the response was generated or successfully validated at
1100   the origin server.  Age values are calculated as specified in
1101   Section 4.2.3.
1102
1103     Age = delta-seconds
1104
1105   The Age field-value is a non-negative integer, representing time in
1106   seconds (see Section 1.2.1).
1107
1108   The presence of an Age header field implies that the response was not
1109   generated or validated by the origin server for this request.
1110   However, lack of an Age header field does not imply the origin was
1111   contacted, since the response might have been received from an
1112   HTTP/1.0 cache that does not implement Age.
1113
1114
1115
1116
1117
1118
1119Fielding, et al.          Expires May 21, 2014                 [Page 20]
1120
1121Internet-Draft              HTTP/1.1 Caching               November 2013
1122
1123
11245.2.  Cache-Control
1125
1126   The "Cache-Control" header field is used to specify directives for
1127   caches along the request/response chain.  Such cache directives are
1128   unidirectional in that the presence of a directive in a request does
1129   not imply that the same directive is to be given in the response.
1130
1131   A cache MUST obey the requirements of the Cache-Control directives
1132   defined in this section.  See Section 5.2.3 for information about how
1133   Cache-Control directives defined elsewhere are handled.
1134
1135      Note: Some HTTP/1.0 caches might not implement Cache-Control.
1136
1137   A proxy, whether or not it implements a cache, MUST pass cache
1138   directives through in forwarded messages, regardless of their
1139   significance to that application, since the directives might be
1140   applicable to all recipients along the request/response chain.  It is
1141   not possible to target a directive to a specific cache.
1142
1143   Cache directives are identified by a token, to be compared case-
1144   insensitively, and have an optional argument, that can use both token
1145   and quoted-string syntax.  For the directives defined below that
1146   define arguments, recipients ought to accept both forms, even if one
1147   is documented to be preferred.  For any directive not defined by this
1148   specification, a recipient MUST accept both forms.
1149
1150     Cache-Control   = 1#cache-directive
1151
1152     cache-directive = token [ "=" ( token / quoted-string ) ]
1153
1154   For the cache directives defined below, no argument is defined (nor
1155   allowed) unless stated otherwise.
1156
11575.2.1.  Request Cache-Control Directives
1158
11595.2.1.1.  max-age
1160
1161   Argument syntax:
1162
1163      delta-seconds (see Section 1.2.1)
1164
1165   The "max-age" request directive indicates that the client is
1166   unwilling to accept a response whose age is greater than the
1167   specified number of seconds.  Unless the max-stale request directive
1168   is also present, the client is not willing to accept a stale
1169   response.
1170
1171   This directive uses the token form of the argument syntax; e.g.,
1172
1173
1174
1175Fielding, et al.          Expires May 21, 2014                 [Page 21]
1176
1177Internet-Draft              HTTP/1.1 Caching               November 2013
1178
1179
1180   'max-age=5', not 'max-age="5"'.  A sender SHOULD NOT generate the
1181   quoted-string form.
1182
11835.2.1.2.  max-stale
1184
1185   Argument syntax:
1186
1187      delta-seconds (see Section 1.2.1)
1188
1189   The "max-stale" request directive indicates that the client is
1190   willing to accept a response that has exceeded its freshness
1191   lifetime.  If max-stale is assigned a value, then the client is
1192   willing to accept a response that has exceeded its freshness lifetime
1193   by no more than the specified number of seconds.  If no value is
1194   assigned to max-stale, then the client is willing to accept a stale
1195   response of any age.
1196
1197   This directive uses the token form of the argument syntax; e.g.,
1198   'max-stale=10', not 'max-stale="10"'.  A sender SHOULD NOT generate
1199   the quoted-string form.
1200
12015.2.1.3.  min-fresh
1202
1203   Argument syntax:
1204
1205      delta-seconds (see Section 1.2.1)
1206
1207   The "min-fresh" request directive indicates that the client is
1208   willing to accept a response whose freshness lifetime is no less than
1209   its current age plus the specified time in seconds.  That is, the
1210   client wants a response that will still be fresh for at least the
1211   specified number of seconds.
1212
1213   This directive uses the token form of the argument syntax; e.g.,
1214   'min-fresh=20', not 'min-fresh="20"'.  A sender SHOULD NOT generate
1215   the quoted-string form.
1216
12175.2.1.4.  no-cache
1218
1219   The "no-cache" request directive indicates that a cache MUST NOT use
1220   a stored response to satisfy the request without successful
1221   validation on the origin server.
1222
12235.2.1.5.  no-store
1224
1225   The "no-store" request directive indicates that a cache MUST NOT
1226   store any part of either this request or any response to it.  This
1227   directive applies to both private and shared caches.  "MUST NOT
1228
1229
1230
1231Fielding, et al.          Expires May 21, 2014                 [Page 22]
1232
1233Internet-Draft              HTTP/1.1 Caching               November 2013
1234
1235
1236   store" in this context means that the cache MUST NOT intentionally
1237   store the information in non-volatile storage, and MUST make a best-
1238   effort attempt to remove the information from volatile storage as
1239   promptly as possible after forwarding it.
1240
1241   This directive is NOT a reliable or sufficient mechanism for ensuring
1242   privacy.  In particular, malicious or compromised caches might not
1243   recognize or obey this directive, and communications networks might
1244   be vulnerable to eavesdropping.
1245
1246   Note that if a request containing this directive is satisfied from a
1247   cache, the no-store request directive does not apply to the already
1248   stored response.
1249
12505.2.1.6.  no-transform
1251
1252   The "no-transform" request directive indicates that an intermediary
1253   (whether or not it implements a cache) MUST NOT transform the
1254   payload, as defined in Section 5.7.2 of [Part1].
1255
12565.2.1.7.  only-if-cached
1257
1258   The "only-if-cached" request directive indicates that the client only
1259   wishes to obtain a stored response.  If it receives this directive, a
1260   cache SHOULD either respond using a stored response that is
1261   consistent with the other constraints of the request, or respond with
1262   a 504 (Gateway Timeout) status code.  If a group of caches is being
1263   operated as a unified system with good internal connectivity, a
1264   member cache MAY forward such a request within that group of caches.
1265
12665.2.2.  Response Cache-Control Directives
1267
12685.2.2.1.  must-revalidate
1269
1270   The "must-revalidate" response directive indicates that once it has
1271   become stale, a cache MUST NOT use the response to satisfy subsequent
1272   requests without successful validation on the origin server.
1273
1274   The must-revalidate directive is necessary to support reliable
1275   operation for certain protocol features.  In all circumstances a
1276   cache MUST obey the must-revalidate directive; in particular, if a
1277   cache cannot reach the origin server for any reason, it MUST generate
1278   a 504 (Gateway Timeout) response.
1279
1280   The must-revalidate directive ought to be used by servers if and only
1281   if failure to validate a request on the representation could result
1282   in incorrect operation, such as a silently unexecuted financial
1283   transaction.
1284
1285
1286
1287Fielding, et al.          Expires May 21, 2014                 [Page 23]
1288
1289Internet-Draft              HTTP/1.1 Caching               November 2013
1290
1291
12925.2.2.2.  no-cache
1293
1294   Argument syntax:
1295
1296      #field-name
1297
1298   The "no-cache" response directive indicates that the response MUST
1299   NOT be used to satisfy a subsequent request without successful
1300   validation on the origin server.  This allows an origin server to
1301   prevent a cache from using it to satisfy a request without contacting
1302   it, even by caches that have been configured to send stale responses.
1303
1304   If the no-cache response directive specifies one or more field-names,
1305   then a cache MAY use the response to satisfy a subsequent request,
1306   subject to any other restrictions on caching.  However, any header
1307   fields in the response that have the field-name(s) listed MUST NOT be
1308   sent in the response to a subsequent request without successful
1309   revalidation with the origin server.  This allows an origin server to
1310   prevent the re-use of certain header fields in a response, while
1311   still allowing caching of the rest of the response.
1312
1313   The field-names given are not limited to the set of header fields
1314   defined by this specification.  Field names are case-insensitive.
1315
1316   This directive uses the quoted-string form of the argument syntax.  A
1317   sender SHOULD NOT generate the token form (even if quoting appears
1318   not to be needed for single-entry lists).
1319
1320   Note: Although it has been back-ported to many implementations, some
1321   HTTP/1.0 caches will not recognize or obey this directive.  Also, no-
1322   cache response directives with field-names are often handled by
1323   caches as if an unqualified no-cache directive was received; i.e.,
1324   the special handling for the qualified form is not widely
1325   implemented.
1326
13275.2.2.3.  no-store
1328
1329   The "no-store" response directive indicates that a cache MUST NOT
1330   store any part of either the immediate request or response.  This
1331   directive applies to both private and shared caches.  "MUST NOT
1332   store" in this context means that the cache MUST NOT intentionally
1333   store the information in non-volatile storage, and MUST make a best-
1334   effort attempt to remove the information from volatile storage as
1335   promptly as possible after forwarding it.
1336
1337   This directive is NOT a reliable or sufficient mechanism for ensuring
1338   privacy.  In particular, malicious or compromised caches might not
1339   recognize or obey this directive, and communications networks might
1340
1341
1342
1343Fielding, et al.          Expires May 21, 2014                 [Page 24]
1344
1345Internet-Draft              HTTP/1.1 Caching               November 2013
1346
1347
1348   be vulnerable to eavesdropping.
1349
13505.2.2.4.  no-transform
1351
1352   The "no-transform" response directive indicates that an intermediary
1353   (regardless of whether it implements a cache) MUST NOT transform the
1354   payload, as defined in Section 5.7.2 of [Part1].
1355
13565.2.2.5.  public
1357
1358   The "public" response directive indicates that any cache MAY store
1359   the response, even if the response would normally be non-cacheable or
1360   cacheable only within a private cache.  (See Section 3.2 for
1361   additional details related to the use of public in response to a
1362   request containing Authorization, and Section 3 for details of how
1363   public affects responses that would normally not be stored, due to
1364   their status codes not being defined as cacheable by default; see
1365   Section 4.2.2.)
1366
13675.2.2.6.  private
1368
1369   Argument syntax:
1370
1371      #field-name
1372
1373   The "private" response directive indicates that the response message
1374   is intended for a single user and MUST NOT be stored by a shared
1375   cache.  A private cache MAY store the response and reuse it for later
1376   requests, even if the response would normally be non-cacheable.
1377
1378   If the private response directive specifies one or more field-names,
1379   this requirement is limited to the field-values associated with the
1380   listed response header fields.  That is, a shared cache MUST NOT
1381   store the specified field-names(s), whereas it MAY store the
1382   remainder of the response message.
1383
1384   The field-names given are not limited to the set of header fields
1385   defined by this specification.  Field names are case-insensitive.
1386
1387   This directive uses the quoted-string form of the argument syntax.  A
1388   sender SHOULD NOT generate the token form (even if quoting appears
1389   not to be needed for single-entry lists).
1390
1391   Note: This usage of the word "private" only controls where the
1392   response can be stored; it cannot ensure the privacy of the message
1393   content.  Also, private response directives with field-names are
1394   often handled by caches as if an unqualified private directive was
1395   received; i.e., the special handling for the qualified form is not
1396
1397
1398
1399Fielding, et al.          Expires May 21, 2014                 [Page 25]
1400
1401Internet-Draft              HTTP/1.1 Caching               November 2013
1402
1403
1404   widely implemented.
1405
14065.2.2.7.  proxy-revalidate
1407
1408   The "proxy-revalidate" response directive has the same meaning as the
1409   must-revalidate response directive, except that it does not apply to
1410   private caches.
1411
14125.2.2.8.  max-age
1413
1414   Argument syntax:
1415
1416      delta-seconds (see Section 1.2.1)
1417
1418   The "max-age" response directive indicates that the response is to be
1419   considered stale after its age is greater than the specified number
1420   of seconds.
1421
1422   This directive uses the token form of the argument syntax; e.g.,
1423   'max-age=5', not 'max-age="5"'.  A sender SHOULD NOT generate the
1424   quoted-string form.
1425
14265.2.2.9.  s-maxage
1427
1428   Argument syntax:
1429
1430      delta-seconds (see Section 1.2.1)
1431
1432   The "s-maxage" response directive indicates that, in shared caches,
1433   the maximum age specified by this directive overrides the maximum age
1434   specified by either the max-age directive or the Expires header
1435   field.  The s-maxage directive also implies the semantics of the
1436   proxy-revalidate response directive.
1437
1438   This directive uses the token form of the argument syntax; e.g.,
1439   's-maxage=10', not 's-maxage="10"'.  A sender SHOULD NOT generate the
1440   quoted-string form.
1441
14425.2.3.  Cache Control Extensions
1443
1444   The Cache-Control header field can be extended through the use of one
1445   or more cache-extension tokens, each with an optional value.
1446
1447   Informational extensions (those that do not require a change in cache
1448   behavior) can be added without changing the semantics of other
1449   directives.  Behavioral extensions are designed to work by acting as
1450   modifiers to the existing base of cache directives.
1451
1452
1453
1454
1455Fielding, et al.          Expires May 21, 2014                 [Page 26]
1456
1457Internet-Draft              HTTP/1.1 Caching               November 2013
1458
1459
1460   Both the new directive and the standard directive are supplied, such
1461   that applications that do not understand the new directive will
1462   default to the behavior specified by the standard directive, and
1463   those that understand the new directive will recognize it as
1464   modifying the requirements associated with the standard directive.
1465   In this way, extensions to the cache-control directives can be made
1466   without requiring changes to the base protocol.
1467
1468   This extension mechanism depends on an HTTP cache obeying all of the
1469   cache-control directives defined for its native HTTP-version, obeying
1470   certain extensions, and ignoring all directives that it does not
1471   understand.
1472
1473   For example, consider a hypothetical new response directive called
1474   "community" that acts as a modifier to the private directive.  We
1475   define this new directive to mean that, in addition to any private
1476   cache, any cache that is shared only by members of the community
1477   named within its value is allowed to cache the response.  An origin
1478   server wishing to allow the UCI community to use an otherwise private
1479   response in their shared cache(s) could do so by including
1480
1481     Cache-Control: private, community="UCI"
1482
1483   A cache seeing this header field will act correctly even if the cache
1484   does not understand the community cache-extension, since it will also
1485   see and understand the private directive and thus default to the safe
1486   behavior.
1487
1488   A cache MUST ignore unrecognized cache directives; it is assumed that
1489   any cache directive likely to be unrecognized by an HTTP/1.1 cache
1490   will be combined with standard directives (or the response's default
1491   cacheability) such that the cache behavior will remain minimally
1492   correct even if the cache does not understand the extension(s).
1493
14945.3.  Expires
1495
1496   The "Expires" header field gives the date/time after which the
1497   response is considered stale.  See Section 4.2 for further discussion
1498   of the freshness model.
1499
1500   The presence of an Expires field does not imply that the original
1501   resource will change or cease to exist at, before, or after that
1502   time.
1503
1504   The Expires value is an HTTP-date timestamp, as defined in Section
1505   7.1.1.1 of [Part2].
1506
1507     Expires = HTTP-date
1508
1509
1510
1511Fielding, et al.          Expires May 21, 2014                 [Page 27]
1512
1513Internet-Draft              HTTP/1.1 Caching               November 2013
1514
1515
1516   For example
1517
1518     Expires: Thu, 01 Dec 1994 16:00:00 GMT
1519
1520   A cache recipient MUST interpret invalid date formats, especially the
1521   value "0", as representing a time in the past (i.e., "already
1522   expired").
1523
1524   If a response includes a Cache-Control field with the max-age
1525   directive (Section 5.2.2.8), a recipient MUST ignore the Expires
1526   field.  Likewise, if a response includes the s-maxage directive
1527   (Section 5.2.2.9), a shared cache recipient MUST ignore the Expires
1528   field.  In both these cases, the value in Expires is only intended
1529   for recipients that have not yet implemented the Cache-Control field.
1530
1531   An origin server without a clock MUST NOT generate an Expires field
1532   unless its value represents a fixed time in the past (always expired)
1533   or its value has been associated with the resource by a system or
1534   user with a reliable clock.
1535
1536   Historically, HTTP required the Expires field-value to be no more
1537   than a year in the future.  While longer freshness lifetimes are no
1538   longer prohibited, extremely large values have been demonstrated to
1539   cause problems (e.g., clock overflows due to use of 32-bit integers
1540   for time values), and many caches will evict a response far sooner
1541   than that.
1542
15435.4.  Pragma
1544
1545   The "Pragma" header field allows backwards compatibility with
1546   HTTP/1.0 caches, so that clients can specify a "no-cache" request
1547   that they will understand (as Cache-Control was not defined until
1548   HTTP/1.1).  When the Cache-Control header field is also present and
1549   understood in a request, Pragma is ignored.
1550
1551   In HTTP/1.0, Pragma was defined as an extensible field for
1552   implementation-specified directives for recipients.  This
1553   specification deprecates such extensions to improve interoperability.
1554
1555     Pragma           = 1#pragma-directive
1556     pragma-directive = "no-cache" / extension-pragma
1557     extension-pragma = token [ "=" ( token / quoted-string ) ]
1558
1559   When the Cache-Control header field is not present in a request,
1560   caches MUST consider the no-cache request pragma-directive as having
1561   the same effect as if "Cache-Control: no-cache" were present (see
1562   Section 5.2.1).
1563
1564
1565
1566
1567Fielding, et al.          Expires May 21, 2014                 [Page 28]
1568
1569Internet-Draft              HTTP/1.1 Caching               November 2013
1570
1571
1572   When sending a no-cache request, a client ought to include both the
1573   pragma and cache-control directives, unless Cache-Control: no-cache
1574   is purposefully omitted to target other Cache-Control response
1575   directives at HTTP/1.1 caches.  For example:
1576
1577     GET / HTTP/1.1
1578     Host: www.example.com
1579     Cache-Control: max-age=30
1580     Pragma: no-cache
1581
1582
1583   will constrain HTTP/1.1 caches to serve a response no older than 30
1584   seconds, while precluding implementations that do not understand
1585   Cache-Control from serving a cached response.
1586
1587      Note: Because the meaning of "Pragma: no-cache" in responses is
1588      not specified, it does not provide a reliable replacement for
1589      "Cache-Control: no-cache" in them.
1590
15915.5.  Warning
1592
1593   The "Warning" header field is used to carry additional information
1594   about the status or transformation of a message that might not be
1595   reflected in the status code.  This information is typically used to
1596   warn about possible incorrectness introduced by caching operations or
1597   transformations applied to the payload of the message.
1598
1599   Warnings can be used for other purposes, both cache-related and
1600   otherwise.  The use of a warning, rather than an error status code,
1601   distinguishes these responses from true failures.
1602
1603   Warning header fields can in general be applied to any message,
1604   however some warn-codes are specific to caches and can only be
1605   applied to response messages.
1606
1607     Warning       = 1#warning-value
1608
1609     warning-value = warn-code SP warn-agent SP warn-text
1610                                           [ SP warn-date ]
1611
1612     warn-code  = 3DIGIT
1613     warn-agent = ( uri-host [ ":" port ] ) / pseudonym
1614                     ; the name or pseudonym of the server adding
1615                     ; the Warning header field, for use in debugging
1616                     ; a single "-" is recommended when agent unknown
1617     warn-text  = quoted-string
1618     warn-date  = DQUOTE HTTP-date DQUOTE
1619
1620
1621
1622
1623Fielding, et al.          Expires May 21, 2014                 [Page 29]
1624
1625Internet-Draft              HTTP/1.1 Caching               November 2013
1626
1627
1628   Multiple warnings can be generated in a response (either by the
1629   origin server or by a cache), including multiple warnings with the
1630   same warn-code number that only differ in warn-text.
1631
1632   A user agent that receives one or more Warning header fields SHOULD
1633   inform the user of as many of them as possible, in the order that
1634   they appear in the response.  Senders that generate multiple Warning
1635   header fields are encouraged to order them with this user agent
1636   behavior in mind.  A sender that generates new Warning header fields
1637   MUST append them after any existing Warning header fields.
1638
1639   Warnings are assigned three digit warn-codes.  The first digit
1640   indicates whether the Warning is required to be deleted from a stored
1641   response after validation:
1642
1643   o  1xx warn-codes describe the freshness or validation status of the
1644      response, and so MUST be deleted by a cache after validation.
1645      They can only be generated by a cache when validating a cached
1646      entry, and MUST NOT be generated in any other situation.
1647
1648   o  2xx warn-codes describe some aspect of the representation that is
1649      not rectified by a validation (for example, a lossy compression of
1650      the representation) and MUST NOT be deleted by a cache after
1651      validation, unless a full response is sent, in which case they
1652      MUST be.
1653
1654   If a sender generates one or more 1xx warn-codes in a message to be
1655   sent to a recipient known to implement only HTTP/1.0, the sender MUST
1656   include in each corresponding warning-value a warn-date that matches
1657   the Date header field in the message.  For example:
1658
1659     HTTP/1.1 200 OK
1660     Date: Sat, 25 Aug 2012 23:34:45 GMT
1661     Warning: 112 - "network down" "Sat, 25 Aug 2012 23:34:45 GMT"
1662
1663
1664   If a recipient that uses, evaluates, or displays Warning header
1665   fields receives a warn-date that is different from the Date value in
1666   the same message, the recipient MUST exclude the warning-value
1667   containing that warn-date before storing, forwarding, or using the
1668   message.  This allows recipients to exclude warning-values that were
1669   improperly retained after a cache validation.  If all of the warning-
1670   values are excluded, the recipient MUST exclude the Warning header
1671   field as well.
1672
1673   The following warn-codes are defined by this specification, each with
1674   a recommended warn-text in English, and a description of its meaning.
1675   The procedure for defining additional warn codes is described in
1676
1677
1678
1679Fielding, et al.          Expires May 21, 2014                 [Page 30]
1680
1681Internet-Draft              HTTP/1.1 Caching               November 2013
1682
1683
1684   Section 7.2.1.
1685
16865.5.1.  Warning: 110 - "Response is Stale"
1687
1688   A cache SHOULD generate this whenever the sent response is stale.
1689
16905.5.2.  Warning: 111 - "Revalidation Failed"
1691
1692   A cache SHOULD generate this when sending a stale response because an
1693   attempt to validate the response failed, due to an inability to reach
1694   the server.
1695
16965.5.3.  Warning: 112 - "Disconnected Operation"
1697
1698   A cache SHOULD generate this if it is intentionally disconnected from
1699   the rest of the network for a period of time.
1700
17015.5.4.  Warning: 113 - "Heuristic Expiration"
1702
1703   A cache SHOULD generate this if it heuristically chose a freshness
1704   lifetime greater than 24 hours and the response's age is greater than
1705   24 hours.
1706
17075.5.5.  Warning: 199 - "Miscellaneous Warning"
1708
1709   The warning text can include arbitrary information to be presented to
1710   a human user, or logged.  A system receiving this warning MUST NOT
1711   take any automated action, besides presenting the warning to the
1712   user.
1713
17145.5.6.  Warning: 214 - "Transformation Applied"
1715
1716   MUST be added by a proxy if it applies any transformation to the
1717   representation, such as changing the content-coding, media-type, or
1718   modifying the representation data, unless this Warning code already
1719   appears in the response.
1720
17215.5.7.  Warning: 299 - "Miscellaneous Persistent Warning"
1722
1723   The warning text can include arbitrary information to be presented to
1724   a human user, or logged.  A system receiving this warning MUST NOT
1725   take any automated action.
1726
17276.  History Lists
1728
1729   User agents often have history mechanisms, such as "Back" buttons and
1730   history lists, that can be used to redisplay a representation
1731   retrieved earlier in a session.
1732
1733
1734
1735Fielding, et al.          Expires May 21, 2014                 [Page 31]
1736
1737Internet-Draft              HTTP/1.1 Caching               November 2013
1738
1739
1740   The freshness model (Section 4.2) does not necessarily apply to
1741   history mechanisms.  I.e., a history mechanism can display a previous
1742   representation even if it has expired.
1743
1744   This does not prohibit the history mechanism from telling the user
1745   that a view might be stale, or from honoring cache directives (e.g.,
1746   Cache-Control: no-store).
1747
17487.  IANA Considerations
1749
17507.1.  Cache Directive Registry
1751
1752   The HTTP Cache Directive Registry defines the name space for the
1753   cache directives.  It will be created and maintained at (the
1754   suggested URI)
1755   <http://www.iana.org/assignments/http-cache-directives>.
1756
17577.1.1.  Procedure
1758
1759   A registration MUST include the following fields:
1760
1761   o  Cache Directive Name
1762
1763   o  Pointer to specification text
1764
1765   Values to be added to this name space require IETF Review (see
1766   [RFC5226], Section 4.1).
1767
17687.1.2.  Considerations for New Cache Control Directives
1769
1770   New extension directives ought to consider defining:
1771
1772   o  What it means for a directive to be specified multiple times,
1773
1774   o  When the directive does not take an argument, what it means when
1775      an argument is present,
1776
1777   o  When the directive requires an argument, what it means when it is
1778      missing,
1779
1780   o  Whether the directive is specific to requests, responses, or able
1781      to be used in either.
1782
1783   See also Section 5.2.3.
1784
1785
1786
1787
1788
1789
1790
1791Fielding, et al.          Expires May 21, 2014                 [Page 32]
1792
1793Internet-Draft              HTTP/1.1 Caching               November 2013
1794
1795
17967.1.3.  Registrations
1797
1798   The HTTP Cache Directive Registry shall be populated with the
1799   registrations below:
1800
1801   +------------------------+----------------------------------+
1802   | Cache Directive        | Reference                        |
1803   +------------------------+----------------------------------+
1804   | max-age                | Section 5.2.1.1, Section 5.2.2.8 |
1805   | max-stale              | Section 5.2.1.2                  |
1806   | min-fresh              | Section 5.2.1.3                  |
1807   | must-revalidate        | Section 5.2.2.1                  |
1808   | no-cache               | Section 5.2.1.4, Section 5.2.2.2 |
1809   | no-store               | Section 5.2.1.5, Section 5.2.2.3 |
1810   | no-transform           | Section 5.2.1.6, Section 5.2.2.4 |
1811   | only-if-cached         | Section 5.2.1.7                  |
1812   | private                | Section 5.2.2.6                  |
1813   | proxy-revalidate       | Section 5.2.2.7                  |
1814   | public                 | Section 5.2.2.5                  |
1815   | s-maxage               | Section 5.2.2.9                  |
1816   | stale-if-error         | [RFC5861], Section 4             |
1817   | stale-while-revalidate | [RFC5861], Section 3             |
1818   +------------------------+----------------------------------+
1819
18207.2.  Warn Code Registry
1821
1822   The HTTP Warn Code Registry defines the name space for warn codes.
1823   It will be created and maintained at (the suggested URI)
1824   <http://www.iana.org/assignments/http-warn-codes>.
1825
18267.2.1.  Procedure
1827
1828   A registration MUST include the following fields:
1829
1830   o  Warn Code (3 digits)
1831
1832   o  Short Description
1833
1834   o  Pointer to specification text
1835
1836   Values to be added to this name space require IETF Review (see
1837   [RFC5226], Section 4.1).
1838
18397.2.2.  Registrations
1840
1841   The HTTP Warn Code Registry shall be populated with the registrations
1842   below:
1843
1844
1845
1846
1847Fielding, et al.          Expires May 21, 2014                 [Page 33]
1848
1849Internet-Draft              HTTP/1.1 Caching               November 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 May 21, 2014                 [Page 34]
1904
1905Internet-Draft              HTTP/1.1 Caching               November 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-25 (work in progress),
1943              November 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-25 (work in progress),
1948              November 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-25 (work in progress),
1953              November 2013.
1954
1955   [Part5]    Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed.,
1956
1957
1958
1959Fielding, et al.          Expires May 21, 2014                 [Page 35]
1960
1961Internet-Draft              HTTP/1.1 Caching               November 2013
1962
1963
1964              "Hypertext Transfer Protocol (HTTP/1.1): Range Requests",
1965              draft-ietf-httpbis-p5-range-25 (work in progress),
1966              November 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-25 (work in progress),
1971              November 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   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
1986              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
1987              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
1988
1989   [RFC5226]  Narten, T. and H. Alvestrand, "Guidelines for Writing an
1990              IANA Considerations Section in RFCs", BCP 26, RFC 5226,
1991              May 2008.
1992
1993   [RFC5861]  Nottingham, M., "HTTP Cache-Control Extensions for Stale
1994              Content", RFC 5861, April 2010.
1995
1996   [RFC5905]  Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
1997              "Network Time Protocol Version 4: Protocol and Algorithms
1998              Specification", RFC 5905, June 2010.
1999
2000   [RFC6265]  Barth, A., "HTTP State Management Mechanism", RFC 6265,
2001              April 2011.
2002
2003Appendix A.  Changes from RFC 2616
2004
2005   The specification has been substantially rewritten for clarity.
2006
2007   The conditions under which an authenticated response can be cached
2008   have been clarified.  (Section 3.2)
2009
2010   New status codes can now define that caches are allowed to use
2011   heuristic freshness with them.  Caches are now allowed to calculate
2012
2013
2014
2015Fielding, et al.          Expires May 21, 2014                 [Page 36]
2016
2017Internet-Draft              HTTP/1.1 Caching               November 2013
2018
2019
2020   heuristic freshness for URIs with query components.  (Section 4.2.2)
2021
2022   The algorithm for calculating age is now less conservative.  Caches
2023   are now required to handle dates with timezones as if they're
2024   invalid, because it's not possible to accurately guess.
2025   (Section 4.2.3)
2026
2027   The Content-Location response header field is no longer used to
2028   determine the appropriate response to use when validating.
2029   (Section 4.3)
2030
2031   The algorithm for selecting a cached negotiated response to use has
2032   been clarified in several ways.  In particular, it now explicitly
2033   allows header-specific canonicalization when processing selecting
2034   header fields.  (Section 4.1)
2035
2036   Requirements regarding denial of service attack avoidance when
2037   performing invalidation have been clarified.  (Section 4.4)
2038
2039   Cache invalidation only occurs when a successful response is
2040   received.  (Section 4.4)
2041
2042   Cache directives are explicitly defined to be case-insensitive.
2043   Handling of multiple instances of cache directives when only one is
2044   expected is now defined.  (Section 5.2)
2045
2046   The "no-store" cache request directive doesn't apply to responses;
2047   i.e., a cache can satisfy a request with no-store on it, and does not
2048   invalidate it.  (Section 5.2.1.5)
2049
2050   The qualified forms of the private and no-cache cache directives are
2051   noted to not be widely implemented; e.g., "private=foo" is
2052   interpreted by many caches as simply "private".  Additionally, the
2053   meaning of the qualified form of no-cache has been clarified.
2054   (Section 5.2.2)
2055
2056   The "no-cache" response cache directive's meaning has been clarified.
2057   (Section 5.2.2.2)
2058
2059   The one-year limit on Expires header field values has been removed;
2060   instead, the reasoning for using a sensible value is given.
2061   (Section 5.3)
2062
2063   The Pragma header field is now only defined for backwards
2064   compatibility; future pragmas are deprecated.  (Section 5.4)
2065
2066   Some requirements regarding production and processing of the Warning
2067   header fields have been relaxed, as it is not widely implemented.
2068
2069
2070
2071Fielding, et al.          Expires May 21, 2014                 [Page 37]
2072
2073Internet-Draft              HTTP/1.1 Caching               November 2013
2074
2075
2076   Furthermore, the Warning header field no longer uses RFC 2047
2077   encoding, nor allows multiple languages, as these aspects were not
2078   implemented.  (Section 5.5)
2079
2080   This specification introduces the Cache Directive and Warn Code
2081   Registries, and defines considerations for new cache directives.
2082   (Section 7.1 and Section 7.2)
2083
2084Appendix B.  Imported ABNF
2085
2086   The following core rules are included by reference, as defined in
2087   Appendix B.1 of [RFC5234]: ALPHA (letters), CR (carriage return),
2088   CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double
2089   quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any
2090   8-bit sequence of data), SP (space), and VCHAR (any visible US-ASCII
2091   character).
2092
2093   The rules below are defined in [Part1]:
2094
2095     OWS           = <OWS, defined in [Part1], Section 3.2.3>
2096     field-name    = <field-name, defined in [Part1], Section 3.2>
2097     quoted-string = <quoted-string, defined in [Part1], Section 3.2.6>
2098     token         = <token, defined in [Part1], Section 3.2.6>
2099
2100     port          = <port, defined in [Part1], Section 2.7>
2101     pseudonym     = <pseudonym, defined in [Part1], Section 5.7.1>
2102     uri-host      = <uri-host, defined in [Part1], Section 2.7>
2103
2104   The rules below are defined in other parts:
2105
2106     HTTP-date     = <HTTP-date, defined in [Part2], Section 7.1.1.1>
2107
2108Appendix C.  Collected ABNF
2109
2110   In the collected ABNF below, list rules are expanded as per Section
2111   1.2 of [Part1].
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127Fielding, et al.          Expires May 21, 2014                 [Page 38]
2128
2129Internet-Draft              HTTP/1.1 Caching               November 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 IETF Last Call draft are summarized in <http://
2177   trac.tools.ietf.org/html/draft-ietf-httpbis-p6-cache-24#appendix-D>.
2178
2179
2180
2181
2182
2183Fielding, et al.          Expires May 21, 2014                 [Page 39]
2184
2185Internet-Draft              HTTP/1.1 Caching               November 2013
2186
2187
2188D.1.  Since draft-ietf-httpbis-p6-cache-24
2189
2190   Closed issues:
2191
2192   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/499>: "RFC 1305 ref
2193      needs to be updated to 5905"
2194
2195   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/500>: "dangling
2196      reference to cacheable status codes"
2197
2198   o  <http://tools.ietf.org/wg/httpbis/trac/ticket/512>: "APPSDIR
2199      review of draft-ietf-httpbis-p6-cache-24"
2200
2201Index
2202
2203   1
2204      110 (warn-code)  31
2205      111 (warn-code)  31
2206      112 (warn-code)  31
2207      113 (warn-code)  31
2208      199 (warn-code)  31
2209
2210   2
2211      214 (warn-code)  31
2212      299 (warn-code)  31
2213
2214   A
2215      age  10
2216      Age header field  20
2217
2218   C
2219      cache  4
2220      cache entry  5
2221      cache key  5
2222      Cache-Control header field  21
2223
2224   D
2225      Disconnected Operation (warn-text)  31
2226
2227   E
2228      Expires header field  27
2229      explicit expiration time  10
2230
2231   F
2232      fresh  10
2233      freshness lifetime  10
2234
2235   G
2236
2237
2238
2239Fielding, et al.          Expires May 21, 2014                 [Page 40]
2240
2241Internet-Draft              HTTP/1.1 Caching               November 2013
2242
2243
2244      Grammar
2245         Age  20
2246         Cache-Control  21
2247         cache-directive  21
2248         delta-seconds  5
2249         Expires  27
2250         extension-pragma  28
2251         Pragma  28
2252         pragma-directive  28
2253         warn-agent  29
2254         warn-code  29
2255         warn-date  29
2256         warn-text  29
2257         Warning  29
2258         warning-value  29
2259
2260   H
2261      Heuristic Expiration (warn-text)  31
2262      heuristic expiration time  10
2263
2264   M
2265      max-age (cache directive)  21, 26
2266      max-stale (cache directive)  22
2267      min-fresh (cache directive)  22
2268      Miscellaneous Persistent Warning (warn-text)  31
2269      Miscellaneous Warning (warn-text)  31
2270      must-revalidate (cache directive)  23
2271
2272   N
2273      no-cache (cache directive)  22, 24
2274      no-store (cache directive)  22, 24
2275      no-transform (cache directive)  23, 25
2276
2277   O
2278      only-if-cached (cache directive)  23
2279
2280   P
2281      Pragma header field  28
2282      private (cache directive)  25
2283      private cache  4
2284      proxy-revalidate (cache directive)  26
2285      public (cache directive)  25
2286
2287   R
2288      Response is Stale (warn-text)  31
2289      Revalidation Failed (warn-text)  31
2290
2291   S
2292
2293
2294
2295Fielding, et al.          Expires May 21, 2014                 [Page 41]
2296
2297Internet-Draft              HTTP/1.1 Caching               November 2013
2298
2299
2300      s-maxage (cache directive)  26
2301      shared cache  4
2302      stale  10
2303      strong validator  18
2304
2305   T
2306      Transformation Applied (warn-text)  31
2307
2308   V
2309      validator  15
2310
2311   W
2312      Warning header field  29
2313
2314Authors' Addresses
2315
2316   Roy T. Fielding (editor)
2317   Adobe Systems Incorporated
2318   345 Park Ave
2319   San Jose, CA  95110
2320   USA
2321
2322   EMail: fielding@gbiv.com
2323   URI:   http://roy.gbiv.com/
2324
2325
2326   Mark Nottingham (editor)
2327   Akamai
2328
2329   EMail: mnot@mnot.net
2330   URI:   http://www.mnot.net/
2331
2332
2333   Julian F. Reschke (editor)
2334   greenbytes GmbH
2335   Hafenweg 16
2336   Muenster, NW  48155
2337   Germany
2338
2339   EMail: julian.reschke@greenbytes.de
2340   URI:   http://greenbytes.de/tech/webdav/
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351Fielding, et al.          Expires May 21, 2014                 [Page 42]
2352
Note: See TracBrowser for help on using the repository browser.