source: draft-ietf-httpbis/23/draft-ietf-httpbis-p6-cache-23.txt @ 2323

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

prepare release of -23

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