| draft-ietf-httpbis-p6-cache-05.txt |  | draft-ietf-httpbis-p6-cache-06.txt |
--- | --- | --- | --- | ---
| Network Working Group R. Fielding, Ed. |  | HTTPbis Working Group R. Fielding, Ed. |
| Internet-Draft Day Software |  | Internet-Draft Day Software |
| Obsoletes: 2616 (if approved) J. Gettys |  | Obsoletes: 2616 (if approved) J. Gettys |
| Intended status: Standards Track One Laptop per Child |  | Intended status: Standards Track One Laptop per Child |
| Expires: May 20, 2009 J. Mogul |  | Expires: September 10, 2009 J. Mogul |
| HP |  | HP |
| H. Frystyk |  | H. Frystyk |
| Microsoft |  | Microsoft |
| L. Masinter |  | L. Masinter |
| Adobe Systems |  | Adobe Systems |
| P. Leach |  | P. Leach |
| Microsoft |  | Microsoft |
| T. Berners-Lee |  | T. Berners-Lee |
| W3C/MIT |  | W3C/MIT |
| Y. Lafon, Ed. |  | Y. Lafon, Ed. |
| W3C |  | W3C |
| J. Reschke, Ed. |  | J. Reschke, Ed. |
| greenbytes |  | greenbytes |
| November 16, 2008 |  | March 9, 2009 |
| HTTP/1.1, part 6: Caching |  | HTTP/1.1, part 6: Caching |
| draft-ietf-httpbis-p6-cache-05 |  | draft-ietf-httpbis-p6-cache-06 |
| Status of this Memo |  | Status of this Memo |
| By submitting this Internet-Draft, each author represents that any |  | This Internet-Draft is submitted to IETF in full conformance with the |
| applicable patent or other IPR claims of which he or she is aware |  | provisions of BCP 78 and BCP 79. This document may contain material |
| have been or will be disclosed, and any of which he or she becomes |  | from IETF Documents or IETF Contributions published or made publicly |
| aware will be disclosed, in accordance with Section 6 of BCP 79. |  | available before November 10, 2008. The person(s) controlling the |
|  |  | copyright in some of this material may not have granted the IETF |
|  |  | Trust the right to allow modifications of such material outside the |
|  |  | IETF Standards Process. Without obtaining an adequate license from |
|  |  | the person(s) controlling the copyright in such materials, this |
|  |  | document may not be modified outside the IETF Standards Process, and |
|  |  | derivative works of it may not be created outside the IETF Standards |
|  |  | Process, except to format it for publication as an RFC or to |
|  |  | translate it into languages other than English. |
| Internet-Drafts are working documents of the Internet Engineering |  | Internet-Drafts are working documents of the Internet Engineering |
| Task Force (IETF), its areas, and its working groups. Note that |  | Task Force (IETF), its areas, and its working groups. Note that |
| other groups may also distribute working documents as Internet- |  | other groups may also distribute working documents as Internet- |
| Drafts. |  | Drafts. |
| Internet-Drafts are draft documents valid for a maximum of six months |  | Internet-Drafts are draft documents valid for a maximum of six months |
| and may be updated, replaced, or obsoleted by other documents at any |  | and may be updated, replaced, or obsoleted by other documents at any |
| time. It is inappropriate to use Internet-Drafts as reference |  | time. It is inappropriate to use Internet-Drafts as reference |
| material or to cite them other than as "work in progress." |  | material or to cite them other than as "work in progress." |
| skipping to change at page 1, line 42 |  | skipping to change at page 2, line 4 |
| Internet-Drafts are working documents of the Internet Engineering |  | Internet-Drafts are working documents of the Internet Engineering |
| Task Force (IETF), its areas, and its working groups. Note that |  | Task Force (IETF), its areas, and its working groups. Note that |
| other groups may also distribute working documents as Internet- |  | other groups may also distribute working documents as Internet- |
| Drafts. |  | Drafts. |
| Internet-Drafts are draft documents valid for a maximum of six months |  | Internet-Drafts are draft documents valid for a maximum of six months |
| and may be updated, replaced, or obsoleted by other documents at any |  | and may be updated, replaced, or obsoleted by other documents at any |
| time. It is inappropriate to use Internet-Drafts as reference |  | time. It is inappropriate to use Internet-Drafts as reference |
| material or to cite them other than as "work in progress." |  | material or to cite them other than as "work in progress." |
| The list of current Internet-Drafts can be accessed at |  | The list of current Internet-Drafts can be accessed at |
| http://www.ietf.org/ietf/1id-abstracts.txt. |  | http://www.ietf.org/ietf/1id-abstracts.txt. |
| The list of Internet-Draft Shadow Directories can be accessed at |  | The list of Internet-Draft Shadow Directories can be accessed at |
| http://www.ietf.org/shadow.html. |  | http://www.ietf.org/shadow.html. |
| This Internet-Draft will expire on May 20, 2009. |  | This Internet-Draft will expire on September 10, 2009. |
|  |  | Copyright Notice |
|  |  | Copyright (c) 2009 IETF Trust and the persons identified as the |
|  |  | document authors. All rights reserved. |
|  |  | This document is subject to BCP 78 and the IETF Trust's Legal |
|  |  | Provisions Relating to IETF Documents in effect on the date of |
|  |  | publication of this document (http://trustee.ietf.org/license-info). |
|  |  | Please review these documents carefully, as they describe your rights |
|  |  | and restrictions with respect to this document. |
| Abstract |  | Abstract |
| The Hypertext Transfer Protocol (HTTP) is an application-level |  | The Hypertext Transfer Protocol (HTTP) is an application-level |
| protocol for distributed, collaborative, hypermedia information |  | protocol for distributed, collaborative, hypermedia information |
| systems. HTTP has been in use by the World Wide Web global |  | systems. This document is Part 6 of the seven-part specification |
| information initiative since 1990. This document is Part 6 of the |  | that defines the protocol referred to as "HTTP/1.1" and, taken |
| seven-part specification that defines the protocol referred to as |  | together, obsoletes RFC 2616. Part 6 defines requirements on HTTP |
| "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 defines |  | caches and the associated header fields that control cache behavior |
| requirements on HTTP caches and the associated header fields that |  | or indicate cacheable response messages. |
| control cache behavior or indicate cacheable response messages. |  |  |
| Editorial Note (To be removed by RFC Editor) |  | Editorial Note (To be removed by RFC Editor) |
| Discussion of this draft should take place on the HTTPBIS working |  | Discussion of this draft should take place on the HTTPBIS working |
| group mailing list (ietf-http-wg@w3.org). The current issues list is |  | group mailing list (ietf-http-wg@w3.org). The current issues list is |
| at <http://tools.ietf.org/wg/httpbis/trac/report/11> and related |  | at <http://tools.ietf.org/wg/httpbis/trac/report/11> and related |
| documents (including fancy diffs) can be found at |  | documents (including fancy diffs) can be found at |
| <http://tools.ietf.org/wg/httpbis/>. |  | <http://tools.ietf.org/wg/httpbis/>. |
| The changes in this draft are summarized in Appendix B.6. |  | The changes in this draft are summarized in Appendix C.7. |
| Table of Contents |  | Table of Contents |
| 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 |  | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 |
| 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 |  | 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 |
| 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 |  | 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 |
| 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 |  | 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 6 |
| 2. Notational Conventions and Generic Grammar . . . . . . . . . . 8 |  | 1.4. Syntax Notation . . . . . . . . . . . . . . . . . . . . . 7 |
| 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 |  | 1.4.1. Core Rules . . . . . . . . . . . . . . . . . . . . . . 7 |
| 3.1. Cache Correctness . . . . . . . . . . . . . . . . . . . . 8 |  | 1.4.2. ABNF Rules defined in other Parts of the |
| 3.2. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . 9 |  | Specification . . . . . . . . . . . . . . . . . . . . 7 |
| 3.3. Cache-control Mechanisms . . . . . . . . . . . . . . . . . 10 |  | 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 |
| 3.4. Explicit User Agent Warnings . . . . . . . . . . . . . . . 10 |  | 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 |
| 3.5. Exceptions to the Rules and Warnings . . . . . . . . . . . 11 |  | 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 |
| 3.6. Client-controlled Behavior . . . . . . . . . . . . . . . . 11 |  | 2.2. Constructing Responses from Caches . . . . . . . . . . . . 8 |
| 4. Expiration Model . . . . . . . . . . . . . . . . . . . . . . . 12 |  | 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 9 |
| 4.1. Server-Specified Expiration . . . . . . . . . . . . . . . 12 |  | 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 10 |
| 4.2. Heuristic Expiration . . . . . . . . . . . . . . . . . . . 13 |  | 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 11 |
| 4.3. Age Calculations . . . . . . . . . . . . . . . . . . . . . 13 |  | 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 |
| 4.4. Expiration Calculations . . . . . . . . . . . . . . . . . 15 |  | 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 13 |
| 4.5. Disambiguating Expiration Values . . . . . . . . . . . . . 16 |  | 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 |
| 4.6. Disambiguating Multiple Responses . . . . . . . . . . . . 17 |  | 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 |
| 5. Validation Model . . . . . . . . . . . . . . . . . . . . . . . 17 |  | 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 |
| 6. Response Cacheability . . . . . . . . . . . . . . . . . . . . 18 |  | 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 16 |
| 7. Constructing Responses From Caches . . . . . . . . . . . . . . 19 |  | 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 |
| 7.1. End-to-end and Hop-by-hop Headers . . . . . . . . . . . . 19 |  | 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 17 |
| 7.2. Non-modifiable Headers . . . . . . . . . . . . . . . . . . 20 |  | 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 |
| 7.3. Combining Headers . . . . . . . . . . . . . . . . . . . . 21 |  | 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 |
| 8. Caching Negotiated Responses . . . . . . . . . . . . . . . . . 22 |  | 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 |
| 9. Shared and Non-Shared Caches . . . . . . . . . . . . . . . . . 23 |  | 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 |
| 10. Errors or Incomplete Response Cache Behavior . . . . . . . . . 24 |  | 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 23 |
| 11. Side Effects of GET and HEAD . . . . . . . . . . . . . . . . . 24 |  | 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 |
| 12. Invalidation After Updates or Deletions . . . . . . . . . . . 24 |  | 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 |
| 13. Write-Through Mandatory . . . . . . . . . . . . . . . . . . . 25 |  | 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 |
| 14. Cache Replacement . . . . . . . . . . . . . . . . . . . . . . 26 |  | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 |
| 15. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 26 |  | 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 |
| 16. Header Field Definitions . . . . . . . . . . . . . . . . . . . 27 |  | 6. Security Considerations . . . . . . . . . . . . . . . . . . . 29 |
| 16.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 |  | 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 |
| 16.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 27 |  | 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 |
| 16.2.1. What is Cacheable . . . . . . . . . . . . . . . . . . 29 |  | 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 |
| 16.2.2. What May be Stored by Caches . . . . . . . . . . . . 30 |  | 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 |
| 16.2.3. Modifications of the Basic Expiration Mechanism . . . 31 |  | Appendix A. Compatibility with Previous Versions . . . . . . . . 31 |
| 16.2.4. Cache Revalidation and Reload Controls . . . . . . . 33 |  | A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 31 |
| 16.2.5. No-Transform Directive . . . . . . . . . . . . . . . 35 |  | A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 31 |
| 16.2.6. Cache Control Extensions . . . . . . . . . . . . . . 36 |  | Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 |
| 16.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 37 |  | Appendix C. Change Log (to be removed by RFC Editor before |
| 16.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 38 |  | publication) . . . . . . . . . . . . . . . . . . . . 33 |
| 16.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 |  | C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 33 |
| 16.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 39 |  | C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 33 |
| 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 |  | C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 34 |
| 17.1. Message Header Registration . . . . . . . . . . . . . . . 42 |  | C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 34 |
| 18. Security Considerations . . . . . . . . . . . . . . . . . . . 42 |  | C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 |
| 19. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 |  | C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 |
| 20. References . . . . . . . . . . . . . . . . . . . . . . . . . . 43 |  | C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 35 |
| 20.1. Normative References . . . . . . . . . . . . . . . . . . . 43 |  | Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 |
| 20.2. Informative References . . . . . . . . . . . . . . . . . . 44 |  | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 |
| Appendix A. Compatibility with Previous Versions . . . . . . . . 44 |  |  |
| A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 44 |  |  |
| A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 45 |  |  |
| Appendix B. Change Log (to be removed by RFC Editor before |  |  |
| publication) . . . . . . . . . . . . . . . . . . . . 45 |  |  |
| B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 45 |  |  |
| B.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 45 |  |  |
| B.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 46 |  |  |
| B.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 46 |  |  |
| B.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 46 |  |  |
| B.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 47 |  |  |
| Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 |  |  |
| Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49 |  |  |
| Intellectual Property and Copyright Statements . . . . . . . . . . 52 |  |  |
| 1. Introduction |  | 1. Introduction |
| HTTP is typically used for distributed information systems, where |  | HTTP is typically used for distributed information systems, where |
| performance can be improved by the use of response caches, and |  | performance can be improved by the use of response caches. This |
| includes a number of elements intended to make caching work as well |  |  |
| as possible. Because these elements interact with each other, it is |  |  |
| useful to describe the caching design of HTTP separately. This |  |  |
| document defines aspects of HTTP/1.1 related to caching and reusing |  | document defines aspects of HTTP/1.1 related to caching and reusing |
| response messages. |  | response messages. |
| 1.1. Purpose |  | 1.1. Purpose |
| An HTTP cache is a local store of response messages and the subsystem |  | An HTTP cache is a local store of response messages and the subsystem |
| that controls its message storage, retrieval, and deletion. A cache |  | that controls its message storage, retrieval, and deletion. A cache |
| stores cacheable responses in order to reduce the response time and |  | stores cacheable responses in order to reduce the response time and |
| network bandwidth consumption on future, equivalent requests. Any |  | network bandwidth consumption on future, equivalent requests. Any |
| client or server may include a cache, though a cache cannot be used |  | client or server may include a cache, though a cache cannot be used |
| by a server that is acting as a tunnel. |  | by a server that is acting as a tunnel. |
| Caching would be useless if it did not significantly improve |  | Caching would be useless if it did not significantly improve |
| performance. The goal of caching in HTTP/1.1 is to reuse a prior |  | performance. The goal of caching in HTTP/1.1 is to reuse a prior |
| response message to satisfy a current request. In some cases, the |  | response message to satisfy a current request. In some cases, a |
| existing response can be reused without the need for a network |  | stored response can be reused without the need for a network request, |
| request, reducing latency and network round-trips; we use an |  | reducing latency and network round-trips; a "freshness" mechanism is |
| "expiration" mechanism for this purpose (see Section 4). Even when a |  | used for this purpose (see Section 2.3). Even when a new request is |
| new request is required, it is often possible to reuse all or parts |  | required, it is often possible to reuse all or parts of the payload |
| of the payload of a prior response to satisfy the request, thereby |  | of a prior response to satisfy the request, thereby reducing network |
| reducing network bandwidth usage; we use a "validation" mechanism for |  | bandwidth usage; a "validation" mechanism is used for this purpose |
| this purpose (see Section 5). |  | (see Section 2.4). |
| A cache behaves in a "semantically transparent" manner, with respect |  |  |
| to a particular response, when its use affects neither the requesting |  |  |
| client nor the origin server, except to improve performance. When a |  |  |
| cache is semantically transparent, the client receives exactly the |  |  |
| same response status and payload that it would have received had its |  |  |
| request been handled directly by the origin server. |  |  |
| In an ideal world, all interactions with an HTTP cache would be |  |  |
| semantically transparent. However, for some resources, semantic |  |  |
| transparency is not always necessary and can be effectively traded |  |  |
| for the sake of bandwidth scaling, disconnected operation, and high |  |  |
| availability. HTTP/1.1 allows origin servers, caches, and clients to |  |  |
| explicitly reduce transparency when necessary. However, because non- |  |  |
| transparent operation may confuse non-expert users and might be |  |  |
| incompatible with certain server applications (such as those for |  |  |
| ordering merchandise), the protocol requires that transparency be |  |  |
| relaxed |  |  |
| o only by an explicit protocol-level request when relaxed by client |  |  |
| or origin server |  |  |
| o only with an explicit warning to the end user when relaxed by |  |  |
| cache or client |  |  |
| Therefore, HTTP/1.1 provides these important elements: |  |  |
| 1. Protocol features that provide full semantic transparency when |  |  |
| this is required by all parties. |  |  |
| 2. Protocol features that allow an origin server or user agent to |  |  |
| explicitly request and control non-transparent operation. |  |  |
| 3. Protocol features that allow a cache to attach warnings to |  |  |
| responses that do not preserve the requested approximation of |  |  |
| semantic transparency. |  |  |
| A basic principle is that it must be possible for the clients to |  |  |
| detect any potential relaxation of semantic transparency. |  |  |
| Note: The server, cache, or client implementor might be faced with |  |  |
| design decisions not explicitly discussed in this specification. |  |  |
| If a decision might affect semantic transparency, the implementor |  |  |
| ought to err on the side of maintaining transparency unless a |  |  |
| careful and complete analysis shows significant benefits in |  |  |
| breaking transparency. |  |  |
| 1.2. Terminology |  | 1.2. Terminology |
| This specification uses a number of terms to refer to the roles |  | This specification uses a number of terms to refer to the roles |
| played by participants in, and objects of, HTTP caching. |  | played by participants in, and objects of, HTTP caching. |
| cacheable |  | cacheable |
| A response is cacheable if a cache is allowed to store a copy of |  | A response is cacheable if a cache is allowed to store a copy of |
| the response message for use in answering subsequent requests. |  | the response message for use in answering subsequent requests. |
| Even when a response is cacheable, there may be additional |  | Even when a response is cacheable, there may be additional |
| constraints on whether a cache can use the cached copy for a |  | constraints on whether a cache can use the cached copy to satisfy |
| particular request. |  | a particular request. |
| first-hand |  |  |
| A response is first-hand if it comes directly and without |  |  |
| unnecessary delay from the origin server, perhaps via one or more |  |  |
| proxies. A response is also first-hand if its validity has just |  |  |
| been checked directly with the origin server. |  |  |
| explicit expiration time |  | explicit expiration time |
| The time at which the origin server intends that an entity should |  | The time at which the origin server intends that an entity should |
| no longer be returned by a cache without further validation. |  | no longer be returned by a cache without further validation. |
| heuristic expiration time |  | heuristic expiration time |
| An expiration time assigned by a cache when no explicit expiration |  | An expiration time assigned by a cache when no explicit expiration |
| time is available. |  | time is available. |
| age |  | age |
| The age of a response is the time since it was sent by, or |  | The age of a response is the time since it was sent by, or |
| successfully validated with, the origin server. |  | successfully validated with, the origin server. |
|  |  | first-hand |
|  |  | A response is first-hand if the freshness model is not in use; |
|  |  | i.e., its age is 0. |
| freshness lifetime |  | freshness lifetime |
| The length of time between the generation of a response and its |  | The length of time between the generation of a response and its |
| expiration time. |  | expiration time. |
| fresh |  | fresh |
| A response is fresh if its age has not yet exceeded its freshness |  | A response is fresh if its age has not yet exceeded its freshness |
| lifetime. |  | lifetime. |
| stale |  | stale |
| A response is stale if its age has passed its freshness lifetime. |  | A response is stale if its age has passed its freshness lifetime |
|  |  | (either explicit or heuristic). |
| validator |  | validator |
| A protocol element (e.g., an entity tag or a Last-Modified time) |  | A protocol element (e.g., an entity tag or a Last-Modified time) |
| that is used to find out whether a cache entry is an equivalent |  | that is used to find out whether a stored response is an |
| copy of an entity. |  | equivalent copy of an entity. |
|  |  | shared cache |
|  |  | A cache that is accessible to more than one user. A non-shared |
|  |  | cache is dedicated to a single user. |
| 1.3. Requirements |  | 1.3. Requirements |
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |  | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", |
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |  | "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this |
| document are to be interpreted as described in [RFC2119]. |  | document are to be interpreted as described in [RFC2119]. |
| An implementation is not compliant if it fails to satisfy one or more |  | An implementation is not compliant if it fails to satisfy one or more |
| of the MUST or REQUIRED level requirements for the protocols it |  | of the MUST or REQUIRED level requirements for the protocols it |
| implements. An implementation that satisfies all the MUST or |  | implements. An implementation that satisfies all the MUST or |
| REQUIRED level and all the SHOULD level requirements for its |  | REQUIRED level and all the SHOULD level requirements for its |
| protocols is said to be "unconditionally compliant"; one that |  | protocols is said to be "unconditionally compliant"; one that |
| satisfies all the MUST level requirements but not all the SHOULD |  | satisfies all the MUST level requirements but not all the SHOULD |
| level requirements for its protocols is said to be "conditionally |  | level requirements for its protocols is said to be "conditionally |
| compliant." |  | compliant." |
| 2. Notational Conventions and Generic Grammar |  | 1.4. Syntax Notation |
| This specification uses the ABNF syntax defined in Section 2.1 of |  | This specification uses the ABNF syntax defined in Section 1.2 of |
| [Part1] and the core rules defined in Section 2.2 of [Part1]: |  | [Part1] (which extends the syntax defined in [RFC5234] with a list |
|  |  | rule). Appendix B shows the collected ABNF, with the list rule |
|  |  | expanded. |
| DIGIT = <DIGIT, defined in [Part1], Section 2.2> |  | The following core rules are included by reference, as defined in |
| DQUOTE = <DQUOTE, defined in [Part1], Section 2.2> |  | [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF |
| SP = <SP, defined in [Part1], Section 2.2> |  | (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double quote), |
|  |  | HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit |
|  |  | sequence of data), SP (space), VCHAR (any visible USASCII character), |
|  |  | and WSP (whitespace). |
| quoted-string = <quoted-string, defined in [Part1], Section 2.2> |  | 1.4.1. Core Rules |
| token = <token, defined in [Part1], Section 2.2> |  |  |
| OWS = <OWS, defined in [Part1], Section 2.2> |  | The core rules below are defined in Section 1.2.2 of [Part1]: |
|  |  | quoted-string = <quoted-string, defined in [Part1], Section 1.2.2> |
|  |  | token = <token, defined in [Part1], Section 1.2.2> |
|  |  | OWS = <OWS, defined in [Part1], Section 1.2.2> |
|  |  | 1.4.2. ABNF Rules defined in other Parts of the Specification |
| The ABNF rules below are defined in other parts: |  | The ABNF rules below are defined in other parts: |
| field-name = <field-name, defined in [Part1], Section 4.2> |  | field-name = <field-name, defined in [Part1], Section 4.2> |
| HTTP-date = <HTTP-date, defined in [Part1], Section 3.3.1> |  | HTTP-date = <HTTP-date, defined in [Part1], Section 3.2.1> |
| port = <port, defined in [Part1], Section 3.2> |  | port = <port, defined in [Part1], Section 2.1> |
| pseudonym = <pseudonym, defined in [Part1], Section 8.9> |  | pseudonym = <pseudonym, defined in [Part1], Section 8.9> |
| uri-host = <uri-host, defined in [Part1], Section 3.2> |  | uri-host = <uri-host, defined in [Part1], Section 2.1> |
| 3. Overview |  | 2. Cache Operation |
| 3.1. Cache Correctness |  | 2.1. Response Cacheability |
| A correct cache MUST respond to a request with the most up-to-date |  | A cache MUST NOT store a response to any request, unless: |
| response held by the cache that is appropriate to the request (see |  |  |
| Sections 4.5, 4.6, and 14) which meets one of the following |  |  |
| conditions: |  |  |
| 1. It has been checked for equivalence with what the origin server |  | o The request method is defined as being cacheable, and |
| would have returned by revalidating the response with the origin |  |  |
| server (Section 5); |  |  |
| 2. It is "fresh enough" (see Section 4). In the default case, this |  | o the "no-store" cache directive (see Section 3.2) does not appear |
| means it meets the least restrictive freshness requirement of the |  | in request or response headers, and |
| client, origin server, and cache (see Section 16.2); if the |  |  |
| origin server so specifies, it is the freshness requirement of |  |  |
| the origin server alone. If a stored response is not "fresh |  |  |
| enough" by the most restrictive freshness requirement of both the |  |  |
| client and the origin server, in carefully considered |  |  |
| circumstances the cache MAY still return the response with the |  |  |
| appropriate Warning header (see Sections 3.5 and 16.6), unless |  |  |
| such a response is prohibited (e.g., by a "no-store" cache- |  |  |
| directive, or by a "no-cache" cache-request-directive; see |  |  |
| Section 16.2). |  |  |
| 3. It is an appropriate 304 (Not Modified), 305 (Use Proxy), or |  | o the "private" cache response directive (see Section 3.2 does not |
| error (4xx or 5xx) response message. |  | appear in the response, if the cache is shared, and |
| If the cache can not communicate with the origin server, then a |  | o the "Authorization" header (see Section 3.1 of [Part7]) does not |
| correct cache SHOULD respond as above if the response can be |  | appear in the request, if the cache is shared (unless the "public" |
| correctly served from the cache; if not it MUST return an error or |  | directive is present; see Section 3.2), and |
| warning indicating that there was a communication failure. |  |  |
| If a cache receives a response (either an entire response, or a 304 |  | o the cache understands partial responses, if the response is |
| (Not Modified) response) that it would normally forward to the |  | partial or incomplete (see Section 2.1.1). |
| requesting client, and the received response is no longer fresh, the |  |  |
| cache SHOULD forward it to the requesting client without adding a new |  |  |
| Warning (but without removing any existing Warning headers). A cache |  |  |
| SHOULD NOT attempt to revalidate a response simply because that |  |  |
| response became stale in transit; this might lead to an infinite |  |  |
| loop. A user agent that receives a stale response without a Warning |  |  |
| MAY display a warning indication to the user. |  |  |
| 3.2. Warnings |  | Note that in normal operation, most caches will not store a response |
|  |  | that has neither a cache validator nor an explicit expiration time, |
|  |  | as such responses are not usually useful to store. However, caches |
|  |  | are not prohibited from storing such responses. |
| Whenever a cache returns a response that is neither first-hand nor |  | 2.1.1. Storing Partial and Incomplete Responses |
| "fresh enough" (in the sense of condition 2 in Section 3.1), it MUST |  |  |
| attach a warning to that effect, using a Warning general-header. The |  |  |
| Warning header and the currently defined warnings are described in |  |  |
| Section 16.6. The warning allows clients to take appropriate action. |  |  |
| Warnings MAY be used for other purposes, both cache-related and |  | A cache that receives an incomplete response (for example, with fewer |
| otherwise. The use of a warning, rather than an error status code, |  | bytes of data than specified in a Content-Length header) can store |
| distinguish these responses from true failures. |  | the response, but MUST treat it as a partial response [Part5]. |
|  |  | Partial responses can be combined as described in Section 4 of |
|  |  | [Part5]; the result might be a full response or might still be |
|  |  | partial. A cache MUST NOT return a partial response to a client |
|  |  | without explicitly marking it as such using the 206 (Partial Content) |
|  |  | status code. |
| Warnings are assigned three digit warn-codes. The first digit |  | A cache that does not support the Range and Content-Range headers |
| indicates whether the Warning MUST or MUST NOT be deleted from a |  | MUST NOT store incomplete or partial responses. |
| stored cache entry after a successful revalidation: |  |  |
| 1xx Warnings that describe the freshness or revalidation status of |  | 2.2. Constructing Responses from Caches |
| the response, and so MUST be deleted after a successful |  |  |
| revalidation. 1xx warn-codes MAY be generated by a cache only when |  |  |
| validating a cached entry. It MUST NOT be generated by clients. |  |  |
| 2xx Warnings that describe some aspect of the entity body or entity |  | For a presented request, a cache MUST NOT return a stored response, |
| headers that is not rectified by a revalidation (for example, a |  | unless: |
| lossy compression of the entity bodies) and which MUST NOT be |  |  |
| deleted after a successful revalidation. |  |  |
| See Section 16.6 for the definitions of the codes themselves. |  | o The presented Request-URI and that of the stored response match |
|  |  | (see [[anchor1: TBD]]), and |
| HTTP/1.0 caches will cache all Warnings in responses, without |  | o the request method associated with the stored response allows it |
| deleting the ones in the first category. Warnings in responses that |  | to be used for the presented request, and |
| are passed to HTTP/1.0 caches carry an extra warning-date field, |  |  |
| which prevents a future HTTP/1.1 recipient from believing an |  |  |
| erroneously cached Warning. |  |  |
| Warnings also carry a warning text. The text MAY be in any |  | o selecting request-headers nominated by the stored response (if |
| appropriate natural language (perhaps based on the client's Accept |  | any) match those presented (see Section 2.6), and |
| headers), and include an OPTIONAL indication of what character set is |  | o the presented request and stored response are free from directives |
| used. |  | that would prevent its use (see Section 3.2 and Section 3.4), and |
| Multiple warnings MAY be attached to a response (either by the origin |  | o the stored response is either: |
| server or by a cache), including multiple warnings with the same code |  |  |
| number. For example, a server might provide the same warning with |  |  |
| texts in both English and Basque. |  |  |
| When multiple warnings are attached to a response, it might not be |  | * fresh (see Section 2.3), or |
| practical or reasonable to display all of them to the user. This |  |  |
| version of HTTP does not specify strict priority rules for deciding |  |  |
| which warnings to display and in what order, but does suggest some |  |  |
| heuristics. |  |  |
| 3.3. Cache-control Mechanisms |  | * allowed to be served stale (see Section 2.3.3), or |
| The basic cache mechanisms in HTTP/1.1 (server-specified expiration |  | * successfully validated (see Section 2.4). |
| times and validators) are implicit directives to caches. In some |  |  |
| cases, a server or client might need to provide explicit directives |  |  |
| to the HTTP caches. We use the Cache-Control header for this |  |  |
| purpose. |  |  |
| The Cache-Control header allows a client or server to transmit a |  | [[anchor2: TODO: define method cacheability for GET, HEAD and POST in |
| variety of directives in either requests or responses. These |  | p2-semantics.]] |
| directives typically override the default caching algorithms. As a |  |  |
| general rule, if there is any apparent conflict between header |  |  |
| values, the most restrictive interpretation is applied (that is, the |  |  |
| one that is most likely to preserve semantic transparency). However, |  |  |
| in some cases, cache-control directives are explicitly specified as |  |  |
| weakening the approximation of semantic transparency (for example, |  |  |
| "max-stale" or "public"). |  |  |
| The cache-control directives are described in detail in Section 16.2. |  | When a stored response is used to satisfy a request, caches MUST |
|  |  | include a single Age header field Section 3.1 in the response with a |
|  |  | value equal to the stored response's current_age; see Section 2.3.2. |
|  |  | [[anchor3: DISCUSS: this currently includes successfully validated |
|  |  | responses.]] |
| 3.4. Explicit User Agent Warnings |  | Requests with methods that are unsafe (Section 7.1.1 of [Part2]) MUST |
|  |  | be written through the cache to the origin server; i.e., A cache must |
|  |  | not reply to such a request before having forwarded the request and |
|  |  | having received a corresponding response. |
| Many user agents make it possible for users to override the basic |  | Also, note that unsafe requests might invalidate already stored |
| caching mechanisms. For example, the user agent might allow the user |  | responses; see Section 2.5. |
| to specify that cached entities (even explicitly stale ones) are |  |  |
| never validated. Or the user agent might habitually add "Cache- |  |  |
| Control: max-stale=3600" to every request. The user agent SHOULD NOT |  |  |
| default to either non-transparent behavior, or behavior that results |  |  |
| in abnormally ineffective caching, but MAY be explicitly configured |  |  |
| to do so by an explicit action of the user. |  |  |
| If the user has overridden the basic caching mechanisms, the user |  | Caches MUST use the most recent response (as determined by the Date |
| agent SHOULD explicitly indicate to the user whenever this results in |  | header) when more than one suitable response is stored. They can |
| the display of information that might not meet the server's |  | also forward a request with "Cache-Control: max-age=0" or "Cache- |
| transparency requirements (in particular, if the displayed entity is |  | Control: no-cache" to disambiguate which response to use. |
| known to be stale). Since the protocol normally allows the user |  |  |
| agent to determine if responses are stale or not, this indication |  |  |
| need only be displayed when this actually happens. The indication |  |  |
| need not be a dialog box; it could be an icon (for example, a picture |  |  |
| of a rotting fish) or some other indicator. |  |  |
| If the user has overridden the caching mechanisms in a way that would |  | [[anchor4: TODO: end-to-end and hop-by-hop headers, non-modifiable |
| abnormally reduce the effectiveness of caches, the user agent SHOULD |  | headers removed; re-spec in p1]] |
| continually indicate this state to the user (for example, by a |  |  |
| display of a picture of currency in flames) so that the user does not |  |  |
| inadvertently consume excess resources or suffer from excessive |  |  |
| latency. |  |  |
| 3.5. Exceptions to the Rules and Warnings |  | 2.3. Freshness Model |
| In some cases, the operator of a cache MAY choose to configure it to |  | When a response is "fresh" in the cache, it can be used to satisfy |
| return stale responses even when not requested by clients. This |  | subsequent requests without contacting the origin server, thereby |
| decision ought not be made lightly, but may be necessary for reasons |  | improving efficiency. |
| of availability or performance, especially when the cache is poorly |  |  |
| connected to the origin server. Whenever a cache returns a stale |  |  |
| response, it MUST mark it as such (using a Warning header) enabling |  |  |
| the client software to alert the user that there might be a potential |  |  |
| problem. |  |  |
| It also allows the user agent to take steps to obtain a first-hand or |  | The primary mechanism for determining freshness is for an origin |
| fresh response. For this reason, a cache SHOULD NOT return a stale |  | server to provide an explicit expiration time in the future, using |
| response if the client explicitly requests a first-hand or fresh one, |  | either the Expires header (Section 3.3) or the max-age response cache |
| unless it is impossible to comply for technical or policy reasons. |  | directive (Section 3.2.2). Generally, origin servers will assign |
|  |  | future explicit expiration times to responses in the belief that the |
|  |  | entity is not likely to change in a semantically significant way |
|  |  | before the expiration time is reached. |
| 3.6. Client-controlled Behavior |  | If an origin server wishes to force a cache to validate every |
|  |  | request, it can assign an explicit expiration time in the past. This |
|  |  | means that the response is always stale, so that caches should |
|  |  | validate it before using it for subsequent requests. [[anchor5: This |
|  |  | wording may cause confusion, because the response may still be served |
|  |  | stale.]] |
| While the origin server (and to a lesser extent, intermediate caches, |  | Since origin servers do not always provide explicit expiration times, |
| by their contribution to the age of a response) are the primary |  | HTTP caches may also assign heuristic expiration times when they are |
| source of expiration information, in some cases the client might need |  | not specified, employing algorithms that use other header values |
| to control a cache's decision about whether to return a cached |  | (such as the Last-Modified time) to estimate a plausible expiration |
| response without validating it. Clients do this using several |  | time. The HTTP/1.1 specification does not provide specific |
| directives of the Cache-Control header. |  | algorithms, but does impose worst-case constraints on their results. |
| A client's request MAY specify the maximum age it is willing to |  | The calculation to determine if a response is fresh is: |
| accept of an unvalidated response; specifying a value of zero forces |  |  |
| the cache(s) to revalidate all responses. A client MAY also specify |  |  |
| the minimum time remaining before a response expires. Both of these |  |  |
| options increase constraints on the behavior of caches, and so cannot |  |  |
| further relax the cache's approximation of semantic transparency. |  |  |
| A client MAY also specify that it will accept stale responses, up to |  | response_is_fresh = (freshness_lifetime > current_age) |
| some maximum amount of staleness. This loosens the constraints on |  |  |
| the caches, and so might violate the origin server's specified |  |  |
| constraints on semantic transparency, but might be necessary to |  |  |
| support disconnected operation, or high availability in the face of |  |  |
| poor connectivity. |  |  |
| 4. Expiration Model |  | The freshness_lifetime is defined in Section 2.3.1; the current_age |
|  |  | is defined in Section 2.3.2. |
| 4.1. Server-Specified Expiration |  | Additionally, clients may need to influence freshness calculation. |
|  |  | They can do this using several request cache directives, with the |
|  |  | effect of either increasing or loosening constraints on freshness. |
|  |  | See Section 3.2.1. |
| HTTP caching works best when caches can entirely avoid making |  | [[anchor6: ISSUE: there are not requirements directly applying to |
| requests to the origin server. The primary mechanism for avoiding |  | cache-request-directives and freshness.]] |
| requests is for an origin server to provide an explicit expiration |  |  |
| time in the future, indicating that a response MAY be used to satisfy |  |  |
| subsequent requests. In other words, a cache can return a fresh |  |  |
| response without first contacting the server. |  |  |
| Our expectation is that servers will assign future explicit |  | Note that freshness applies only to cache operation; it cannot be |
| expiration times to responses in the belief that the entity is not |  | used to force a user agent to refresh its display or reload a |
| likely to change, in a semantically significant way, before the |  | resource. See Section 4 for an explanation of the difference between |
| expiration time is reached. This normally preserves semantic |  | caches and history mechanisms. |
| transparency, as long as the server's expiration times are carefully |  |  |
| chosen. |  |  |
| The expiration mechanism applies only to responses taken from a cache |  | 2.3.1. Calculating Freshness Lifetime |
| and not to first-hand responses forwarded immediately to the |  |  |
| requesting client. |  |  |
| If an origin server wishes to force a semantically transparent cache |  | A cache can calculate the freshness lifetime (denoted as |
| to validate every request, it MAY assign an explicit expiration time |  | freshness_lifetime) of a response by using the first match of: |
| in the past. This means that the response is always stale, and so |  |  |
| the cache SHOULD validate it before using it for subsequent requests. |  |  |
| See Section 16.2.4 for a more restrictive way to force revalidation. |  |  |
| If an origin server wishes to force any HTTP/1.1 cache, no matter how |  | o If the cache is shared and the s-maxage response cache directive |
| it is configured, to validate every request, it SHOULD use the "must- |  | (Section 3.2.2) is present, use its value, or |
| revalidate" cache-control directive (see Section 16.2). |  |  |
| Servers specify explicit expiration times using either the Expires |  | o If the max-age response cache directive (Section 3.2.2) is |
| header, or the max-age directive of the Cache-Control header. |  | present, use its value, or |
|  |  | o If the Expires response header (Section 3.3) is present, use its |
|  |  | value minus the value of the Date response header, or |
| An expiration time cannot be used to force a user agent to refresh |  | o Otherwise, no explicit expiration time is present in the response, |
| its display or reload a resource; its semantics apply only to caching |  | but a heuristic may be used; see Section 2.3.1.1. |
| mechanisms, and such mechanisms need only check a resource's |  |  |
| expiration status when a new request for that resource is initiated. |  |  |
| See Section 15 for an explanation of the difference between caches |  |  |
| and history mechanisms. |  |  |
| 4.2. Heuristic Expiration |  | Note that this calculation is not vulnerable to clock skew, since all |
|  |  | of the information comes from the origin server. |
| Since origin servers do not always provide explicit expiration times, |  | 2.3.1.1. Calculating Heuristic Freshness |
| HTTP caches typically assign heuristic expiration times, employing |  |  |
| algorithms that use other header values (such as the Last-Modified |  |  |
| time) to estimate a plausible expiration time. The HTTP/1.1 |  |  |
| specification does not provide specific algorithms, but does impose |  |  |
| worst-case constraints on their results. Since heuristic expiration |  |  |
| times might compromise semantic transparency, they ought to be used |  |  |
| cautiously, and we encourage origin servers to provide explicit |  |  |
| expiration times as much as possible. |  |  |
| 4.3. Age Calculations |  | If no explicit expiration time is present in a stored response that |
|  |  | has a status code of 200, 203, 206, 300, 301 or 410, a heuristic |
|  |  | expiration time can be calculated. Heuristics MUST NOT be used for |
|  |  | other response status codes. |
| In order to know if a cached entry is fresh, a cache needs to know if |  | When a heuristic is used to calculate freshness lifetime, the cache |
| its age exceeds its freshness lifetime. We discuss how to calculate |  | SHOULD attach a Warning header with a 113 warn-code to the response |
| the latter in Section 4.4; this section describes how to calculate |  | if its current_age is more than 24 hours and such a warning is not |
| the age of a response or cache entry. |  | already present. |
| In this discussion, we use the term "now" to mean "the current value |  | Also, if the response has a Last-Modified header (Section 6.6 of |
| of the clock at the host performing the calculation." Hosts that use |  | [Part4]), the heuristic expiration value SHOULD be no more than some |
| HTTP, but especially hosts running origin servers and caches, SHOULD |  | fraction of the interval since that time. A typical setting of this |
| use NTP [RFC1305] or some similar protocol to synchronize their |  | fraction might be 10%. |
| clocks to a globally accurate time standard. |  |  |
| HTTP/1.1 requires origin servers to send a Date header, if possible, |  | [[anchor7: REVIEW: took away HTTP/1.0 query string heuristic |
| with every response, giving the time at which the response was |  | uncacheability.]] |
| generated (see Section 8.3 of [Part1]). We use the term "date_value" |  |  |
| to denote the value of the Date header, in a form appropriate for |  | 2.3.2. Calculating Age |
| arithmetic operations. |  |  |
| HTTP/1.1 uses the Age response-header to convey the estimated age of |  | HTTP/1.1 uses the Age response-header to convey the estimated age of |
| the response message when obtained from a cache. The Age field value |  | the response message when obtained from a cache. The Age field value |
| is the cache's estimate of the amount of time since the response was |  | is the cache's estimate of the amount of time since the response was |
| generated or revalidated by the origin server. |  | generated or validated by the origin server. In essence, the Age |
|  |  | value is the sum of the time that the response has been resident in |
|  |  | each of the caches along the path from the origin server, plus the |
|  |  | amount of time it has been in transit along network paths. |
| In essence, the Age value is the sum of the time that the response |  | The term "age_value" denotes the value of the Age header, in a form |
| has been resident in each of the caches along the path from the |  | appropriate for arithmetic operations. |
| origin server, plus the amount of time it has been in transit along |  |  |
| network paths. |  |  |
| We use the term "age_value" to denote the value of the Age header, in |  | HTTP/1.1 requires origin servers to send a Date header, if possible, |
| a form appropriate for arithmetic operations. |  | with every response, giving the time at which the response was |
|  |  | generated (see Section 8.3 of [Part1]). The term "date_value" |
|  |  | denotes the value of the Date header, in a form appropriate for |
|  |  | arithmetic operations. |
|  |  | The term "now" means "the current value of the clock at the host |
|  |  | performing the calculation." Hosts that use HTTP, but especially |
|  |  | hosts running origin servers and caches, SHOULD use NTP [RFC1305] or |
|  |  | some similar protocol to synchronize their clocks to a globally |
|  |  | accurate time standard. |
| A response's age can be calculated in two entirely independent ways: |  | A response's age can be calculated in two entirely independent ways: |
| 1. now minus date_value, if the local clock is reasonably well |  | 1. now minus date_value, if the local clock is reasonably well |
| synchronized to the origin server's clock. If the result is |  | synchronized to the origin server's clock. If the result is |
| negative, the result is replaced by zero. |  | negative, the result is replaced by zero. |
| 2. age_value, if all of the caches along the response path implement |  | 2. age_value, if all of the caches along the response path implement |
| HTTP/1.1. |  | HTTP/1.1. |
| Given that we have two independent ways to compute the age of a |  | These are combined as |
| response when it is received, we can combine these as |  |  |
| corrected_received_age = max(now - date_value, age_value) |  | corrected_received_age = max(now - date_value, age_value) |
| and as long as we have either nearly synchronized clocks or all- |  | When an Age value is received, it MUST be interpreted relative to the |
| HTTP/1.1 paths, one gets a reliable (conservative) result. |  | time the request was initiated, not the time that the response was |
|  |  | received. |
| Because of network-imposed delays, some significant interval might |  |  |
| pass between the time that a server generates a response and the time |  |  |
| it is received at the next outbound cache or client. If uncorrected, |  |  |
| this delay could result in improperly low ages. |  |  |
| Because the request that resulted in the returned Age value must have |  |  |
| been initiated prior to that Age value's generation, we can correct |  |  |
| for delays imposed by the network by recording the time at which the |  |  |
| request was initiated. Then, when an Age value is received, it MUST |  |  |
| be interpreted relative to the time the request was initiated, not |  |  |
| the time that the response was received. This algorithm results in |  |  |
| conservative behavior no matter how much delay is experienced. So, |  |  |
| we compute: |  |  |
| corrected_initial_age = corrected_received_age |  | corrected_initial_age = corrected_received_age |
| + (now - request_time) |  | + (now - request_time) |
| where "request_time" is the time (according to the local clock) when |  | where "request_time" is the time (according to the local clock) when |
| the request that elicited this response was sent. |  | the request that elicited this response was sent. |
| Summary of age calculation algorithm, when a cache receives a |  | The current_age of a stored response can then be calculated by adding |
| response: |  | the amount of time (in seconds) since the stored response was last |
|  |  | validated by the origin server to the corrected_initial_age. |
| /* |  | In summary: |
| * age_value |  |  |
| * is the value of Age: header received by the cache with |  | age_value - Age header field-value received with the response |
| * this response. |  | date_value - Date header field-value received with the response |
| * date_value |  | request_time - local time when the cache made the request |
| * is the value of the origin server's Date: header |  | resulting in the stored response |
| * request_time |  | response_time - local time when the cache received the response |
| * is the (local) time when the cache made the request |  | now - current local time |
| * that resulted in this cached response |  |  |
| * response_time |  |  |
| * is the (local) time when the cache received the |  |  |
| * response |  |  |
| * now |  |  |
| * is the current (local) time |  |  |
| */ |  |  |
| apparent_age = max(0, response_time - date_value); |  | apparent_age = max(0, response_time - date_value); |
| corrected_received_age = max(apparent_age, age_value); |  | corrected_received_age = max(apparent_age, age_value); |
| response_delay = response_time - request_time; |  | response_delay = response_time - request_time; |
| corrected_initial_age = corrected_received_age + response_delay; |  | corrected_initial_age = corrected_received_age + response_delay; |
| resident_time = now - response_time; |  | resident_time = now - response_time; |
| current_age = corrected_initial_age + resident_time; |  | current_age = corrected_initial_age + resident_time; |
| The current_age of a cache entry is calculated by adding the amount |  | 2.3.3. Serving Stale Responses |
| of time (in seconds) since the cache entry was last validated by the |  |  |
| origin server to the corrected_initial_age. When a response is |  |  |
| generated from a cache entry, the cache MUST include a single Age |  |  |
| header field in the response with a value equal to the cache entry's |  |  |
| current_age. |  |  |
| The presence of an Age header field in a response implies that a |  |  |
| response is not first-hand. However, the converse is not true, since |  |  |
| the lack of an Age header field in a response does not imply that the |  |  |
| response is first-hand unless all caches along the request path are |  |  |
| compliant with HTTP/1.1 (i.e., older HTTP caches did not implement |  |  |
| the Age header field). |  |  |
| 4.4. Expiration Calculations |  |  |
| In order to decide whether a response is fresh or stale, we need to |  |  |
| compare its freshness lifetime to its age. The age is calculated as |  |  |
| described in Section 4.3; this section describes how to calculate the |  |  |
| freshness lifetime, and to determine if a response has expired. In |  |  |
| the discussion below, the values can be represented in any form |  |  |
| appropriate for arithmetic operations. |  |  |
| We use the term "expires_value" to denote the value of the Expires |  |  |
| header. We use the term "max_age_value" to denote an appropriate |  |  |
| value of the number of seconds carried by the "max-age" directive of |  |  |
| the Cache-Control header in a response (see Section 16.2.3). |  |  |
| The max-age directive takes priority over Expires, so if max-age is |  |  |
| present in a response, the calculation is simply: |  |  |
| freshness_lifetime = max_age_value |  |  |
| Otherwise, if Expires is present in the response, the calculation is: |  |  |
| freshness_lifetime = expires_value - date_value |  |  |
| Note that neither of these calculations is vulnerable to clock skew, |  |  |
| since all of the information comes from the origin server. |  |  |
| If none of Expires, Cache-Control: max-age, or Cache-Control: |  |  |
| s-maxage (see Section 16.2.3) appears in the response, and the |  |  |
| response does not include other restrictions on caching, the cache |  |  |
| MAY compute a freshness lifetime using a heuristic. The cache MUST |  |  |
| attach Warning 113 to any response whose age is more than 24 hours if |  |  |
| such warning has not already been added. |  |  |
| Also, if the response does have a Last-Modified time, the heuristic |  |  |
| expiration value SHOULD be no more than some fraction of the interval |  |  |
| since that time. A typical setting of this fraction might be 10%. |  |  |
| The calculation to determine if a response has expired is quite |  |  |
| simple: |  |  |
| response_is_fresh = (freshness_lifetime > current_age) |  |  |
| 4.5. Disambiguating Expiration Values |  |  |
| Because expiration values are assigned optimistically, it is possible |  |  |
| for two caches to contain fresh values for the same resource that are |  |  |
| different. |  |  |
| If a client performing a retrieval receives a non-first-hand response |  |  |
| for a request that was already fresh in its own cache, and the Date |  |  |
| header in its existing cache entry is newer than the Date on the new |  |  |
| response, then the client MAY ignore the response. If so, it MAY |  |  |
| retry the request with a "Cache-Control: max-age=0" directive (see |  |  |
| Section 16.2), to force a check with the origin server. |  |  |
| If a cache has two fresh responses for the same representation with |  |  |
| different validators, it MUST use the one with the more recent Date |  |  |
| header. This situation might arise because the cache is pooling |  |  |
| responses from other caches, or because a client has asked for a |  |  |
| reload or a revalidation of an apparently fresh cache entry. |  |  |
| 4.6. Disambiguating Multiple Responses |  |  |
| Because a client might be receiving responses via multiple paths, so |  |  |
| that some responses flow through one set of caches and other |  |  |
| responses flow through a different set of caches, a client might |  |  |
| receive responses in an order different from that in which the origin |  |  |
| server sent them. We would like the client to use the most recently |  |  |
| generated response, even if older responses are still apparently |  |  |
| fresh. |  |  |
| Neither the entity tag nor the expiration value can impose an |  |  |
| ordering on responses, since it is possible that a later response |  |  |
| intentionally carries an earlier expiration time. The Date values |  |  |
| are ordered to a granularity of one second. |  |  |
| When a client tries to revalidate a cache entry, and the response it |  |  |
| receives contains a Date header that appears to be older than the one |  |  |
| for the existing entry, then the client SHOULD repeat the request |  |  |
| unconditionally, and include |  |  |
| Cache-Control: max-age=0 |  |  |
| to force any intermediate caches to validate their copies directly |  |  |
| with the origin server, or |  |  |
| Cache-Control: no-cache |  |  |
| to force any intermediate caches to obtain a new copy from the origin |  |  |
| server. |  |  |
| If the Date values are equal, then the client MAY use either response |  |  |
| (or MAY, if it is being extremely prudent, request a new response). |  |  |
| Servers MUST NOT depend on clients being able to choose |  |  |
| deterministically between responses generated during the same second, |  |  |
| if their expiration times overlap. |  |  |
| 5. Validation Model |  |  |
| When a cache has a stale entry that it would like to use as a |  |  |
| response to a client's request, it first has to check with the origin |  |  |
| server (or possibly an intermediate cache with a fresh response) to |  |  |
| see if its cached entry is still usable. We call this "validating" |  |  |
| the cache entry. |  |  |
| HTTP's conditional request mechanism, defined in [Part4], is used to |  |  |
| avoid retransmitting the response payload when the cached entry is |  |  |
| valid. When a cached response includes one or more "cache |  |  |
| validators," such as the field values of an ETag or Last-Modified |  |  |
| header field, then a validating GET request SHOULD be made |  |  |
| conditional to those field values. The server checks the conditional |  |  |
| request's validator against the current state of the requested |  |  |
| resource and, if they match, the server responds with a 304 (Not |  |  |
| Modified) status code to indicate that the cached response can be |  |  |
| refreshed and reused without retransmitting the response payload. If |  |  |
| the validator does not match the current state of the requested |  |  |
| resource, then the server returns a full response, including payload, |  |  |
| so that the request can be satisfied and the cache entry supplanted |  |  |
| without the need for an additional network round-trip. |  |  |
| 6. Response Cacheability |  |  |
| Unless specifically constrained by a cache-control (Section 16.2) |  |  |
| directive, a caching system MAY always store a successful response |  |  |
| (see Section 10) as a cache entry, MAY return it without validation |  |  |
| if it is fresh, and MAY return it after successful validation. If |  |  |
| there is neither a cache validator nor an explicit expiration time |  |  |
| associated with a response, we do not expect it to be cached, but |  |  |
| certain caches MAY violate this expectation (for example, when little |  |  |
| or no network connectivity is available). A client can usually |  |  |
| detect that such a response was taken from a cache by comparing the |  |  |
| Date header to the current time. |  |  |
| Note: some HTTP/1.0 caches are known to violate this expectation |  |  |
| without providing any Warning. |  |  |
| However, in some cases it might be inappropriate for a cache to |  |  |
| retain an entity, or to return it in response to a subsequent |  |  |
| request. This might be because absolute semantic transparency is |  |  |
| deemed necessary by the service author, or because of security or |  |  |
| privacy considerations. Certain cache-control directives are |  |  |
| therefore provided so that the server can indicate that certain |  |  |
| resource entities, or portions thereof, are not to be cached |  |  |
| regardless of other considerations. |  |  |
| Note that Section 4.1 of [Part7] normally prevents a shared cache |  |  |
| from saving and returning a response to a previous request if that |  |  |
| request included an Authorization header. |  |  |
| A response received with a status code of 200, 203, 206, 300, 301 or |  |  |
| 410 MAY be stored by a cache and used in reply to a subsequent |  |  |
| request, subject to the expiration mechanism, unless a cache-control |  |  |
| directive prohibits caching. However, a cache that does not support |  |  |
| the Range and Content-Range headers MUST NOT cache 206 (Partial |  |  |
| Content) responses. |  |  |
| A response received with any other status code (e.g. status codes 302 |  |  |
| and 307) MUST NOT be returned in a reply to a subsequent request |  |  |
| unless there are cache-control directives or another header(s) that |  |  |
| explicitly allow it. For example, these include the following: an |  |  |
| Expires header (Section 16.3); a "max-age", "s-maxage", "must- |  |  |
| revalidate", "proxy-revalidate", "public" or "private" cache-control |  |  |
| directive (Section 16.2). |  |  |
| 7. Constructing Responses From Caches |  |  |
| The purpose of an HTTP cache is to store information received in |  |  |
| response to requests for use in responding to future requests. In |  |  |
| many cases, a cache simply returns the appropriate parts of a |  |  |
| response to the requester. However, if the cache holds a cache entry |  |  |
| based on a previous response, it might have to combine parts of a new |  |  |
| response with what is held in the cache entry. |  |  |
| 7.1. End-to-end and Hop-by-hop Headers |  |  |
| For the purpose of defining the behavior of caches and non-caching |  |  |
| proxies, we divide HTTP headers into two categories: |  |  |
| o End-to-end headers, which are transmitted to the ultimate |  |  |
| recipient of a request or response. End-to-end headers in |  |  |
| responses MUST be stored as part of a cache entry and MUST be |  |  |
| transmitted in any response formed from a cache entry. |  |  |
| o Hop-by-hop headers, which are meaningful only for a single |  |  |
| transport-level connection, and are not stored by caches or |  |  |
| forwarded by proxies. |  |  |
| The following HTTP/1.1 headers are hop-by-hop headers: |  |  |
| o Connection |  |  |
| o Keep-Alive |  |  |
| o Proxy-Authenticate |  |  |
| o Proxy-Authorization |  |  |
| o TE |  |  |
| o Trailer |  |  |
| o Transfer-Encoding |  |  |
| o Upgrade |  |  |
| All other headers defined by HTTP/1.1 are end-to-end headers. |  |  |
| Other hop-by-hop headers MUST be listed in a Connection header |  |  |
| (Section 8.1 of [Part1]). |  |  |
| 7.2. Non-modifiable Headers |  |  |
| Some features of HTTP/1.1, such as Digest Authentication, depend on |  |  |
| the value of certain end-to-end headers. A transparent proxy SHOULD |  |  |
| NOT modify an end-to-end header unless the definition of that header |  |  |
| requires or specifically allows that. |  |  |
| A transparent proxy MUST NOT modify any of the following fields in a |  |  |
| request or response, and it MUST NOT add any of these fields if not |  |  |
| already present: |  |  |
| o Content-Location |  |  |
| o Content-MD5 |  |  |
| o ETag |  | A "stale" response is one that either has explicit expiry |
|  |  | information, or is allowed to have heuristic expiry calculated, but |
|  |  | is not fresh according to the calculations in Section 2.3. |
| o Last-Modified |  | Caches MUST NOT return a stale response if it is prohibited by an |
|  |  | explicit in-protocol directive (e.g., by a "no-store" or "no-cache" |
|  |  | cache directive, a "must-revalidate" cache-response-directive, or an |
|  |  | applicable "s-maxage" or "proxy-revalidate" cache-response-directive; |
|  |  | see Section 3.2.2). |
| A transparent proxy MUST NOT modify any of the following fields in a |  | Caches SHOULD NOT return stale responses unless they are disconnected |
| response: |  | (i.e., it cannot contact the origin server or otherwise find a |
|  |  | forward path) or otherwise explicitly allowed (e.g., the max-stale |
|  |  | request directive; see Section 3.2.1). |
| o Expires |  | Stale responses SHOULD have a Warning header with the 110 warn-code |
|  |  | (see Section 3.6). Likewise, the 112 warn-code SHOULD be sent on |
|  |  | stale responses if the cache is disconnected. |
| but it MAY add any of these fields if not already present. If an |  | If a cache receives a first-hand response (either an entire response, |
| Expires header is added, it MUST be given a field-value identical to |  | or a 304 (Not Modified) response) that it would normally forward to |
| that of the Date header in that response. |  | the requesting client, and the received response is no longer fresh, |
|  |  | the cache SHOULD forward it to the requesting client without adding a |
|  |  | new Warning (but without removing any existing Warning headers). A |
|  |  | cache SHOULD NOT attempt to validate a response simply because that |
|  |  | response became stale in transit. |
| A proxy MUST NOT modify or add any of the following fields in a |  | 2.4. Validation Model |
| message that contains the no-transform cache-control directive, or in |  |  |
| any request: |  |  |
| o Content-Encoding |  | Checking with the origin server to see if a stale or otherwise |
|  |  | unusable cached response can be reused is called "validating" or |
|  |  | "revalidating." Doing so potentially avoids the overhead of |
|  |  | retransmitting the response body when the stored response is valid. |
| o Content-Range |  | HTTP's conditional request mechanism [Part4] is used for this |
| o Content-Type |  | purpose. When a stored response includes one or more validators, |
|  |  | such as the field values of an ETag or Last-Modified header field, |
|  |  | then a validating request SHOULD be made conditional to those field |
|  |  | values. |
| A non-transparent proxy MAY modify or add these fields to a message |  | A 304 (Not Modified) response status code indicates that the stored |
| that does not include no-transform, but if it does so, it MUST add a |  | response can be updated and reused; see Section 2.7. |
| Warning 214 (Transformation applied) if one does not already appear |  |  |
| in the message (see Section 16.6). |  |  |
| Warning: unnecessary modification of end-to-end headers might |  | If instead the cache receives a full response (i.e., one with a |
| cause authentication failures if stronger authentication |  | response body), it is used to satisfy the request and replace the |
| mechanisms are introduced in later versions of HTTP. Such |  | stored response. [[anchor8: Should there be a requirement here?]] |
| authentication mechanisms MAY rely on the values of header fields |  | If a cache receives a 5xx response while attempting to validate a |
| not listed here. |  | response, it MAY either forward this response to the requesting |
|  |  | client, or act as if the server failed to respond. In the latter |
|  |  | case, it MAY return a previously stored response (which SHOULD |
|  |  | include the 111 warn-code; see Section 3.6) unless the stored |
|  |  | response includes the "must-revalidate" cache directive (see |
|  |  | Section 2.3.3). |
| The Content-Length field of a request or response is added or deleted |  | 2.5. Request Methods that Invalidate |
| according to the rules in Section 4.4 of [Part1]. A transparent |  |  |
| proxy MUST preserve the entity-length (Section 4.2.2 of [Part3]) of |  |  |
| the entity-body, although it MAY change the transfer-length (Section |  |  |
| 4.4 of [Part1]). |  |  |
| 7.3. Combining Headers |  | Because unsafe methods (Section 7.1.1 of [Part2]) have the potential |
|  |  | for changing state on the origin server, intervening caches can use |
|  |  | them to keep their contents up-to-date. |
| When a cache makes a validating request to a server, and the server |  | The following HTTP methods MUST cause a cache to invalidate the |
| provides a 304 (Not Modified) response or a 206 (Partial Content) |  | Request-URI as well as the Location and Content-Location headers (if |
| response, the cache then constructs a response to send to the |  | present): |
| requesting client. |  |  |
| If the status code is 304 (Not Modified), the cache uses the entity- |  | o PUT |
| body stored in the cache entry as the entity-body of this outgoing |  |  |
| response. If the status code is 206 (Partial Content) and the ETag |  |  |
| or Last-Modified headers match exactly, the cache MAY combine the |  |  |
| contents stored in the cache entry with the new contents received in |  |  |
| the response and use the result as the entity-body of this outgoing |  |  |
| response, (see Section 5 of [Part5]). |  |  |
| The end-to-end headers stored in the cache entry are used for the |  | o DELETE |
| constructed response, except that |  |  |
| o any stored Warning headers with warn-code 1xx (see Section 16.6) |  | o POST |
| MUST be deleted from the cache entry and the forwarded response. |  |  |
| o any stored Warning headers with warn-code 2xx MUST be retained in |  | An invalidation based on the URI in a Location or Content-Location |
| the cache entry and the forwarded response. |  | header MUST NOT be performed if the host part of that URI differs |
|  |  | from the host part in the Request-URI. This helps prevent denial of |
|  |  | service attacks. |
| o any end-to-end headers provided in the 304 or 206 response MUST |  | [[anchor9: TODO: "host part" needs to be specified better.]] |
| replace the corresponding headers from the cache entry. |  |  |
| Unless the cache decides to remove the cache entry, it MUST also |  | A cache that passes through requests for methods it does not |
| replace the end-to-end headers stored with the cache entry with |  | understand SHOULD invalidate the Request-URI. |
| corresponding headers received in the incoming response, except for |  |  |
| Warning headers as described immediately above. If a header field- |  |  |
| name in the incoming response matches more than one header in the |  |  |
| cache entry, all such old headers MUST be replaced. |  |  |
| In other words, the set of end-to-end headers received in the |  | Here, "invalidate" means that the cache will either remove all stored |
| incoming response overrides all corresponding end-to-end headers |  | responses related to the Request-URI, or will mark these as "invalid" |
| stored with the cache entry (except for stored Warning headers with |  | and in need of a mandatory validation before they can be returned in |
| warn-code 1xx, which are deleted even if not overridden). |  | response to a subsequent request. |
| Note: this rule allows an origin server to use a 304 (Not |  | Note that this does not guarantee that all appropriate responses are |
| Modified) or a 206 (Partial Content) response to update any header |  | invalidated. For example, the request that caused the change at the |
| associated with a previous response for the same entity or sub- |  | origin server might not have gone through the cache where a response |
| ranges thereof, although it might not always be meaningful or |  | is stored. |
| correct to do so. This rule does not allow an origin server to |  |  |
| use a 304 (Not Modified) or a 206 (Partial Content) response to |  |  |
| entirely delete a header that it had provided with a previous |  |  |
| response. |  |  |
| 8. Caching Negotiated Responses |  | [[anchor10: TODO: specify that only successful (2xx, 3xx?) responses |
|  |  | invalidate.]] |
| Use of server-driven content negotiation (Section 5.1 of [Part3]), as |  | 2.6. Caching Negotiated Responses |
| indicated by the presence of a Vary header field in a response, |  |  |
| alters the conditions and procedure by which a cache can use the |  |  |
| response for subsequent requests. See Section 16.5 for use of the |  |  |
| Vary header field by servers. |  |  |
| A server SHOULD use the Vary header field to inform a cache of what |  | Use of server-driven content negotiation (Section 4.1 of [Part3]) |
| request-header fields were used to select among multiple |  | alters the conditions under which a cache can use the response for |
| representations of a cacheable response subject to server-driven |  | subsequent requests. |
| negotiation. The set of header fields named by the Vary field value |  |  |
| is known as the "selecting" request-headers. |  |  |
| When the cache receives a subsequent request whose Request-URI |  | When a cache receives a request that can be satisfied by a stored |
| specifies one or more cache entries including a Vary header field, |  | response that includes a Vary header field (Section 3.5), it MUST NOT |
| the cache MUST NOT use such a cache entry to construct a response to |  | use that response unless all of the selecting request-headers in the |
| the new request unless all of the selecting request-headers present |  | presented request match the corresponding stored request-headers from |
| in the new request match the corresponding stored request-headers in |  |  |
| the original request. |  | the original request. |
| The selecting request-headers from two requests are defined to match |  | The selecting request-headers from two requests are defined to match |
| if and only if the selecting request-headers in the first request can |  | if and only if the selecting request-headers in the first request can |
| be transformed to the selecting request-headers in the second request |  | be transformed to the selecting request-headers in the second request |
| by adding or removing linear white space (LWS) at places where this |  | by adding or removing linear white space [[anchor11: [ref]]] at |
| is allowed by the corresponding BNF, and/or combining multiple |  | places where this is allowed by the corresponding ABNF, and/or |
| message-header fields with the same field name following the rules |  | combining multiple message-header fields with the same field name |
| about message headers in Section 4.2 of [Part1]. |  | following the rules about message headers in Section 4.2 of [Part1]. |
|  |  | [[anchor12: DISCUSS: header-specific canonicalisation]] |
| A Vary header field-value of "*" always fails to match and subsequent |  |  |
| requests on that resource can only be properly interpreted by the |  |  |
| origin server. |  |  |
| If the selecting request header fields for the cached entry do not |  | A Vary header field-value of "*" always fails to match, and |
| match the selecting request header fields of the new request, then |  | subsequent requests to that resource can only be properly interpreted |
| the cache MUST NOT use a cached entry to satisfy the request unless |  | by the origin server. |
| it first relays the new request to the origin server in a conditional |  |  |
| request and the server responds with 304 (Not Modified), including an |  |  |
| entity tag or Content-Location that indicates the entity to be used. |  |  |
| If an entity tag was assigned to a cached representation, the |  | If no stored response matches, the cache MAY forward the presented |
| forwarded request SHOULD be conditional and include the entity tags |  | request to the origin server in a conditional request, and SHOULD |
| in an If-None-Match header field from all its cache entries for the |  | include all ETags stored with potentially suitable responses in an |
| resource. This conveys to the server the set of entities currently |  | If-None-Match request header. If the server responds with 304 (Not |
| held by the cache, so that if any one of these entities matches the |  | Modified) and includes an entity tag or Content-Location that |
| requested entity, the server can use the ETag header field in its 304 |  | indicates the entity to be used, that cached response MUST be used to |
| (Not Modified) response to tell the cache which entry is appropriate. |  | satisfy the presented request, and SHOULD be used to update the |
| If the entity-tag of the new response matches that of an existing |  | corresponding stored response; see Section 2.7. |
| entry, the new response SHOULD be used to update the header fields of |  |  |
| the existing entry, and the result MUST be returned to the client. |  |  |
| If any of the existing cache entries contains only partial content |  | If any of the stored responses contains only partial content, its |
| for the associated entity, its entity-tag SHOULD NOT be included in |  | entity-tag SHOULD NOT be included in the If-None-Match header field |
| the If-None-Match header field unless the request is for a range that |  | unless the request is for a range that would be fully satisfied by |
| would be fully satisfied by that entry. |  | that stored response. |
| If a cache receives a successful response whose Content-Location |  | If a cache receives a successful response whose Content-Location |
| field matches that of an existing cache entry for the same Request- |  | field matches that of an existing stored response for the same |
| URI, whose entity-tag differs from that of the existing entry, and |  | Request-URI, whose entity-tag differs from that of the existing |
| whose Date is more recent than that of the existing entry, the |  | stored response, and whose Date is more recent than that of the |
| existing entry SHOULD NOT be returned in response to future requests |  | existing response, the existing response SHOULD NOT be returned in |
| and SHOULD be deleted from the cache. |  | response to future requests and SHOULD be deleted from the |
|  |  | cache.[[anchor13: DISCUSS: Not sure if this is necessary.]] |
| 9. Shared and Non-Shared Caches |  |  |
| For reasons of security and privacy, it is necessary to make a |  |  |
| distinction between "shared" and "non-shared" caches. A non-shared |  |  |
| cache is one that is accessible only to a single user. Accessibility |  |  |
| in this case SHOULD be enforced by appropriate security mechanisms. |  |  |
| All other caches are considered to be "shared." Other sections of |  |  |
| this specification place certain constraints on the operation of |  |  |
| shared caches in order to prevent loss of privacy or failure of |  |  |
| access controls. |  |  |
| 10. Errors or Incomplete Response Cache Behavior |  |  |
| A cache that receives an incomplete response (for example, with fewer |  |  |
| bytes of data than specified in a Content-Length header) MAY store |  |  |
| the response. However, the cache MUST treat this as a partial |  |  |
| response. Partial responses MAY be combined as described in Section |  |  |
| 5 of [Part5]; the result might be a full response or might still be |  |  |
| partial. A cache MUST NOT return a partial response to a client |  |  |
| without explicitly marking it as such, using the 206 (Partial |  |  |
| Content) status code. A cache MUST NOT return a partial response |  |  |
| using a status code of 200 (OK). |  |  |
| If a cache receives a 5xx response while attempting to revalidate an |  |  |
| entry, it MAY either forward this response to the requesting client, |  |  |
| or act as if the server failed to respond. In the latter case, it |  |  |
| MAY return a previously received response unless the cached entry |  |  |
| includes the "must-revalidate" cache-control directive (see |  |  |
| Section 16.2). |  |  |
| 11. Side Effects of GET and HEAD |  |  |
| Unless the origin server explicitly prohibits the caching of their |  |  |
| responses, the application of GET and HEAD methods to any resources |  |  |
| SHOULD NOT have side effects that would lead to erroneous behavior if |  |  |
| these responses are taken from a cache. They MAY still have side |  |  |
| effects, but a cache is not required to consider such side effects in |  |  |
| its caching decisions. Caches are always expected to observe an |  |  |
| origin server's explicit restrictions on caching. |  |  |
| We note one exception to this rule: since some applications have |  |  |
| traditionally used GET and HEAD requests with URLs containing a query |  |  |
| part to perform operations with significant side effects, caches MUST |  |  |
| NOT treat responses to such URIs as fresh unless the server provides |  |  |
| an explicit expiration time. This specifically means that responses |  |  |
| from HTTP/1.0 servers for such URIs SHOULD NOT be taken from a cache. |  |  |
| See Section 8.1.1 of [Part2] for related information. |  |  |
| 12. Invalidation After Updates or Deletions |  |  |
| The effect of certain methods performed on a resource at the origin |  |  |
| server might cause one or more existing cache entries to become non- |  |  |
| transparently invalid. That is, although they might continue to be |  |  |
| "fresh," they do not accurately reflect what the origin server would |  |  |
| return for a new request on that resource. |  |  |
| There is no way for HTTP to guarantee that all such cache entries are |  |  |
| marked invalid. For example, the request that caused the change at |  |  |
| the origin server might not have gone through the proxy where a cache |  |  |
| entry is stored. However, several rules help reduce the likelihood |  |  |
| of erroneous behavior. |  |  |
| In this section, the phrase "invalidate an entity" means that the |  |  |
| cache will either remove all instances of that entity from its |  |  |
| storage, or will mark these as "invalid" and in need of a mandatory |  |  |
| revalidation before they can be returned in response to a subsequent |  |  |
| request. |  |  |
| Some HTTP methods MUST cause a cache to invalidate an entity. This |  |  |
| is either the entity referred to by the Request-URI, or by the |  |  |
| Location or Content-Location headers (if present). These methods |  |  |
| are: |  |  |
| o PUT |  |  |
| o DELETE |  |  |
| o POST |  |  |
| An invalidation based on the URI in a Location or Content-Location |  |  |
| header MUST NOT be performed if the host part of that URI differs |  |  |
| from the host part in the Request-URI. This helps prevent denial of |  |  |
| service attacks. |  |  |
| A cache that passes through requests for methods it does not |  |  |
| understand SHOULD invalidate any entities referred to by the Request- |  |  |
| URI. |  |  |
| 13. Write-Through Mandatory |  |  |
| All methods that might be expected to cause modifications to the |  |  |
| origin server's resources MUST be written through to the origin |  |  |
| server. This currently includes all methods except for GET and HEAD. |  |  |
| A cache MUST NOT reply to such a request from a client before having |  |  |
| transmitted the request to the inbound server, and having received a |  |  |
| corresponding response from the inbound server. This does not |  |  |
| prevent a proxy cache from sending a 100 (Continue) response before |  |  |
| the inbound server has sent its final reply. |  |  |
| The alternative (known as "write-back" or "copy-back" caching) is not |  |  |
| allowed in HTTP/1.1, due to the difficulty of providing consistent |  |  |
| updates and the problems arising from server, cache, or network |  |  |
| failure prior to write-back. |  |  |
| 14. Cache Replacement |  | 2.7. Combining Responses |
| If a new cacheable (see Sections 16.2.2, 4.5, 4.6 and 10) response is |  | When a cache receives a 304 (Not Modified) response or a 206 (Partial |
| received from a resource while any existing responses for the same |  | Content) response, it needs to update the stored response with the |
| resource are cached, the cache SHOULD use the new response to reply |  | new one, so that the updated response can be sent to the client. |
| to the current request. It MAY insert it into cache storage and MAY, |  |  |
| if it meets all other requirements, use it to respond to any future |  |  |
| requests that would previously have caused the old response to be |  |  |
| returned. If it inserts the new response into cache storage the |  |  |
| rules in Section 7.3 apply. |  |  |
| Note: a new response that has an older Date header value than |  | If the status code is 304 (Not Modified), the cache SHOULD use the |
| existing cached responses is not cacheable. |  | stored entity-body as the updated entity-body. If the status code is |
|  |  | 206 (Partial Content) and the ETag or Last-Modified headers match |
|  |  | exactly, the cache MAY combine the stored entity-body in the stored |
|  |  | response with the updated entity-body received in the response and |
|  |  | use the result as the updated entity-body (see Section 4 of [Part5]). |
| 15. History Lists |  | The stored response headers are used for the updated response, except |
|  |  | that |
| User agents often have history mechanisms, such as "Back" buttons and |  | o any stored Warning headers with warn-code 1xx (see Section 3.6) |
| history lists, which can be used to redisplay an entity retrieved |  | MUST be deleted from the stored response and the forwarded |
| earlier in a session. |  | response. |
| History mechanisms and caches are different. In particular history |  | o any stored Warning headers with warn-code 2xx MUST be retained in |
| mechanisms SHOULD NOT try to show a semantically transparent view of |  | the stored response and the forwarded response. |
| the current state of a resource. Rather, a history mechanism is |  |  |
| meant to show exactly what the user saw at the time when the resource |  |  |
| was retrieved. |  |  |
| By default, an expiration time does not apply to history mechanisms. |  | o any headers provided in the 304 or 206 response MUST replace the |
| If the entity is still in storage, a history mechanism SHOULD display |  | corresponding headers from the stored response. |
| it even if the entity has expired, unless the user has specifically |  |  |
| configured the agent to refresh expired history documents. |  |  |
| This is not to be construed to prohibit the history mechanism from |  | A cache MUST also replace any stored headers with corresponding |
| telling the user that a view might be stale. |  | headers received in the incoming response, except for Warning headers |
|  |  | as described immediately above. If a header field-name in the |
|  |  | incoming response matches more than one header in the stored |
|  |  | response, all such old headers MUST be replaced. It MAY store the |
|  |  | combined entity-body. |
| Note: if history list mechanisms unnecessarily prevent users from |  | [[anchor14: ISSUE: discuss how to handle HEAD updates]] |
| viewing stale resources, this will tend to force service authors |  |  |
| to avoid using HTTP expiration controls and cache controls when |  |  |
| they would otherwise like to. Service authors may consider it |  |  |
| important that users not be presented with error messages or |  |  |
| warning messages when they use navigation controls (such as BACK) |  |  |
| to view previously fetched resources. Even though sometimes such |  |  |
| resources ought not be cached, or ought to expire quickly, user |  |  |
| interface considerations may force service authors to resort to |  |  |
| other means of preventing caching (e.g. "once-only" URLs) in order |  |  |
| not to suffer the effects of improperly functioning history |  |  |
| mechanisms. |  |  |
| 16. Header Field Definitions |  | 3. Header Field Definitions |
| This section defines the syntax and semantics of HTTP/1.1 header |  | This section defines the syntax and semantics of HTTP/1.1 header |
| fields related to caching. |  | fields related to caching. |
| For entity-header fields, both sender and recipient refer to either |  | For entity-header fields, both sender and recipient refer to either |
| the client or the server, depending on who sends and who receives the |  | the client or the server, depending on who sends and who receives the |
| entity. |  | entity. |
| 16.1. Age |  | 3.1. Age |
| The response-header field "Age" conveys the sender's estimate of the |  | The response-header field "Age" conveys the sender's estimate of the |
| amount of time since the response (or its revalidation) was generated |  | amount of time since the response (or its validation) was generated |
| at the origin server. A cached response is "fresh" if its age does |  | at the origin server. Age values are calculated as specified in |
| not exceed its freshness lifetime. Age values are calculated as |  | Section 2.3.2. |
| specified in Section 4.3. |  |  |
| Age = "Age" ":" OWS Age-v |  | Age = "Age" ":" OWS Age-v |
| Age-v = delta-seconds |  | Age-v = delta-seconds |
| Age values are non-negative decimal integers, representing time in |  | Age field-values are non-negative decimal integers, representing time |
| seconds. |  | in seconds. |
| delta-seconds = 1*DIGIT |  | delta-seconds = 1*DIGIT |
| If a cache receives a value larger than the largest positive integer |  | If a cache receives a value larger than the largest positive integer |
| it can represent, or if any of its age calculations overflows, it |  | it can represent, or if any of its age calculations overflows, it |
| MUST transmit an Age header with a value of 2147483648 (2^31). An |  | MUST transmit an Age header with a field-value of 2147483648 (2^31). |
| HTTP/1.1 server that includes a cache MUST include an Age header |  | Caches SHOULD use an arithmetic type of at least 31 bits of range. |
| field in every response generated from its own cache. Caches SHOULD |  |  |
| use an arithmetic type of at least 31 bits of range. |  |  |
| 16.2. Cache-Control |  | The presence of an Age header field in a response implies that a |
|  |  | response is not first-hand. However, the converse is not true, since |
|  |  | HTTP/1.0 caches may not implement the Age header field. |
|  |  | 3.2. Cache-Control |
| The general-header field "Cache-Control" is used to specify |  | The general-header field "Cache-Control" is used to specify |
| directives that MUST be obeyed by all caching mechanisms along the |  | directives that MUST be obeyed by all caches along the request/ |
| request/response chain. The directives specify behavior intended to |  | response chain. The directives specify behavior intended to prevent |
| prevent caches from adversely interfering with the request or |  | caches from adversely interfering with the request or response. |
| response. These directives typically override the default caching |  | Cache directives are unidirectional in that the presence of a |
| algorithms. Cache directives are unidirectional in that the presence |  | directive in a request does not imply that the same directive is to |
| of a directive in a request does not imply that the same directive is |  | be given in the response. |
| to be given in the response. |  |  |
| Note that HTTP/1.0 caches might not implement Cache-Control and |  | Note that HTTP/1.0 caches might not implement Cache-Control and |
| might only implement Pragma: no-cache (see Section 16.4). |  | might only implement Pragma: no-cache (see Section 3.4). |
| Cache directives MUST be passed through by a proxy or gateway |  | Cache directives MUST be passed through by a proxy or gateway |
| application, regardless of their significance to that application, |  | application, regardless of their significance to that application, |
| since the directives might be applicable to all recipients along the |  | since the directives might be applicable to all recipients along the |
| request/response chain. It is not possible to specify a cache- |  | request/response chain. It is not possible to target a directive to |
| directive for a specific cache. |  | a specific cache. |
| Cache-Control = "Cache-Control" ":" OWS Cache-Control-v |  | Cache-Control = "Cache-Control" ":" OWS Cache-Control-v |
| Cache-Control-v = 1#cache-directive |  | Cache-Control-v = 1#cache-directive |
| cache-directive = cache-request-directive |  | cache-directive = cache-request-directive |
| / cache-response-directive |  | / cache-response-directive |
| cache-request-directive = |  |  |
| "no-cache" ; Section 16.2.1 |  |  |
| / "no-store" ; Section 16.2.2 |  |  |
| / "max-age" "=" delta-seconds ; Section 16.2.3, 16.2.4 |  |  |
| / "max-stale" [ "=" delta-seconds ] ; Section 16.2.3 |  |  |
| / "min-fresh" "=" delta-seconds ; Section 16.2.3 |  |  |
| / "no-transform" ; Section 16.2.5 |  |  |
| / "only-if-cached" ; Section 16.2.4 |  |  |
| / cache-extension ; Section 16.2.6 |  |  |
| cache-response-directive = |  |  |
| "public" ; Section 16.2.1 |  |  |
| / "private" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 |  |  |
| / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 |  |  |
| / "no-store" ; Section 16.2.2 |  |  |
| / "no-transform" ; Section 16.2.5 |  |  |
| / "must-revalidate" ; Section 16.2.4 |  |  |
| / "proxy-revalidate" ; Section 16.2.4 |  |  |
| / "max-age" "=" delta-seconds ; Section 16.2.3 |  |  |
| / "s-maxage" "=" delta-seconds ; Section 16.2.3 |  |  |
| / cache-extension ; Section 16.2.6 |  |  |
| cache-extension = token [ "=" ( token / quoted-string ) ] |  | cache-extension = token [ "=" ( token / quoted-string ) ] |
| When a directive appears without any 1#field-name parameter, the |  | 3.2.1. Request Cache-Control Directives |
| directive applies to the entire request or response. When such a |  |  |
| directive appears with a 1#field-name parameter, it applies only to |  |  |
| the named field or fields, and not to the rest of the request or |  |  |
| response. This mechanism supports extensibility; implementations of |  |  |
| future versions of HTTP might apply these directives to header fields |  |  |
| not defined in HTTP/1.1. |  |  |
| The cache-control directives can be broken down into these general |  |  |
| categories: |  |  |
| o Restrictions on what are cacheable; these may only be imposed by |  |  |
| the origin server. |  |  |
| o Restrictions on what may be stored by a cache; these may be |  |  |
| imposed by either the origin server or the user agent. |  |  |
| o Modifications of the basic expiration mechanism; these may be |  |  |
| imposed by either the origin server or the user agent. |  |  |
| o Controls over cache revalidation and reload; these may only be |  |  |
| imposed by a user agent. |  |  |
| o Control over transformation of entities. |  |  |
| o Extensions to the caching system. |  |  |
| 16.2.1. What is Cacheable |  |  |
| By default, a response is cacheable if the requirements of the |  |  |
| request method, request header fields, and the response status |  |  |
| indicate that it is cacheable. Section 6 summarizes these defaults |  |  |
| for cacheability. The following Cache-Control response directives |  |  |
| allow an origin server to override the default cacheability of a |  |  |
| response: |  |  |
| public |  |  |
| Indicates that the response MAY be cached by any cache, even if it |  |  |
| would normally be non-cacheable or cacheable only within a non- |  |  |
| shared cache. (See also Authorization, Section 4.1 of [Part7], |  |  |
| for additional details.) |  |  |
| private |  |  |
| Indicates that all or part of the response message is intended for |  |  |
| a single user and MUST NOT be cached by a shared cache. This |  |  |
| allows an origin server to state that the specified parts of the |  |  |
| response are intended for only one user and are not a valid |  |  |
| response for requests by other users. A private (non-shared) |  |  |
| cache MAY cache the response. |  |  |
| Note: This usage of the word private only controls where the |  | cache-request-directive = |
| response may be cached, and cannot ensure the privacy of the |  | "no-cache" |
| message content. |  | / "no-store" |
|  |  | / "max-age" "=" delta-seconds |
|  |  | / "max-stale" [ "=" delta-seconds ] |
|  |  | / "min-fresh" "=" delta-seconds |
|  |  | / "no-transform" |
|  |  | / "only-if-cached" |
|  |  | / cache-extension |
| no-cache |  | no-cache |
| If the no-cache directive does not specify a field-name, then a |  | The no-cache request directive indicates that a stored response |
| cache MUST NOT use the response to satisfy a subsequent request |  | MUST NOT be used to satisfy the request without successful |
| without successful revalidation with the origin server. This |  | validation on the origin server. |
| allows an origin server to prevent caching even by caches that |  |  |
| have been configured to return stale responses to client requests. |  |  |
| If the no-cache directive does specify one or more field-names, |  |  |
| then a cache MAY use the response to satisfy a subsequent request, |  |  |
| subject to any other restrictions on caching. However, the |  |  |
| specified field-name(s) MUST NOT be sent in the response to a |  |  |
| subsequent request without successful revalidation with the origin |  |  |
| server. This allows an origin server to prevent the re-use of |  |  |
| certain header fields in a response, while still allowing caching |  |  |
| of the rest of the response. |  |  |
| Note: Most HTTP/1.0 caches will not recognize or obey this |  |  |
| directive. |  |  |
| 16.2.2. What May be Stored by Caches |  |  |
| no-store |  | no-store |
| The purpose of the no-store directive is to prevent the |  | The no-store request directive indicates that a cache MUST NOT |
| inadvertent release or retention of sensitive information (for |  | store any part of either this request or any response to it. This |
| example, on backup tapes). The no-store directive applies to the |  | directive applies to both non-shared and shared caches. "MUST NOT |
| entire message, and MAY be sent either in a response or in a |  | store" in this context means that the cache MUST NOT intentionally |
| request. If sent in a request, a cache MUST NOT store any part of |  | store the information in non-volatile storage, and MUST make a |
| either this request or any response to it. If sent in a response, |  | best-effort attempt to remove the information from volatile |
| a cache MUST NOT store any part of either this response or the |  | storage as promptly as possible after forwarding it. |
| request that elicited it. This directive applies to both non- |  |  |
| shared and shared caches. "MUST NOT store" in this context means |  |  |
| that the cache MUST NOT intentionally store the information in |  |  |
| non-volatile storage, and MUST make a best-effort attempt to |  |  |
| remove the information from volatile storage as promptly as |  |  |
| possible after forwarding it. |  |  |
| Even when this directive is associated with a response, users |  |  |
| might explicitly store such a response outside of the caching |  |  |
| system (e.g., with a "Save As" dialog). History buffers MAY store |  |  |
| such responses as part of their normal operation. |  |  |
| The purpose of this directive is to meet the stated requirements |  |  |
| of certain users and service authors who are concerned about |  |  |
| accidental releases of information via unanticipated accesses to |  |  |
| cache data structures. While the use of this directive might |  |  |
| improve privacy in some cases, we caution that it is NOT in any |  |  |
| way a reliable or sufficient mechanism for ensuring privacy. In |  |  |
| particular, malicious or compromised caches might not recognize or |  |  |
| obey this directive, and communications networks might be |  |  |
| vulnerable to eavesdropping. |  |  |
| 16.2.3. Modifications of the Basic Expiration Mechanism |  |  |
| The expiration time of an entity MAY be specified by the origin |  |  |
| server using the Expires header (see Section 16.3). Alternatively, |  |  |
| it MAY be specified using the max-age directive in a response. When |  |  |
| the max-age cache-control directive is present in a cached response, |  |  |
| the response is stale if its current age is greater than the age |  |  |
| value given (in seconds) at the time of a new request for that |  |  |
| resource. The max-age directive on a response implies that the |  |  |
| response is cacheable (i.e., "public") unless some other, more |  |  |
| restrictive cache directive is also present. |  |  |
| If a response includes both an Expires header and a max-age |  |  |
| directive, the max-age directive overrides the Expires header, even |  |  |
| if the Expires header is more restrictive. This rule allows an |  |  |
| origin server to provide, for a given response, a longer expiration |  |  |
| time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This |  |  |
| might be useful if certain HTTP/1.0 caches improperly calculate ages |  |  |
| or expiration times, perhaps due to desynchronized clocks. |  |  |
| Many HTTP/1.0 cache implementations will treat an Expires value that |  |  |
| is less than or equal to the response Date value as being equivalent |  |  |
| to the Cache-Control response directive "no-cache". If an HTTP/1.1 |  |  |
| cache receives such a response, and the response does not include a |  |  |
| Cache-Control header field, it SHOULD consider the response to be |  |  |
| non-cacheable in order to retain compatibility with HTTP/1.0 servers. |  |  |
| Note: An origin server might wish to use a relatively new HTTP |  |  |
| cache control feature, such as the "private" directive, on a |  |  |
| network including older caches that do not understand that |  |  |
| feature. The origin server will need to combine the new feature |  |  |
| with an Expires field whose value is less than or equal to the |  |  |
| Date value. This will prevent older caches from improperly |  |  |
| caching the response. |  |  |
| s-maxage |  |  |
| If a response includes an s-maxage directive, then for a shared |  | This directive is NOT a reliable or sufficient mechanism for |
| cache (but not for a private cache), the maximum age specified by |  | ensuring privacy. In particular, malicious or compromised caches |
| this directive overrides the maximum age specified by either the |  | might not recognize or obey this directive, and communications |
| max-age directive or the Expires header. The s-maxage directive |  | networks may be vulnerable to eavesdropping. |
| also implies the semantics of the proxy-revalidate directive (see |  |  |
| Section 16.2.4), i.e., that the shared cache must not use the |  |  |
| entry after it becomes stale to respond to a subsequent request |  |  |
| without first revalidating it with the origin server. The |  |  |
| s-maxage directive is always ignored by a private cache. |  |  |
| Note that most older caches, not compliant with this specification, |  | max-age |
| do not implement any cache-control directives. An origin server |  |  |
| wishing to use a cache-control directive that restricts, but does not |  |  |
| prevent, caching by an HTTP/1.1-compliant cache MAY exploit the |  |  |
| requirement that the max-age directive overrides the Expires header, |  |  |
| and the fact that pre-HTTP/1.1-compliant caches do not observe the |  |  |
| max-age directive. |  |  |
| Other directives allow a user agent to modify the basic expiration |  | The max-age request directive indicates that the client is willing |
| mechanism. These directives MAY be specified on a request: |  | to accept a response whose age is no greater than the specified |
|  |  | time in seconds. Unless max-stale directive is also included, the |
|  |  | client is not willing to accept a stale response. |
| max-age |  | max-stale |
| Indicates that the client is willing to accept a response whose |  | The max-stale request directive indicates that the client is |
| age is no greater than the specified time in seconds. Unless max- |  | willing to accept a response that has exceeded its expiration |
| stale directive is also included, the client is not willing to |  | time. If max-stale is assigned a value, then the client is |
| accept a stale response. |  | willing to accept a response that has exceeded its expiration time |
|  |  | by no more than the specified number of seconds. If no value is |
|  |  | assigned to max-stale, then the client is willing to accept a |
|  |  | stale response of any age. [[anchor15: of any staleness? --mnot]] |
| min-fresh |  | min-fresh |
| Indicates that the client is willing to accept a response whose |  | The min-fresh request directive indicates that the client is |
| freshness lifetime is no less than its current age plus the |  | willing to accept a response whose freshness lifetime is no less |
| specified time in seconds. That is, the client wants a response |  | than its current age plus the specified time in seconds. That is, |
| that will still be fresh for at least the specified number of |  | the client wants a response that will still be fresh for at least |
| seconds. |  | the specified number of seconds. |
| max-stale |  |  |
| Indicates that the client is willing to accept a response that has |  | no-transform |
| exceeded its expiration time. If max-stale is assigned a value, |  |  |
| then the client is willing to accept a response that has exceeded |  |  |
| its expiration time by no more than the specified number of |  |  |
| seconds. If no value is assigned to max-stale, then the client is |  |  |
| willing to accept a stale response of any age. |  |  |
| If a cache returns a stale response, either because of a max-stale |  | The no-transform request directive indicates that an intermediate |
| directive on a request, or because the cache is configured to |  | cache or proxy MUST NOT change the Content-Encoding, Content-Range |
| override the expiration time of a response, the cache MUST attach a |  | or Content-Type request headers, nor the request entity-body. |
| Warning header to the stale response, using Warning 110 (Response is |  |  |
| stale). |  |  |
| A cache MAY be configured to return stale responses without |  | only-if-cached |
| validation, but only if this does not conflict with any "MUST"-level |  |  |
| requirements concerning cache validation (e.g., a "must-revalidate" |  |  |
| cache-control directive). |  |  |
| If both the new request and the cached entry include "max-age" |  | The only-if-cached request directive indicates that the client |
| directives, then the lesser of the two values is used for determining |  | only wishes to return a stored response. If it receives this |
| the freshness of the cached entry for that request. |  | directive, a cache SHOULD either respond using a stored response |
|  |  | that is consistent with the other constraints of the request, or |
|  |  | respond with a 504 (Gateway Timeout) status. If a group of caches |
|  |  | is being operated as a unified system with good internal |
|  |  | connectivity, such a request MAY be forwarded within that group of |
|  |  | caches. |
| 16.2.4. Cache Revalidation and Reload Controls |  | 3.2.2. Response Cache-Control Directives |
| Sometimes a user agent might want or need to insist that a cache |  | cache-response-directive = |
| revalidate its cache entry with the origin server (and not just with |  | "public" |
| the next cache along the path to the origin server), or to reload its |  | / "private" [ "=" DQUOTE 1#field-name DQUOTE ] |
| cache entry from the origin server. End-to-end revalidation might be |  | / "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] |
| necessary if either the cache or the origin server has overestimated |  | / "no-store" |
| the expiration time of the cached response. End-to-end reload may be |  | / "no-transform" |
| necessary if the cache entry has become corrupted for some reason. |  | / "must-revalidate" |
|  |  | / "proxy-revalidate" |
|  |  | / "max-age" "=" delta-seconds |
|  |  | / "s-maxage" "=" delta-seconds |
|  |  | / cache-extension |
| End-to-end revalidation may be requested either when the client does |  | public |
| not have its own local cached copy, in which case we call it |  |  |
| "unspecified end-to-end revalidation", or when the client does have a |  |  |
| local cached copy, in which case we call it "specific end-to-end |  |  |
| revalidation." |  |  |
| The client can specify these three kinds of action using Cache- |  | The public response directive indicates that the response MAY be |
| Control request directives: |  | cached, even if it would normally be non-cacheable or cacheable |
|  |  | only within a non-shared cache. (See also Authorization, Section |
|  |  | 3.1 of [Part7], for additional details.) |
| End-to-end reload |  | private |
| The request includes a "no-cache" cache-control directive or, for |  | The private response directive indicates that the response message |
| compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field |  | is intended for a single user and MUST NOT be stored by a shared |
| names MUST NOT be included with the no-cache directive in a |  | cache. A private (non-shared) cache MAY store the response. |
| request. The server MUST NOT use a cached copy when responding to |  |  |
| such a request. |  |  |
| Specific end-to-end revalidation |  | If the private response directive specifies one or more field- |
|  |  | names, this requirement is limited to the field-values associated |
|  |  | with the listed response headers. That is, the specified field- |
|  |  | names(s) MUST NOT be stored by a shared cache, whereas the |
|  |  | remainder of the response message MAY be. |
| The request includes a "max-age=0" cache-control directive, which |  | Note: This usage of the word private only controls where the |
| forces each cache along the path to the origin server to |  | response may be stored, and cannot ensure the privacy of the |
| revalidate its own entry, if any, with the next cache or server. |  | message content. |
| The initial request includes a cache-validating conditional with |  |  |
| the client's current validator. |  |  |
| Unspecified end-to-end revalidation |  | no-cache |
| The request includes "max-age=0" cache-control directive, which |  | The no-cache response directive indicates that the response MUST |
| forces each cache along the path to the origin server to |  | NOT be used to satisfy a subsequent request without successful |
| revalidate its own entry, if any, with the next cache or server. |  | validation on the origin server. This allows an origin server to |
| The initial request does not include a cache-validating |  | prevent caching even by caches that have been configured to return |
| conditional; the first cache along the path (if any) that holds a |  | stale responses. |
| cache entry for this resource includes a cache-validating |  |  |
| conditional with its current validator. |  |  |
| max-age |  | If the no-cache response directive specifies one or more field- |
| When an intermediate cache is forced, by means of a max-age=0 |  | names, this requirement is limited to the field-values assosicated |
| directive, to revalidate its own cache entry, and the client has |  | with the listed response headers. That is, the specified field- |
| supplied its own validator in the request, the supplied validator |  | name(s) MUST NOT be sent in the response to a subsequent request |
| might differ from the validator currently stored with the cache |  | without successful validation on the origin server. This allows |
| entry. In this case, the cache MAY use either validator in making |  | an origin server to prevent the re-use of certain header fields in |
| its own request without affecting semantic transparency. |  | a response, while still allowing caching of the rest of the |
|  |  | response. |
| However, the choice of validator might affect performance. The |  | Note: Most HTTP/1.0 caches will not recognize or obey this |
| best approach is for the intermediate cache to use its own |  | directive. |
| validator when making its request. If the server replies with 304 |  |  |
| (Not Modified), then the cache can return its now validated copy |  |  |
| to the client with a 200 (OK) response. If the server replies |  |  |
| with a new entity and cache validator, however, the intermediate |  |  |
| cache can compare the returned validator with the one provided in |  |  |
| the client's request, using the strong comparison function. If |  |  |
| the client's validator is equal to the origin server's, then the |  |  |
| intermediate cache simply returns 304 (Not Modified). Otherwise, |  |  |
| it returns the new entity with a 200 (OK) response. |  |  |
| If a request includes the no-cache directive, it SHOULD NOT |  | no-store |
| include min-fresh, max-stale, or max-age. |  |  |
| only-if-cached |  | The no-store response directive indicates that a cache MUST NOT |
|  |  | store any part of either the immediate request or response. This |
|  |  | directive applies to both non-shared and shared caches. "MUST NOT |
|  |  | store" in this context means that the cache MUST NOT intentionally |
|  |  | store the information in non-volatile storage, and MUST make a |
|  |  | best-effort attempt to remove the information from volatile |
|  |  | storage as promptly as possible after forwarding it. |
| In some cases, such as times of extremely poor network |  | This directive is NOT a reliable or sufficient mechanism for |
| connectivity, a client may want a cache to return only those |  | ensuring privacy. In particular, malicious or compromised caches |
| responses that it currently has stored, and not to reload or |  | might not recognize or obey this directive, and communications |
| revalidate with the origin server. To do this, the client may |  | networks may be vulnerable to eavesdropping. |
| include the only-if-cached directive in a request. If it receives |  |  |
| this directive, a cache SHOULD either respond using a cached entry |  |  |
| that is consistent with the other constraints of the request, or |  |  |
| respond with a 504 (Gateway Timeout) status. However, if a group |  |  |
| of caches is being operated as a unified system with good internal |  |  |
| connectivity, such a request MAY be forwarded within that group of |  |  |
| caches. |  |  |
| must-revalidate |  | must-revalidate |
| Because a cache MAY be configured to ignore a server's specified |  | The must-revalidate response directive indicates that once it has |
| expiration time, and because a client request MAY include a max- |  | become stale, the response MUST NOT be used to satisfy subsequent |
| stale directive (which has a similar effect), the protocol also |  | requests without successful validation on the origin server. |
| includes a mechanism for the origin server to require revalidation |  |  |
| of a cache entry on any subsequent use. When the must-revalidate |  |  |
| directive is present in a response received by a cache, that cache |  |  |
| MUST NOT use the entry after it becomes stale to respond to a |  |  |
| subsequent request without first revalidating it with the origin |  |  |
| server. (I.e., the cache MUST do an end-to-end revalidation every |  |  |
| time, if, based solely on the origin server's Expires or max-age |  |  |
| value, the cached response is stale.) |  |  |
| The must-revalidate directive is necessary to support reliable |  | The must-revalidate directive is necessary to support reliable |
| operation for certain protocol features. In all circumstances an |  | operation for certain protocol features. In all circumstances an |
| HTTP/1.1 cache MUST obey the must-revalidate directive; in |  | HTTP/1.1 cache MUST obey the must-revalidate directive; in |
| particular, if the cache cannot reach the origin server for any |  | particular, if the cache cannot reach the origin server for any |
| reason, it MUST generate a 504 (Gateway Timeout) response. |  | reason, it MUST generate a 504 (Gateway Timeout) response. |
| Servers SHOULD send the must-revalidate directive if and only if |  | Servers SHOULD send the must-revalidate directive if and only if |
| failure to revalidate a request on the entity could result in |  | failure to validate a request on the entity could result in |
| incorrect operation, such as a silently unexecuted financial |  | incorrect operation, such as a silently unexecuted financial |
| transaction. Recipients MUST NOT take any automated action that |  | transaction. |
| violates this directive, and MUST NOT automatically provide an |  |  |
| unvalidated copy of the entity if revalidation fails. |  |  |
| Although this is not recommended, user agents operating under |  |  |
| severe connectivity constraints MAY violate this directive but, if |  |  |
| so, MUST explicitly warn the user that an unvalidated response has |  |  |
| been provided. The warning MUST be provided on each unvalidated |  |  |
| access, and SHOULD require explicit user confirmation. |  |  |
| proxy-revalidate |  | proxy-revalidate |
| The proxy-revalidate directive has the same meaning as the must- |  | The proxy-revalidate response directive has the same meaning as |
| revalidate directive, except that it does not apply to non-shared |  | the must-revalidate response directive, except that it does not |
| user agent caches. It can be used on a response to an |  | apply to non-shared caches. |
| authenticated request to permit the user's cache to store and |  |  |
| later return the response without needing to revalidate it (since |  |  |
| it has already been authenticated once by that user), while still |  |  |
| requiring proxies that service many users to revalidate each time |  |  |
| (in order to make sure that each user has been authenticated). |  |  |
| Note that such authenticated responses also need the public cache |  |  |
| control directive in order to allow them to be cached at all. |  |  |
| 16.2.5. No-Transform Directive |  | max-age |
|  |  | The max-age response directive indicates that response is to be |
|  |  | considered stale after its age is greater than the specified |
|  |  | number of seconds. |
| no-transform |  | s-maxage |
| Implementors of intermediate caches (proxies) have found it useful |  | The s-maxage response directive indicates that, in shared caches, |
| to convert the media type of certain entity bodies. A non- |  | the maximum age specified by this directive overrides the maximum |
| transparent proxy might, for example, convert between image |  | age specified by either the max-age directive or the Expires |
| formats in order to save cache space or to reduce the amount of |  | header. The s-maxage directive also implies the semantics of the |
| traffic on a slow link. |  | proxy-revalidate response directive. |
| Serious operational problems occur, however, when these |  | no-transform |
| transformations are applied to entity bodies intended for certain |  |  |
| kinds of applications. For example, applications for medical |  |  |
| imaging, scientific data analysis and those using end-to-end |  |  |
| authentication, all depend on receiving an entity body that is bit |  |  |
| for bit identical to the original entity-body. |  |  |
| Therefore, if a message includes the no-transform directive, an |  | The no-transform response directive indicates that an intermediate |
| intermediate cache or proxy MUST NOT change those headers that are |  | cache or proxy MUST NOT change the Content-Encoding, Content-Range |
| listed in Section 7.2 as being subject to the no-transform |  | or Content-Type response headers, nor the response entity-body. |
| directive. This implies that the cache or proxy MUST NOT change |  |  |
| any aspect of the entity-body that is specified by these headers, |  |  |
| including the value of the entity-body itself. |  |  |
| 16.2.6. Cache Control Extensions |  | 3.2.3. Cache Control Extensions |
| The Cache-Control header field can be extended through the use of one |  | The Cache-Control header field can be extended through the use of one |
| or more cache-extension tokens, each with an optional assigned value. |  | or more cache-extension tokens, each with an optional value. |
| Informational extensions (those which do not require a change in |  | Informational extensions (those that do not require a change in cache |
| cache behavior) MAY be added without changing the semantics of other |  | behavior) can be added without changing the semantics of other |
| directives. Behavioral extensions are designed to work by acting as |  | directives. Behavioral extensions are designed to work by acting as |
| modifiers to the existing base of cache directives. Both the new |  | modifiers to the existing base of cache directives. Both the new |
| directive and the standard directive are supplied, such that |  | directive and the standard directive are supplied, such that |
| applications which do not understand the new directive will default |  | applications that do not understand the new directive will default to |
| to the behavior specified by the standard directive, and those that |  | the behavior specified by the standard directive, and those that |
| understand the new directive will recognize it as modifying the |  | understand the new directive will recognize it as modifying the |
| requirements associated with the standard directive. In this way, |  | requirements associated with the standard directive. In this way, |
| extensions to the cache-control directives can be made without |  | extensions to the cache-control directives can be made without |
| requiring changes to the base protocol. |  | requiring changes to the base protocol. |
| This extension mechanism depends on an HTTP cache obeying all of the |  | This extension mechanism depends on an HTTP cache obeying all of the |
| cache-control directives defined for its native HTTP-version, obeying |  | cache-control directives defined for its native HTTP-version, obeying |
| certain extensions, and ignoring all directives that it does not |  | certain extensions, and ignoring all directives that it does not |
| understand. |  | understand. |
| For example, consider a hypothetical new response directive called |  | For example, consider a hypothetical new response directive called |
| community which acts as a modifier to the private directive. We |  | "community" that acts as a modifier to the private directive. We |
| define this new directive to mean that, in addition to any non-shared |  | define this new directive to mean that, in addition to any non-shared |
| cache, any cache which is shared only by members of the community |  | cache, any cache that is shared only by members of the community |
| named within its value may cache the response. An origin server |  | named within its value may cache the response. An origin server |
| wishing to allow the UCI community to use an otherwise private |  | wishing to allow the UCI community to use an otherwise private |
| response in their shared cache(s) could do so by including |  | response in their shared cache(s) could do so by including |
| Cache-Control: private, community="UCI" |  | Cache-Control: private, community="UCI" |
| A cache seeing this header field will act correctly even if the cache |  | A cache seeing this header field will act correctly even if the cache |
| does not understand the community cache-extension, since it will also |  | does not understand the community cache-extension, since it will also |
| see and understand the private directive and thus default to the safe |  | see and understand the private directive and thus default to the safe |
| behavior. |  | behavior. |
| Unrecognized cache-directives MUST be ignored; it is assumed that any |  | Unrecognized cache directives MUST be ignored; it is assumed that any |
| cache-directive likely to be unrecognized by an HTTP/1.1 cache will |  | cache directive likely to be unrecognized by an HTTP/1.1 cache will |
| be combined with standard directives (or the response's default |  | be combined with standard directives (or the response's default |
| cacheability) such that the cache behavior will remain minimally |  | cacheability) such that the cache behavior will remain minimally |
| correct even if the cache does not understand the extension(s). |  | correct even if the cache does not understand the extension(s). |
| 16.3. Expires |  | 3.3. Expires |
| The Expires entity-header field gives the date/time after which the |  | The entity-header field "Expires" gives the date/time after which the |
| response is considered stale. A stale cache entry may not normally |  | response is considered stale. See Section 2.3 for further discussion |
| be returned by a cache (either a proxy cache or a user agent cache) |  | of the freshness model. |
| unless it is first validated with the origin server (or with an |  |  |
| intermediate cache that has a fresh copy of the entity). See |  |  |
| Section 4 for further discussion of the expiration model. |  |  |
| The presence of an Expires field does not imply that the original |  | The presence of an Expires field does not imply that the original |
| resource will change or cease to exist at, before, or after that |  | resource will change or cease to exist at, before, or after that |
| time. |  | time. |
| The format is an absolute date and time as defined by HTTP-date in |  | The field-value is an absolute date and time as defined by HTTP-date |
| Section 3.3.1 of [Part1]; it MUST be sent in rfc1123-date format. |  | in Section 3.2.1 of [Part1]; it MUST be sent in rfc1123-date format. |
| Expires = "Expires" ":" OWS Expires-v |  | Expires = "Expires" ":" OWS Expires-v |
| Expires-v = HTTP-date |  | Expires-v = HTTP-date |
| An example of its use is |  | For example |
| Expires: Thu, 01 Dec 1994 16:00:00 GMT |  | Expires: Thu, 01 Dec 1994 16:00:00 GMT |
| Note: if a response includes a Cache-Control field with the max- |  | Note: if a response includes a Cache-Control field with the max- |
| age directive (see Section 16.2.3), that directive overrides the |  | age directive (see Section 3.2.2), that directive overrides the |
| Expires field. |  | Expires field. Likewise, the s-maxage directive overrides Expires |
|  |  | in shared caches. |
|  |  | HTTP/1.1 servers SHOULD NOT send Expires dates more than one year in |
|  |  | the future. |
| HTTP/1.1 clients and caches MUST treat other invalid date formats, |  | HTTP/1.1 clients and caches MUST treat other invalid date formats, |
| especially including the value "0", as in the past (i.e., "already |  | especially including the value "0", as in the past (i.e., "already |
| expired"). |  | expired"). |
| To mark a response as "already expired," an origin server sends an |  | 3.4. Pragma |
| Expires date that is equal to the Date header value. (See the rules |  |  |
| for expiration calculations in Section 4.4.) |  |  |
| To mark a response as "never expires," an origin server sends an |  |  |
| Expires date approximately one year from the time the response is |  |  |
| sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one |  |  |
| year in the future. |  |  |
| The presence of an Expires header field with a date value of some |  |  |
| time in the future on a response that otherwise would by default be |  |  |
| non-cacheable indicates that the response is cacheable, unless |  |  |
| indicated otherwise by a Cache-Control header field (Section 16.2). |  |  |
| 16.4. Pragma |  |  |
| The general-header field "Pragma" is used to include implementation- |  | The general-header field "Pragma" is used to include implementation- |
| specific directives that might apply to any recipient along the |  | specific directives that might apply to any recipient along the |
| request/response chain. All pragma directives specify optional |  | request/response chain. All pragma directives specify optional |
| behavior from the viewpoint of the protocol; however, some systems |  | behavior from the viewpoint of the protocol; however, some systems |
| MAY require that behavior be consistent with the directives. |  | MAY require that behavior be consistent with the directives. |
| Pragma = "Pragma" ":" OWS Pragma-v |  | Pragma = "Pragma" ":" OWS Pragma-v |
| Pragma-v = 1#pragma-directive |  | Pragma-v = 1#pragma-directive |
| pragma-directive = "no-cache" / extension-pragma |  | pragma-directive = "no-cache" / extension-pragma |
| extension-pragma = token [ "=" ( token / quoted-string ) ] |  | extension-pragma = token [ "=" ( token / quoted-string ) ] |
| When the no-cache directive is present in a request message, an |  | When the no-cache directive is present in a request message, an |
| application SHOULD forward the request toward the origin server even |  | application SHOULD forward the request toward the origin server even |
| if it has a cached copy of what is being requested. This pragma |  | if it has a cached copy of what is being requested. This pragma |
| directive has the same semantics as the no-cache cache-directive (see |  | directive has the same semantics as the no-cache response directive |
| Section 16.2) and is defined here for backward compatibility with |  | (see Section 3.2.2) and is defined here for backward compatibility |
| HTTP/1.0. Clients SHOULD include both header fields when a no-cache |  | with HTTP/1.0. Clients SHOULD include both header fields when a no- |
| request is sent to a server not known to be HTTP/1.1 compliant. |  | cache request is sent to a server not known to be HTTP/1.1 compliant. |
| Pragma directives MUST be passed through by a proxy or gateway |  |  |
| application, regardless of their significance to that application, |  |  |
| since the directives might be applicable to all recipients along the |  |  |
| request/response chain. It is not possible to specify a pragma for a |  |  |
| specific recipient; however, any pragma directive not relevant to a |  |  |
| recipient SHOULD be ignored by that recipient. |  |  |
| HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had |  | HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had |
| sent "Cache-Control: no-cache". No new Pragma directives will be |  | sent "Cache-Control: no-cache". |
| defined in HTTP. |  |  |
| Note: because the meaning of "Pragma: no-cache" as a response- |  | Note: because the meaning of "Pragma: no-cache" as a response- |
| header field is not actually specified, it does not provide a |  | header field is not actually specified, it does not provide a |
| reliable replacement for "Cache-Control: no-cache" in a response. |  | reliable replacement for "Cache-Control: no-cache" in a response. |
| 16.5. Vary |  | This mechanism is deprecated; no new Pragma directives will be |
|  |  | defined in HTTP. |
|  |  | 3.5. Vary |
| The "Vary" response-header field's value indicates the set of |  | The "Vary" response-header field's value indicates the set of |
| request-header fields that fully determines, while the response is |  | request-header fields that determines, while the response is fresh, |
| fresh, whether a cache is permitted to use the response to reply to a |  | whether a cache is permitted to use the response to reply to a |
| subsequent request without revalidation. For uncacheable or stale |  | subsequent request without validation; see Section 2.6. |
| responses, the Vary field value advises the user agent about the |  |  |
| criteria that were used to select the representation. A Vary field |  | In uncacheable or stale responses, the Vary field value advises the |
| value of "*" implies that a cache cannot determine from the request |  | user agent about the criteria that were used to select the |
| headers of a subsequent request whether this response is the |  | representation. |
| appropriate representation. See Section 8 for use of the Vary header |  |  |
| field by caches. |  |  |
| Vary = "Vary" ":" OWS Vary-v |  | Vary = "Vary" ":" OWS Vary-v |
| Vary-v = "*" / 1#field-name |  | Vary-v = "*" / 1#field-name |
| An HTTP/1.1 server SHOULD include a Vary header field with any |  | The set of header fields named by the Vary field value is known as |
| cacheable response that is subject to server-driven negotiation. |  | the selecting request-headers. |
| Doing so allows a cache to properly interpret future requests on that |  |  |
| resource and informs the user agent about the presence of negotiation |  | Servers SHOULD include a Vary header field with any cacheable |
| on that resource. A server MAY include a Vary header field with a |  | response that is subject to server-driven negotiation. Doing so |
| non-cacheable response that is subject to server-driven negotiation, |  | allows a cache to properly interpret future requests on that resource |
|  |  | and informs the user agent about the presence of negotiation on that |
|  |  | resource. A server MAY include a Vary header field with a non- |
|  |  | cacheable response that is subject to server-driven negotiation, |
| since this might provide the user agent with useful information about |  | since this might provide the user agent with useful information about |
| the dimensions over which the response varies at the time of the |  | the dimensions over which the response varies at the time of the |
| response. |  | response. |
| A Vary field value consisting of a list of field-names signals that |  | A Vary field value of "*" signals that unspecified parameters not |
| the representation selected for the response is based on a selection |  | limited to the request-headers (e.g., the network address of the |
| algorithm which considers ONLY the listed request-header field values |  | client), play a role in the selection of the response representation; |
| in selecting the most appropriate representation. A cache MAY assume |  | therefore, a cache cannot determine whether this response is |
| that the same selection will be made for future requests with the |  | appropriate. The "*" value MUST NOT be generated by a proxy server; |
| same values for the listed field names, for the duration of time for |  | it may only be generated by an origin server. |
| which the response is fresh. |  |  |
| The field-names given are not limited to the set of standard request- |  | The field-names given are not limited to the set of standard request- |
| header fields defined by this specification. Field names are case- |  | header fields defined by this specification. Field names are case- |
| insensitive. |  | insensitive. |
| A Vary field value of "*" signals that unspecified parameters not |  | 3.6. Warning |
| limited to the request-headers (e.g., the network address of the |  |  |
| client), play a role in the selection of the response representation. |  |  |
| The "*" value MUST NOT be generated by a proxy server; it may only be |  |  |
| generated by an origin server. |  |  |
| 16.6. Warning |  |  |
| The general-header field "Warning" is used to carry additional |  | The general-header field "Warning" is used to carry additional |
| information about the status or transformation of a message which |  | information about the status or transformation of a message that |
| might not be reflected in the message. This information is typically |  | might not be reflected in the message. This information is typically |
| used to warn about a possible lack of semantic transparency from |  | used to warn about possible incorrectness introduced by caching |
| caching operations or transformations applied to the entity body of |  | operations or transformations applied to the entity body of the |
| the message. |  | message. |
| Warning headers are sent with responses using: |  | Warnings can be used for other purposes, both cache-related and |
|  |  | otherwise. The use of a warning, rather than an error status code, |
|  |  | distinguish these responses from true failures. |
|  |  | Warning headers can in general be applied to any message, however |
|  |  | some warn-codes are specific to caches and can only be applied to |
|  |  | response messages. |
| Warning = "Warning" ":" OWS Warning-v |  | Warning = "Warning" ":" OWS Warning-v |
| Warning-v = 1#warning-value |  | Warning-v = 1#warning-value |
| warning-value = warn-code SP warn-agent SP warn-text |  | warning-value = warn-code SP warn-agent SP warn-text |
| [SP warn-date] |  | [SP warn-date] |
| warn-code = 3DIGIT |  | warn-code = 3DIGIT |
| warn-agent = ( uri-host [ ":" port ] ) / pseudonym |  | warn-agent = ( uri-host [ ":" port ] ) / pseudonym |
| ; the name or pseudonym of the server adding |  | ; the name or pseudonym of the server adding |
| ; the Warning header, for use in debugging |  | ; the Warning header, for use in debugging |
| warn-text = quoted-string |  | warn-text = quoted-string |
| warn-date = DQUOTE HTTP-date DQUOTE |  | warn-date = DQUOTE HTTP-date DQUOTE |
| A response MAY carry more than one Warning header. |  | Multiple warnings can be attached to a response (either by the origin |
|  |  | server or by a cache), including multiple warnings with the same code |
|  |  | number. For example, a server might provide the same warning with |
|  |  | texts in both English and Basque. |
|  |  | When this occurs, the user agent SHOULD inform the user of as many of |
|  |  | them as possible, in the order that they appear in the response. If |
|  |  | it is not possible to inform the user of all of the warnings, the |
|  |  | user agent SHOULD follow these heuristics: |
|  |  | o Warnings that appear early in the response take priority over |
|  |  | those appearing later in the response. |
|  |  | o Warnings in the user's preferred character set take priority over |
|  |  | warnings in other character sets but with identical warn-codes and |
|  |  | warn-agents. |
|  |  | Systems that generate multiple Warning headers SHOULD order them with |
|  |  | this user agent behavior in mind. New Warning headers SHOULD be |
|  |  | added after any existing Warning headers. |
|  |  | Warnings are assigned three digit warn-codes. The first digit |
|  |  | indicates whether the Warning is required to be deleted from a stored |
|  |  | response after validation: |
|  |  | o 1xx Warnings that describe the freshness or validation status of |
|  |  | the response, and so MUST be deleted by caches after validation. |
|  |  | They MUST NOT be generated by a cache except when validating a |
|  |  | cached entry, and MUST NOT be generated by clients. |
|  |  | o 2xx Warnings that describe some aspect of the entity body or |
|  |  | entity headers that is not rectified by a validation (for example, |
|  |  | a lossy compression of the entity bodies) and MUST NOT be deleted |
|  |  | by caches after validation, unless a full response is returned, in |
|  |  | which case they MUST be. |
| The warn-text SHOULD be in a natural language and character set that |  | The warn-text SHOULD be in a natural language and character set that |
| is most likely to be intelligible to the human user receiving the |  | is most likely to be intelligible to the human user receiving the |
| response. This decision MAY be based on any available knowledge, |  | response. This decision can be based on any available knowledge, |
| such as the location of the cache or user, the Accept-Language field |  | such as the location of the cache or user, the Accept-Language field |
| in a request, the Content-Language field in a response, etc. The |  | in a request, the Content-Language field in a response, etc. The |
| default language is English and the default character set is ISO- |  | default language is English and the default character set is ISO- |
| 8859-1 ([ISO-8859-1]). |  | 8859-1 ([ISO-8859-1]). |
| If a character set other than ISO-8859-1 is used, it MUST be encoded |  | If a character set other than ISO-8859-1 is used, it MUST be encoded |
| in the warn-text using the method described in [RFC2047]. |  | in the warn-text using the method described in [RFC2047]. |
| Warning headers can in general be applied to any message, however |  | If an implementation sends a message with one or more Warning headers |
| some specific warn-codes are specific to caches and can only be |  | to a receiver whose version is HTTP/1.0 or lower, then the sender |
| applied to response messages. New Warning headers SHOULD be added |  | MUST include in each warning-value a warn-date that matches the Date |
| after any existing Warning headers. A cache MUST NOT delete any |  | header in the message. |
| Warning header that it received with a message. However, if a cache |  |  |
| successfully validates a cache entry, it SHOULD remove any Warning |  |  |
| headers previously attached to that entry except as specified for |  |  |
| specific Warning codes. It MUST then add any Warning headers |  |  |
| received in the validating response. In other words, Warning headers |  |  |
| are those that would be attached to the most recent relevant |  |  |
| response. |  |  |
| When multiple Warning headers are attached to a response, the user |  |  |
| agent ought to inform the user of as many of them as possible, in the |  |  |
| order that they appear in the response. If it is not possible to |  |  |
| inform the user of all of the warnings, the user agent SHOULD follow |  |  |
| these heuristics: |  |  |
| o Warnings that appear early in the response take priority over |  |  |
| those appearing later in the response. |  |  |
| o Warnings in the user's preferred character set take priority over |  |  |
| warnings in other character sets but with identical warn-codes and |  |  |
| warn-agents. |  |  |
| Systems that generate multiple Warning headers SHOULD order them with |  |  |
| this user agent behavior in mind. |  |  |
| Requirements for the behavior of caches with respect to Warnings are |  | If an implementation receives a message with a warning-value that |
| stated in Section 3.2. |  | includes a warn-date, and that warn-date is different from the Date |
|  |  | value in the response, then that warning-value MUST be deleted from |
|  |  | the message before storing, forwarding, or using it. (preventing the |
|  |  | consequences of naive caching of Warning header fields.) If all of |
|  |  | the warning-values are deleted for this reason, the Warning header |
|  |  | MUST be deleted as well. |
| This is a list of the currently-defined warn-codes, each with a |  | The following warn-codes are defined by this specification, each with |
| recommended warn-text in English, and a description of its meaning. |  | a recommended warn-text in English, and a description of its meaning. |
| 110 Response is stale |  | 110 Response is stale |
| MUST be included whenever the returned response is stale. |  | SHOULD be included whenever the returned response is stale. |
| 111 Revalidation failed |  | 111 Revalidation failed |
| MUST be included if a cache returns a stale response because an |  | SHOULD be included if a cache returns a stale response because an |
| attempt to revalidate the response failed, due to an inability to |  | attempt to validate the response failed, due to an inability to |
| reach the server. |  | reach the server. |
| 112 Disconnected operation |  | 112 Disconnected operation |
| SHOULD be included if the cache is intentionally disconnected from |  | SHOULD be included if the cache is intentionally disconnected from |
| the rest of the network for a period of time. |  | the rest of the network for a period of time. |
| 113 Heuristic expiration |  | 113 Heuristic expiration |
| MUST be included if the cache heuristically chose a freshness |  | SHOULD be included if the cache heuristically chose a freshness |
| lifetime greater than 24 hours and the response's age is greater |  | lifetime greater than 24 hours and the response's age is greater |
| than 24 hours. |  | than 24 hours. |
| 199 Miscellaneous warning |  | 199 Miscellaneous warning |
| The warning text MAY include arbitrary information to be presented |  | The warning text can include arbitrary information to be presented |
| to a human user, or logged. A system receiving this warning MUST |  | to a human user, or logged. A system receiving this warning MUST |
| NOT take any automated action, besides presenting the warning to |  | NOT take any automated action, besides presenting the warning to |
| the user. |  | the user. |
| 214 Transformation applied |  | 214 Transformation applied |
| MUST be added by an intermediate cache or proxy if it applies any |  | MUST be added by an intermediate cache or proxy if it applies any |
| transformation changing the content-coding (as specified in the |  | transformation changing the content-coding (as specified in the |
| Content-Encoding header) or media-type (as specified in the |  | Content-Encoding header) or media-type (as specified in the |
| Content-Type header) of the response, or the entity-body of the |  | Content-Type header) of the response, or the entity-body of the |
| response, unless this Warning code already appears in the |  | response, unless this Warning code already appears in the |
| response. |  | response. |
| 299 Miscellaneous persistent warning |  | 299 Miscellaneous persistent warning |
| The warning text MAY include arbitrary information to be presented |  | The warning text can include arbitrary information to be presented |
| to a human user, or logged. A system receiving this warning MUST |  | to a human user, or logged. A system receiving this warning MUST |
| NOT take any automated action. |  | NOT take any automated action. |
| If an implementation sends a message with one or more Warning headers |  | 4. History Lists |
| whose version is HTTP/1.0 or lower, then the sender MUST include in |  |  |
| each warning-value a warn-date that matches the date in the response. |  |  |
| If an implementation receives a message with a warning-value that |  | User agents often have history mechanisms, such as "Back" buttons and |
| includes a warn-date, and that warn-date is different from the Date |  | history lists, that can be used to redisplay an entity retrieved |
| value in the response, then that warning-value MUST be deleted from |  | earlier in a session. |
| the message before storing, forwarding, or using it. (This prevents |  |  |
| bad consequences of naive caching of Warning header fields.) If all |  |  |
| of the warning-values are deleted for this reason, the Warning header |  |  |
| MUST be deleted as well. |  |  |
| 17. IANA Considerations |  | History mechanisms and caches are different. In particular history |
|  |  | mechanisms SHOULD NOT try to show a correct view of the current state |
|  |  | of a resource. Rather, a history mechanism is meant to show exactly |
|  |  | what the user saw at the time when the resource was retrieved. |
| 17.1. Message Header Registration |  | By default, an expiration time does not apply to history mechanisms. |
|  |  | If the entity is still in storage, a history mechanism SHOULD display |
|  |  | it even if the entity has expired, unless the user has specifically |
|  |  | configured the agent to refresh expired history documents. |
|  |  | This is not to be construed to prohibit the history mechanism from |
|  |  | telling the user that a view might be stale. |
|  |  | Note: if history list mechanisms unnecessarily prevent users from |
|  |  | viewing stale resources, this will tend to force service authors |
|  |  | to avoid using HTTP expiration controls and cache controls when |
|  |  | they would otherwise like to. Service authors may consider it |
|  |  | important that users not be presented with error messages or |
|  |  | warning messages when they use navigation controls (such as BACK) |
|  |  | to view previously fetched resources. Even though sometimes such |
|  |  | resources ought not be cached, or ought to expire quickly, user |
|  |  | interface considerations may force service authors to resort to |
|  |  | other means of preventing caching (e.g. "once-only" URLs) in order |
|  |  | not to suffer the effects of improperly functioning history |
|  |  | mechanisms. |
|  |  | 5. IANA Considerations |
|  |  | 5.1. Message Header Registration |
| The Message Header Registry located at <http://www.iana.org/ |  | The Message Header Registry located at <http://www.iana.org/ |
| assignments/message-headers/message-header-index.html> should be |  | assignments/message-headers/message-header-index.html> should be |
| updated with the permanent registrations below (see [RFC3864]): |  | updated with the permanent registrations below (see [RFC3864]): |
| +-------------------+----------+----------+--------------+ |  | +-------------------+----------+----------+-------------+ |
| | Header Field Name | Protocol | Status | Reference | |  | | Header Field Name | Protocol | Status | Reference | |
| +-------------------+----------+----------+--------------+ |  | +-------------------+----------+----------+-------------+ |
| | Age | http | standard | Section 16.1 | |  | | Age | http | standard | Section 3.1 | |
| | Cache-Control | http | standard | Section 16.2 | |  | | Cache-Control | http | standard | Section 3.2 | |
| | Expires | http | standard | Section 16.3 | |  | | Expires | http | standard | Section 3.3 | |
| | Pragma | http | standard | Section 16.4 | |  | | Pragma | http | standard | Section 3.4 | |
| | Vary | http | standard | Section 16.5 | |  | | Vary | http | standard | Section 3.5 | |
| | Warning | http | standard | Section 16.6 | |  | | Warning | http | standard | Section 3.6 | |
| +-------------------+----------+----------+--------------+ |  | +-------------------+----------+----------+-------------+ |
| The change controller is: "IETF (iesg@ietf.org) - Internet |  | The change controller is: "IETF (iesg@ietf.org) - Internet |
| Engineering Task Force". |  | Engineering Task Force". |
| 18. Security Considerations |  | 6. Security Considerations |
| Caching proxies provide additional potential vulnerabilities, since |  | Caches expose additional potential vulnerabilities, since the |
| the contents of the cache represent an attractive target for |  | contents of the cache represent an attractive target for malicious |
| malicious exploitation. Because cache contents persist after an HTTP |  | exploitation. Because cache contents persist after an HTTP request |
| request is complete, an attack on the cache can reveal information |  | is complete, an attack on the cache can reveal information long after |
| long after a user believes that the information has been removed from |  | a user believes that the information has been removed from the |
| the network. Therefore, cache contents should be protected as |  | network. Therefore, cache contents should be protected as sensitive |
| sensitive information. |  | information. |
| 19. Acknowledgments |  | 7. Acknowledgments |
| Much of the content and presentation of the caching design is due to |  | Much of the content and presentation of the caching design is due to |
| suggestions and comments from individuals including: Shel Kaphan, |  | suggestions and comments from individuals including: Shel Kaphan, |
| Paul Leach, Koen Holtman, David Morris, and Larry Masinter. |  | Paul Leach, Koen Holtman, David Morris, and Larry Masinter. |
| 20. References |  | 8. References |
| 20.1. Normative References |  | 8.1. Normative References |
| [ISO-8859-1] |  | [ISO-8859-1] |
| International Organization for Standardization, |  | International Organization for Standardization, |
| "Information technology -- 8-bit single-byte coded graphic |  | "Information technology -- 8-bit single-byte coded graphic |
| character sets -- Part 1: Latin alphabet No. 1", ISO/ |  | character sets -- Part 1: Latin alphabet No. 1", ISO/ |
| IEC 8859-1:1998, 1998. |  | IEC 8859-1:1998, 1998. |
| [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, |  | and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, |
| and Message Parsing", draft-ietf-httpbis-p1-messaging-05 |  | and Message Parsing", draft-ietf-httpbis-p1-messaging-06 |
| (work in progress), November 2008. |  | (work in progress), March 2009. |
| [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 2: Message |  | and J. Reschke, Ed., "HTTP/1.1, part 2: Message |
| Semantics", draft-ietf-httpbis-p2-semantics-05 (work in |  | Semantics", draft-ietf-httpbis-p2-semantics-06 (work in |
| progress), November 2008. |  | progress), March 2009. |
| [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload |  | and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload |
| and Content Negotiation", draft-ietf-httpbis-p3-payload-05 |  | and Content Negotiation", draft-ietf-httpbis-p3-payload-06 |
| (work in progress), November 2008. |  | (work in progress), March 2009. |
| [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional |  | and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional |
| Requests", draft-ietf-httpbis-p4-conditional-05 (work in |  | Requests", draft-ietf-httpbis-p4-conditional-06 (work in |
| progress), November 2008. |  | progress), March 2009. |
| [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and |  | and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and |
| Partial Responses", draft-ietf-httpbis-p5-range-05 (work |  | Partial Responses", draft-ietf-httpbis-p5-range-06 (work |
| in progress), November 2008. |  | in progress), March 2009. |
| [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |  | [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |  | Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., |
| and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", |  | and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", |
| draft-ietf-httpbis-p7-auth-05 (work in progress), |  | draft-ietf-httpbis-p7-auth-06 (work in progress), |
| November 2008. |  | March 2009. |
| [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) |  | [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) |
| Part Three: Message Header Extensions for Non-ASCII Text", |  | Part Three: Message Header Extensions for Non-ASCII Text", |
| RFC 2047, November 1996. |  | RFC 2047, November 1996. |
| [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |  | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate |
| Requirement Levels", BCP 14, RFC 2119, March 1997. |  | Requirement Levels", BCP 14, RFC 2119, March 1997. |
| 20.2. Informative References |  | [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax |
|  |  | Specifications: ABNF", STD 68, RFC 5234, January 2008. |
|  |  | 8.2. Informative References |
| [RFC1305] Mills, D., "Network Time Protocol (Version 3) |  | [RFC1305] Mills, D., "Network Time Protocol (Version 3) |
| Specification, Implementation", RFC 1305, March 1992. |  | Specification, Implementation", RFC 1305, March 1992. |
| [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |  | [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., |
| Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |  | Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext |
| Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |  | Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration |  | [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration |
| Procedures for Message Header Fields", BCP 90, RFC 3864, |  | Procedures for Message Header Fields", BCP 90, RFC 3864, |
| September 2004. |  | September 2004. |
| Appendix A. Compatibility with Previous Versions |  | Appendix A. Compatibility with Previous Versions |
| A.1. Changes from RFC 2068 |  | A.1. Changes from RFC 2068 |
| A case was missed in the Cache-Control model of HTTP/1.1; s-maxage |  | A case was missed in the Cache-Control model of HTTP/1.1; s-maxage |
| was introduced to add this missing case. (Sections 6, 16.2, 16.2.3) |  | was introduced to add this missing case. (Sections 2.1, 3.2). |
| Transfer-coding and message lengths all interact in ways that |  | Transfer-coding and message lengths all interact in ways that |
| required fixing exactly when chunked encoding is used (to allow for |  | required fixing exactly when chunked encoding is used (to allow for |
| transfer encoding that may not be self delimiting); it was important |  | transfer encoding that may not be self delimiting); it was important |
| to straighten out exactly how message lengths are computed. |  | to straighten out exactly how message lengths are computed. (see also |
| (Section 7.2, see also [Part1], [Part3] and [Part5]) |  | [Part1], [Part3] and [Part5]) [[anchor18: This used to refer to the |
|  |  | text about non-modifiable headers, and will have to be updated later |
|  |  | on. --jre]] |
| Proxies should be able to add Content-Length when appropriate. |  | Proxies should be able to add Content-Length when appropriate. |
| (Section 7.2) |  | [[anchor19: This used to refer to the text about non-modifiable |
|  |  | headers, and will have to be updated later on. --jre]] |
| Range request responses would become very verbose if all meta-data |  | Range request responses would become very verbose if all meta-data |
| were always returned; by allowing the server to only send needed |  | were always returned; by allowing the server to only send needed |
| headers in a 206 response, this problem can be avoided. |  | headers in a 206 response, this problem can be avoided. |
| (Section 7.3) |  | (Section 2.7) |
| The Cache-Control: max-age directive was not properly defined for |  | The Cache-Control: max-age directive was not properly defined for |
| responses. (Section 16.2.3) |  | responses. (Section 3.2.2) |
| Warnings could be cached incorrectly, or not updated appropriately. |  | Warnings could be cached incorrectly, or not updated appropriately. |
| (Section 3.2, 4.4, 7.2, 7.3, 16.2.3, and 16.6) Warning also needed to |  | (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general |
| be a general header, as PUT or other methods may have need for it in |  | header, as PUT or other methods may have need for it in requests. |
| requests. |  |  |
| A.2. Changes from RFC 2616 |  | A.2. Changes from RFC 2616 |
| Clarify denial of service attack avoidance requirement. (Section 12) |  | Clarify denial of service attack avoidance requirement. |
|  |  | (Section 2.5) |
| Appendix B. Change Log (to be removed by RFC Editor before publication) |  | Appendix B. Collected ABNF |
| B.1. Since RFC2616 |  | Age = "Age:" OWS Age-v |
|  |  | Age-v = delta-seconds |
|  |  | Cache-Control = "Cache-Control:" OWS Cache-Control-v |
|  |  | Cache-Control-v = *( "," OWS ) cache-directive *( OWS "," [ OWS |
|  |  | cache-directive ] ) |
|  |  | Expires = "Expires:" OWS Expires-v |
|  |  | Expires-v = HTTP-date |
|  |  | HTTP-date = <HTTP-date, defined in [Part1], Section 3.2.1> |
|  |  | OWS = <OWS, defined in [Part1], Section 1.2.2> |
|  |  | Pragma = "Pragma:" OWS Pragma-v |
|  |  | Pragma-v = *( "," OWS ) pragma-directive *( OWS "," [ OWS |
|  |  | pragma-directive ] ) |
|  |  | Vary = "Vary:" OWS Vary-v |
|  |  | Vary-v = "*" / ( *( "," OWS ) field-name *( OWS "," [ OWS field-name |
|  |  | ] ) ) |
|  |  | Warning = "Warning:" OWS Warning-v |
|  |  | Warning-v = *( "," OWS ) warning-value *( OWS "," [ OWS warning-value |
|  |  | ] ) |
|  |  | cache-directive = cache-request-directive / cache-response-directive |
|  |  | cache-extension = token [ "=" ( token / quoted-string ) ] |
|  |  | cache-request-directive = "no-cache" / "no-store" / ( "max-age=" |
|  |  | delta-seconds ) / ( "max-stale" [ "=" delta-seconds ] ) / ( |
|  |  | "min-fresh=" delta-seconds ) / "no-transform" / "only-if-cached" / |
|  |  | cache-extension |
|  |  | cache-response-directive = "public" / ( "private" [ "=" DQUOTE *( "," |
|  |  | OWS ) field-name *( OWS "," [ OWS field-name ] ) DQUOTE ] ) / ( |
|  |  | "no-cache" [ "=" DQUOTE *( "," OWS ) field-name *( OWS "," [ OWS |
|  |  | field-name ] ) DQUOTE ] ) / "no-store" / "no-transform" / |
|  |  | "must-revalidate" / "proxy-revalidate" / ( "max-age=" delta-seconds |
|  |  | ) / ( "s-maxage=" delta-seconds ) / cache-extension |
|  |  | delta-seconds = 1*DIGIT |
|  |  | extension-pragma = token [ "=" ( token / quoted-string ) ] |
|  |  | field-name = <field-name, defined in [Part1], Section 4.2> |
|  |  | port = <port, defined in [Part1], Section 2.1> |
|  |  | pragma-directive = "no-cache" / extension-pragma |
|  |  | pseudonym = <pseudonym, defined in [Part1], Section 8.9> |
|  |  | quoted-string = <quoted-string, defined in [Part1], Section 1.2.2> |
|  |  | token = <token, defined in [Part1], Section 1.2.2> |
|  |  | uri-host = <uri-host, defined in [Part1], Section 2.1> |
|  |  | warn-agent = ( uri-host [ ":" port ] ) / pseudonym |
|  |  | warn-code = 3DIGIT |
|  |  | warn-date = DQUOTE HTTP-date DQUOTE |
|  |  | warn-text = quoted-string |
|  |  | warning-value = warn-code SP warn-agent SP warn-text [ SP warn-date |
|  |  | ] |
|  |  | ABNF diagnostics: |
|  |  | ; Age defined but not used |
|  |  | ; Cache-Control defined but not used |
|  |  | ; Expires defined but not used |
|  |  | ; Pragma defined but not used |
|  |  | ; Vary defined but not used |
|  |  | ; Warning defined but not used |
|  |  | Appendix C. Change Log (to be removed by RFC Editor before publication) |
|  |  | C.1. Since RFC2616 |
| Extracted relevant partitions from [RFC2616]. |  | Extracted relevant partitions from [RFC2616]. |
| B.2. Since draft-ietf-httpbis-p6-cache-00 |  | C.2. Since draft-ietf-httpbis-p6-cache-00 |
| Closed issues: |  | Closed issues: |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/9>: "Trailer" |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/9>: "Trailer" |
| (<http://purl.org/NET/http-errata#trailer-hop>) |  | (<http://purl.org/NET/http-errata#trailer-hop>) |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/12>: "Invalidation |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/12>: "Invalidation |
| after Update or Delete" |  | after Update or Delete" |
| (<http://purl.org/NET/http-errata#invalidupd>) |  | (<http://purl.org/NET/http-errata#invalidupd>) |
| skipping to change at page 46, line 18 |  | skipping to change at page 34, line 21 |
| to-date references" |  | to-date references" |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/87>: "typo in |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/87>: "typo in |
| 13.2.2" |  | 13.2.2" |
| Other changes: |  | Other changes: |
| o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress |  | o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress |
| on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>) |  | on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>) |
| B.3. Since draft-ietf-httpbis-p6-cache-01 |  | C.3. Since draft-ietf-httpbis-p6-cache-01 |
| Closed issues: |  | Closed issues: |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/82>: "rel_path not |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/82>: "rel_path not |
| used" |  | used" |
| Other changes: |  | Other changes: |
| o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work |  | o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work |
| in progress on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>) |  | in progress on <http://tools.ietf.org/wg/httpbis/trac/ticket/36>) |
| o Add explicit references to BNF syntax and rules imported from |  | o Add explicit references to BNF syntax and rules imported from |
| other parts of the specification. |  | other parts of the specification. |
| B.4. Since draft-ietf-httpbis-p6-cache-02 |  | C.4. Since draft-ietf-httpbis-p6-cache-02 |
| Ongoing work on IANA Message Header Registration |  | Ongoing work on IANA Message Header Registration |
| (<http://tools.ietf.org/wg/httpbis/trac/ticket/40>): |  | (<http://tools.ietf.org/wg/httpbis/trac/ticket/40>): |
| o Reference RFC 3984, and update header registrations for headers |  | o Reference RFC 3984, and update header registrations for headers |
| defined in this document. |  | defined in this document. |
| B.5. Since draft-ietf-httpbis-p6-cache-03 |  | C.5. Since draft-ietf-httpbis-p6-cache-03 |
| Closed issues: |  | Closed issues: |
| o <http://tools.ietf.org/wg/httpbis/trac/ticket/106>: "Vary header |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/106>: "Vary header |
| classification" |  | classification" |
| B.6. Since draft-ietf-httpbis-p6-cache-04 |  | C.6. Since draft-ietf-httpbis-p6-cache-04 |
| Ongoing work on ABNF conversion |  | Ongoing work on ABNF conversion |
| (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>): |  | (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>): |
| o Use "/" instead of "|" for alternatives. |  | o Use "/" instead of "|" for alternatives. |
| o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional |  | o Introduce new ABNF rules for "bad" whitespace ("BWS"), optional |
| whitespace ("OWS") and required whitespace ("RWS"). |  | whitespace ("OWS") and required whitespace ("RWS"). |
| o Rewrite ABNFs to spell out whitespace rules, factor out header |  | o Rewrite ABNFs to spell out whitespace rules, factor out header |
| value format definitions. |  | value format definitions. |
|  |  | C.7. Since draft-ietf-httpbis-p6-cache-05 |
|  |  | This is a total rewrite of this part of the specification. |
|  |  | Affected issues: |
|  |  | o <http://tools.ietf.org/wg/httpbis/trac/ticket/54>: "Definition of |
|  |  | 1xx Warn-Codes" |
|  |  | o <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/60>: "Placement |
|  |  | of 13.5.1 and 13.5.2" |
|  |  | o <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/138>: "The role |
|  |  | of Warning and Semantic Transparency in Caching" |
|  |  | o <http://trac.tools.ietf.org/wg/httpbis/trac/ticket/139>: "Methods |
|  |  | and Caching" |
|  |  | In addition: Final work on ABNF conversion |
|  |  | (<http://tools.ietf.org/wg/httpbis/trac/ticket/36>): |
|  |  | o Add appendix containing collected and expanded ABNF, reorganize |
|  |  | ABNF introduction. |
| Index |  | Index |
| A |  | A |
| age 7 |  | age 6 |
| Age header 27 |  | Age header 17 |
| C |  | C |
| cache 5 |  | cache 5 |
| Cache Directives |  | Cache Directives |
| max-age 32-33 |  | max-age 18, 21 |
| max-stale 32 |  | max-stale 19 |
| min-fresh 32 |  | min-fresh 19 |
| must-revalidate 34 |  | must-revalidate 21 |
| no-cache 29 |  | no-cache 18, 20 |
| no-store 30 |  | no-store 18, 21 |
| no-transform 35 |  | no-transform 19, 22 |
| only-if-cached 34 |  | only-if-cached 19 |
| private 29 |  | private 20 |
| proxy-revalidate 35 |  | proxy-revalidate 21 |
| public 29 |  | public 20 |
| s-maxage 31 |  | s-maxage 22 |
| Cache-Control header 27 |  | Cache-Control header 17 |
| cacheable 6 |  | cacheable 5 |
| E |  | E |
| Expires header 37 |  | Expires header 23 |
| explicit expiration time 7 |  | explicit expiration time 5 |
| F |  | F |
| first-hand 6 |  | first-hand 6 |
| fresh 7 |  | fresh 6 |
| freshness lifetime 7 |  | freshness lifetime 6 |
| G |  | G |
| Grammar |  | Grammar |
| Age 27 |  | Age 17 |
| Age-v 27 |  | Age-v 17 |
| Cache-Control 28 |  | Cache-Control 18 |
| Cache-Control-v 28 |  | Cache-Control-v 18 |
| cache-directive 28 |  | cache-extension 18 |
| cache-extension 28 |  | cache-request-directive 18 |
| cache-request-directive 28 |  | cache-response-directive 20 |
| cache-response-directive 28 |  | delta-seconds 17 |
| delta-seconds 27 |  | Expires 23 |
| Expires 37 |  | Expires-v 23 |
| Expires-v 37 |  | extension-pragma 24 |
| extension-pragma 38 |  | Pragma 24 |
| Pragma 38 |  | pragma-directive 24 |
| pragma-directive 38 |  | Pragma-v 24 |
| Pragma-v 38 |  | Vary 24 |
| Vary 39 |  | Vary-v 24 |
| Vary-v 39 |  | warn-agent 25 |
| warn-agent 40 |  | warn-code 25 |
| warn-code 40 |  | warn-date 25 |
| warn-date 40 |  | warn-text 25 |
| warn-text 40 |  | Warning 25 |
| Warning 40 |  | Warning-v 25 |
| Warning-v 40 |  | warning-value 25 |
| warning-value 40 |  |  |
| H |  | H |
| Headers |  | Headers |
| Age 27 |  | Age 17 |
| Cache-Control 27 |  | Cache-Control 17 |
| Expires 37 |  | Expires 23 |
| Pragma 38 |  | Pragma 23 |
| Vary 38 |  | Vary 24 |
| Warning 39 |  | Warning 25 |
| heuristic expiration time 7 |  | heuristic expiration time 5 |
| M |  | M |
| max-age |  | max-age |
| Cache Directive 32-33 |  | Cache Directive 18, 21 |
| max-stale |  | max-stale |
| Cache Directive 32 |  | Cache Directive 19 |
| min-fresh |  | min-fresh |
| Cache Directive 32 |  | Cache Directive 19 |
| must-revalidate |  | must-revalidate |
| Cache Directive 34 |  | Cache Directive 21 |
| N |  | N |
| no-cache |  | no-cache |
| Cache Directive 29 |  | Cache Directive 18, 20 |
| no-store |  | no-store |
| Cache Directive 30 |  | Cache Directive 18, 21 |
| no-transform |  | no-transform |
| Cache Directive 35 |  | Cache Directive 19, 22 |
| O |  | O |
| only-if-cached |  | only-if-cached |
| Cache Directive 34 |  | Cache Directive 19 |
| P |  | P |
| Pragma header 38 |  | Pragma header 23 |
| private |  | private |
| Cache Directive 29 |  | Cache Directive 20 |
| proxy-revalidate |  | proxy-revalidate |
| Cache Directive 35 |  | Cache Directive 21 |
| public |  | public |
| Cache Directive 29 |  | Cache Directive 20 |
| S |  | S |
| s-maxage |  | s-maxage |
| Cache Directive 31 |  | Cache Directive 22 |
| semantically transparent 5 |  | stale 6 |
| stale 7 |  |  |
| V |  | V |
| validator 7 |  | validator 6 |
| Vary header 38 |  | Vary header 24 |
| W |  | W |
| Warning header 39 |  | Warning header 25 |
| Authors' Addresses |  | Authors' Addresses |
| Roy T. Fielding (editor) |  | Roy T. Fielding (editor) |
| Day Software |  | Day Software |
| 23 Corporate Plaza DR, Suite 280 |  | 23 Corporate Plaza DR, Suite 280 |
| Newport Beach, CA 92660 |  | Newport Beach, CA 92660 |
| USA |  | USA |
| Phone: +1-949-706-5300 |  | Phone: +1-949-706-5300 |
| skipping to change at page 52, line 4 |  | skipping to change at line 1775 |
| Julian F. Reschke (editor) |  | Julian F. Reschke (editor) |
| greenbytes GmbH |  | greenbytes GmbH |
| Hafenweg 16 |  | Hafenweg 16 |
| Muenster, NW 48155 |  | Muenster, NW 48155 |
| Germany |  | Germany |
| Phone: +49 251 2807760 |  | Phone: +49 251 2807760 |
| Fax: +49 251 2807761 |  | Fax: +49 251 2807761 |
| Email: julian.reschke@greenbytes.de |  | Email: julian.reschke@greenbytes.de |
| URI: http://greenbytes.de/tech/webdav/ |  | URI: http://greenbytes.de/tech/webdav/ |
| Full Copyright Statement |  |  |
| Copyright (C) The IETF Trust (2008). |  |  |
| This document is subject to the rights, licenses and restrictions |  |  |
| contained in BCP 78, and except as set forth therein, the authors |  |  |
| retain all their rights. |  |  |
| This document and the information contained herein are provided on an |  |  |
| "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS |  |  |
| OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND |  |  |
| THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS |  |  |
| OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF |  |  |
| THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED |  |  |
| WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. |  |  |
| Intellectual Property |  |  |
| The IETF takes no position regarding the validity or scope of any |  |  |
| Intellectual Property Rights or other rights that might be claimed to |  |  |
| pertain to the implementation or use of the technology described in |  |  |
| this document or the extent to which any license under such rights |  |  |
| might or might not be available; nor does it represent that it has |  |  |
| made any independent effort to identify any such rights. Information |  |  |
| on the procedures with respect to rights in RFC documents can be |  |  |
| found in BCP 78 and BCP 79. |  |  |
| Copies of IPR disclosures made to the IETF Secretariat and any |  |  |
| assurances of licenses to be made available, or the result of an |  |  |
| attempt made to obtain a general license or permission for the use of |  |  |
| such proprietary rights by implementers or users of this |  |  |
| specification can be obtained from the IETF on-line IPR repository at |  |  |
| http://www.ietf.org/ipr. |  |  |
| The IETF invites any interested party to bring to its attention any |  |  |
| copyrights, patents or patent applications, or other proprietary |  |  |
| rights that may cover technology that may be required to implement |  |  |
| this standard. Please address the information to the IETF at |  |  |
| ietf-ipr@ietf.org. |  |  |
End of changes. 254 change blocks.
| 1510 lines changed or deleted |  | 957 lines changed or added |
This html diff was produced by rfcdiff 1.35. The latest version is available from http://tools.ietf.org/tools/rfcdiff/