--- 1/draft-ietf-httpbis-p6-cache-09.txt 2010-07-12 15:13:27.000000000 +0200 +++ 2/draft-ietf-httpbis-p6-cache-10.txt 2010-07-12 15:13:27.000000000 +0200 @@ -1,92 +1,86 @@ HTTPbis Working Group R. Fielding, Ed. Internet-Draft Day Software Obsoletes: 2616 (if approved) J. Gettys -Intended status: Standards Track One Laptop per Child -Expires: September 9, 2010 J. Mogul +Intended status: Standards Track Alcatel-Lucent +Expires: January 13, 2011 J. Mogul HP H. Frystyk Microsoft L. Masinter Adobe Systems P. Leach Microsoft T. Berners-Lee W3C/MIT Y. Lafon, Ed. W3C M. Nottingham, Ed. J. Reschke, Ed. greenbytes - March 8, 2010 + July 12, 2010 HTTP/1.1, part 6: Caching - draft-ietf-httpbis-p6-cache-09 + draft-ietf-httpbis-p6-cache-10 Abstract The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, collaborative, hypermedia information systems. This document is Part 6 of the seven-part specification that defines the protocol referred to as "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 defines requirements on HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages. Editorial Note (To be removed by RFC Editor) Discussion of this draft should take place on the HTTPBIS working group mailing list (ietf-http-wg@w3.org). The current issues list is - at and related + at and related documents (including fancy diffs) can be found at . - The changes in this draft are summarized in Appendix C.10. + The changes in this draft are summarized in Appendix C.11. -Status of this Memo - This Internet-Draft is submitted to IETF in full conformance with the +Status of This Memo + This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering - Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - The list of current Internet-Drafts can be accessed at - http://www.ietf.org/ietf/1id-abstracts.txt. - - The list of Internet-Draft Shadow Directories can be accessed at - http://www.ietf.org/shadow.html. - - This Internet-Draft will expire on September 9, 2010. + This Internet-Draft will expire on January 13, 2011. Copyright Notice Copyright (c) 2010 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 (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as - described in the BSD License. + described in the Simplified BSD License. This document may contain material from IETF Documents or IETF Contributions published or made publicly 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 @@ -106,58 +100,60 @@ 2. Cache Operation . . . . . . . . . . . . . . . . . . . . . . . 7 2.1. Response Cacheability . . . . . . . . . . . . . . . . . . 7 2.1.1. Storing Partial and Incomplete Responses . . . . . . . 8 2.2. Constructing Responses from Caches . . . . . . . . . . . . 9 2.3. Freshness Model . . . . . . . . . . . . . . . . . . . . . 10 2.3.1. Calculating Freshness Lifetime . . . . . . . . . . . . 11 2.3.2. Calculating Age . . . . . . . . . . . . . . . . . . . 12 2.3.3. Serving Stale Responses . . . . . . . . . . . . . . . 13 2.4. Validation Model . . . . . . . . . . . . . . . . . . . . . 14 2.5. Request Methods that Invalidate . . . . . . . . . . . . . 14 - 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 15 - 2.7. Combining Responses . . . . . . . . . . . . . . . . . . . 16 + 2.6. Shared Caching of Authenticated Responses . . . . . . . . 15 + 2.7. Caching Negotiated Responses . . . . . . . . . . . . . . . 16 + 2.8. Combining Responses . . . . . . . . . . . . . . . . . . . 16 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 17 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 18 - 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 18 + 3.2.1. Request Cache-Control Directives . . . . . . . . . . . 19 3.2.2. Response Cache-Control Directives . . . . . . . . . . 20 - 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 22 - 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 23 - 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 - 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 25 - 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 28 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 28 - 5.1. Message Header Registration . . . . . . . . . . . . . . . 28 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 28 - 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 29 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 8.1. Normative References . . . . . . . . . . . . . . . . . . . 29 - 8.2. Informative References . . . . . . . . . . . . . . . . . . 30 - Appendix A. Compatibility with Previous Versions . . . . . . . . 30 - A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 30 - A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 30 - Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 31 + 3.2.3. Cache Control Extensions . . . . . . . . . . . . . . . 23 + 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 24 + 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 + 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 4. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 29 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 + 5.1. Cache Directive Registry . . . . . . . . . . . . . . . . . 29 + 5.2. Message Header Registration . . . . . . . . . . . . . . . 30 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 30 + 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 + 8.1. Normative References . . . . . . . . . . . . . . . . . . . 30 + 8.2. Informative References . . . . . . . . . . . . . . . . . . 31 + Appendix A. Compatibility with Previous Versions . . . . . . . . 32 + A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 32 + A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 32 + Appendix B. Collected ABNF . . . . . . . . . . . . . . . . . . . 32 Appendix C. Change Log (to be removed by RFC Editor before - publication) . . . . . . . . . . . . . . . . . . . . 32 - C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 32 - C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 32 - C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 33 - C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 33 - C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 34 - C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 34 - C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 34 - C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 35 - C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 35 - C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 35 - Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 + publication) . . . . . . . . . . . . . . . . . . . . 34 + C.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 34 + C.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 34 + C.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 35 + C.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 35 + C.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 35 + C.6. Since draft-ietf-httpbis-p6-cache-04 . . . . . . . . . . . 35 + C.7. Since draft-ietf-httpbis-p6-cache-05 . . . . . . . . . . . 36 + C.8. Since draft-ietf-httpbis-p6-cache-06 . . . . . . . . . . . 36 + C.9. Since draft-ietf-httpbis-p6-cache-07 . . . . . . . . . . . 36 + C.10. Since draft-ietf-httpbis-p6-cache-08 . . . . . . . . . . . 37 + C.11. Since draft-ietf-httpbis-p6-cache-09 . . . . . . . . . . . 37 + Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 1. Introduction HTTP is typically used for distributed information systems, where performance can be improved by the use of response caches. This document defines aspects of HTTP/1.1 related to caching and reusing response messages. 1.1. Purpose @@ -238,27 +234,27 @@ A cache that is accessible to more than one user. A non-shared cache is dedicated to a single user. 1.3. Requirements The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. An implementation is not compliant if it fails to satisfy one or more - of the MUST or REQUIRED level requirements for the protocols it - implements. An implementation that satisfies all the MUST or - REQUIRED level and all the SHOULD level requirements for its + of the "MUST" or "REQUIRED" level requirements for the protocols it + implements. An implementation that satisfies all the "MUST" or + "REQUIRED" level and all the "SHOULD" level requirements for its 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 - compliant." + compliant". 1.4. Syntax Notation This specification uses the ABNF syntax defined in Section 1.2 of [Part1] (which extends the syntax defined in [RFC5234] with a list rule). Appendix B shows the collected ABNF, with the list rule expanded. The following core rules are included by reference, as defined in [RFC5234], Appendix B.1: ALPHA (letters), CR (carriage return), CRLF @@ -296,22 +292,22 @@ o the response status code is understood by the cache, and o the "no-store" cache directive (see Section 3.2) does not appear in request or response headers, and o the "private" cache response directive (see Section 3.2.2 does not appear in the response, if the cache is shared, and o the "Authorization" header (see Section 3.1 of [Part7]) does not - appear in the request, if the cache is shared (unless the "public" - directive is present; see Section 3.2), and + appear in the request, if the cache is shared, unless the response + explicitly allows it (see Section 2.6), and o the response either: * contains an Expires header (see Section 3.3), or * contains a max-age response cache directive (see Section 3.2.2), or * contains a s-maxage response cache directive and the cache is shared, or @@ -346,31 +341,28 @@ status code. A cache that does not support the Range and Content-Range headers MUST NOT store incomplete or partial responses. 2.2. Constructing Responses from Caches For a presented request, a cache MUST NOT return a stored response, unless: - o The presented Request-URI and that of the stored response match - ([[TODO-Request-URI: Need to find a new term for this, as Part 1 - doesn't define Request-URI anymore; the new term request-target - does not work for this. (see - )]]), and + o The presented Effective Request URI (Section 4.3 of [Part1]) and + that of the stored response match, and o the request method associated with the stored response allows it to be used for the presented request, and o selecting request-headers nominated by the stored response (if - any) match those presented (see Section 2.6), and + any) match those presented (see Section 2.7), and o the presented request and stored response are free from directives that would prevent its use (see Section 3.2 and Section 3.4), and o the stored response is either: * fresh (see Section 2.3), or * allowed to be served stale (see Section 2.3.3), or @@ -391,23 +383,20 @@ having received a corresponding response. Also, note that unsafe requests might invalidate already stored responses; see Section 2.5. Caches MUST use the most recent response (as determined by the Date header) when more than one suitable response is stored. They can also forward a request with "Cache-Control: max-age=0" or "Cache- Control: no-cache" to disambiguate which response to use. - [[TODO-header-properties: end-to-end and hop-by-hop headers, non- - modifiable headers removed; re-spec in p1]] - 2.3. Freshness Model When a response is "fresh" in the cache, it can be used to satisfy subsequent requests without contacting the origin server, thereby improving efficiency. The primary mechanism for determining freshness is for an origin server to provide an explicit expiration time in the future, using either the Expires header (Section 3.3) or the max-age response cache directive (Section 3.2.2). Generally, origin servers will assign @@ -456,22 +445,23 @@ o If the cache is shared and the s-maxage response cache directive (Section 3.2.2) is present, use its value, or o If the max-age response cache directive (Section 3.2.2) is 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 - o Otherwise, no explicit expiration time is present in the response, - but a heuristic may be used; see Section 2.3.1.1. + o Otherwise, no explicit expiration time is present in the response. + A heuristic freshness lifetime might be applicable; see + Section 2.3.1.1. Note that this calculation is not vulnerable to clock skew, since all of the information comes from the origin server. 2.3.1.1. Calculating Heuristic Freshness 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. @@ -479,96 +469,106 @@ When a heuristic is used to calculate freshness lifetime, the cache SHOULD attach a Warning header with a 113 warn-code to the response if its current_age is more than 24 hours and such a warning is not already present. Also, if the response has a Last-Modified header (Section 6.6 of [Part4]), 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%. - [[REVIEW-query-string-heuristics: took away HTTP/1.0 query string - heuristic uncacheability.]] + Note: RFC 2616 ([RFC2616], Section 13.9) required that caches do + not calculate heuristic freshness for URLs with query components + (i.e., those containing '?'). In practice, this has not been + widely implemented. Therefore, servers are encouraged to send + explicit directives (e.g., Cache-Control: no-cache) if they wish + to preclude caching. 2.3.2. Calculating Age 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 is the cache's estimate of the amount of time since the response was 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. - The term "age_value" denotes the value of the Age header, in a form - appropriate for arithmetic operations. + The following data is used for the age calculation: - HTTP/1.1 requires origin servers to send a Date header, if possible, - with every response, giving the time at which the response was - generated (see Section 9.3 of [Part1]). The term "date_value" - denotes the value of the Date header, in a form appropriate for - arithmetic operations. + age_value - 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. + The term "age_value" denotes the value of the Age header + (Section 3.1), in a form appropriate for arithmetic operation; or + 0, if not available. - A response's age can be calculated in two entirely independent ways: + date_value - 1. now minus date_value, if the local clock is reasonably well - synchronized to the origin server's clock. If the result is - negative, the result is replaced by zero. + HTTP/1.1 requires origin servers to send a Date header, if + possible, with every response, giving the time at which the + response was generated. The term "date_value" denotes the value + of the Date header, in a form appropriate for arithmetic + operations. See Section 9.3 of [Part1] for the definition of the + Date header, and for requirements regarding responses without a + Date response header. - 2. age_value, if all of the caches along the response path implement - HTTP/1.1. + now - These are combined as + 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. - corrected_received_age = max(now - date_value, age_value) + request_time - 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. + The current value of the clock at the host at the time the request + resulting in the stored response was made. - corrected_initial_age = corrected_received_age - + (now - request_time) + response_time - where "request_time" is the time (according to the local clock) when - the request that elicited this response was sent. + The current value of the clock at the host at the time the + response was received. - The current_age of a stored response can then be calculated by adding - the amount of time (in seconds) since the stored response was last - validated by the origin server to the corrected_initial_age. + A response's age can be calculated in two entirely independent ways: - In summary: + 1. the "apparent_age": response_time minus date_value, if the local + clock is reasonably well synchronized to the origin server's + clock. If the result is negative, the result is replaced by + zero. - age_value - Age header field-value received with the response - date_value - Date header field-value received with the response - request_time - local time when the cache made the request - resulting in the stored response - response_time - local time when the cache received the response - now - current local time + 2. the "corrected_age_value", if all of the caches along the + response path implement HTTP/1.1; note this value MUST be + interpreted relative to the time the request was initiated, not + the time that the response was received. apparent_age = max(0, response_time - date_value); - corrected_received_age = max(apparent_age, age_value); + response_delay = response_time - request_time; - corrected_initial_age = corrected_received_age + response_delay; + corrected_age_value = age_value + response_delay; + + These are combined as + + corrected_initial_age = max(apparent_age, corrected_age_value); + + The current_age of a stored response can then be calculated by adding + the amount of time (in seconds) since the stored response was last + validated by the origin server to the corrected_initial_age. + resident_time = now - response_time; current_age = corrected_initial_age + resident_time; 2.3.3. Serving Stale Responses - 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. + 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. 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). Caches SHOULD NOT return stale responses unless they are disconnected (i.e., it cannot contact the origin server or otherwise find a forward path) or otherwise explicitly allowed (e.g., the max-stale @@ -583,91 +583,110 @@ 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. 2.4. Validation Model When a cache has one or more stored responses for a requested URI, but cannot serve any of them (e.g., because they are not fresh, or - one cannot be selected; see Section 2.6), it can use the conditional + one cannot be selected; see Section 2.7), it can use the conditional request mechanism [Part4] in the forwarded request to give the origin server an opportunity to both select a valid stored response to be used, and to update it. This process is known as "validating" or "revalidating" the stored response. When sending such a conditional request, the cache SHOULD add an If- Modified-Since header whose value is that of the Last-Modified header - from the selected (see Section 2.6) stored response, if available. + from the selected (see Section 2.7) stored response, if available. Additionally, the cache SHOULD add an If-None-Match header whose value is that of the ETag header(s) from all responses stored for the requested URI, if present. However, if any of the stored responses contains only partial content, its entity-tag SHOULD NOT be included in the If-None-Match header field unless the request is for a range that would be fully satisfied by that stored response. A 304 (Not Modified) response status code indicates that the stored - response can be updated and reused; see Section 2.7. + response can be updated and reused; see Section 2.8. A full response (i.e., one with a response body) indicates that none of the stored responses nominated in the conditional request is suitable. Instead, the full response is used both to satisfy the request and replace the stored response. [[TODO-req-missing: Should there be a requirement here?]] If a cache receives a 5xx response while attempting to validate a 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 (see Section 2.3.3). 2.5. Request Methods that Invalidate 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. The following HTTP methods MUST cause a cache to invalidate the - Request-URI as well as the URI(s) in the Location and Content- - Location headers (if present): + Effective Request URI (Section 4.3 of [Part1]) as well as the URI(s) + in the Location and Content-Location headers (if present): o PUT o DELETE o POST An invalidation based on a URI from 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. + from the host part in the Effective Request URI (Section 4.3 of + [Part1]). This helps prevent denial of service attacks. [[TODO-def-host-part: "host part" needs to be specified better.]] A cache that passes through requests for methods it does not - understand SHOULD invalidate the Request-URI. + understand SHOULD invalidate the Effective Request URI (Section 4.3 + of [Part1]). Here, "invalidate" means that the cache will either remove all stored - responses related to the Request-URI, or will mark these as "invalid" - and in need of a mandatory validation before they can be returned in - response to a subsequent request. + responses related to the Effective Request URI, or will mark these as + "invalid" and in need of a mandatory validation before they can be + returned in response to a subsequent request. Note that this does not guarantee that all appropriate responses are invalidated. For example, the request that caused the change at the origin server might not have gone through the cache where a response is stored. [[TODO-spec-success-invalidate: specify that only successful (2xx, 3xx?) responses invalidate.]] -2.6. Caching Negotiated Responses +2.6. Shared Caching of Authenticated Responses + + Shared caches MUST NOT use a cached response to a request with an + Authorization header (Section 3.1 of [Part7]) to satisfy any + subsequent request unless a cache directive that allows such + responses to be stored is present in the response. + + In this specification, the following Cache-Control response + directives (Section 3.2.2) have such an effect: must-revalidate, + public, s-maxage. + + Note that cached responses that contain the "must-revalidate" and/or + "s-maxage" response directives are not allowed to be served stale + (Section 2.3.3) by shared caches. In particular, a response with + either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to + satisfy a subsequent request without revalidating it on the origin + server. + +2.7. Caching Negotiated Responses When a cache receives a request that can be satisfied by a stored response that has a Vary header field (Section 3.5), it MUST NOT use that response unless all of the selecting request-headers nominated by the Vary header match in both the original request (i.e., that associated with the stored response), and the presented request. The selecting request-headers from two requests are defined to match if and only if those in the first request can be transformed to those in the second request by applying any of the following: @@ -692,21 +711,21 @@ subsequent requests to that resource can only be properly interpreted by the origin server. The stored response with matching selecting request-headers is known as the selected response. If no selected response is available, the cache MAY forward the presented request to the origin server in a conditional request; see Section 2.4. -2.7. Combining Responses +2.8. Combining Responses When a cache receives a 304 (Not Modified) response or a 206 (Partial Content) response (in this section, the "new" response"), it needs to created an updated response by combining the stored response with the new one, so that the updated response can be used to satisfy the request. If the new response contains an ETag, it identifies the stored response to use. [[TODO-mention-CL: may need language about Content- Location here]][[TODO-inm-mult-etags: cover case where INM with @@ -768,27 +787,32 @@ MUST transmit an Age header with a field-value of 2147483648 (2^31). Caches SHOULD use an arithmetic type of at least 31 bits of range. 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 "Cache-Control" general-header field is used to specify - directives that MUST be obeyed by all caches along the request/ - response chain. Such cache directives are unidirectional in that the - presence of a directive in a request does not imply that the same - directive is to be given in the response. + directives for caches along the request/response chain. Such cache + directives are unidirectional in that the presence of a directive in + a request does not imply that the same directive is to be given in + the response. - Note that HTTP/1.0 caches might not implement Cache-Control and - might only implement Pragma: no-cache (see Section 3.4). + HTTP/1.1 caches MUST obey the requirements of the Cache-Control + directives defined in this section. See Section 3.2.3 for + information about how Cache-Control directives defined elsewhere are + handled. + + Note: HTTP/1.0 caches might not implement Cache-Control and might + only implement Pragma: no-cache (see Section 3.4). Cache 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 target a directive to a specific cache. Cache-Control = "Cache-Control" ":" OWS Cache-Control-v Cache-Control-v = 1#cache-directive @@ -826,22 +851,22 @@ This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In particular, malicious or compromised caches might not recognize or obey this directive, and communications networks may be vulnerable to eavesdropping. max-age The max-age request directive indicates that the client is willing 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. + time in seconds. Unless the max-stale request directive is also + present, the client is not willing to accept a stale response. max-stale The max-stale request directive indicates that the client is willing to accept a response that has 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. [[TODO-staleness: of any staleness? @@ -1027,20 +1053,35 @@ does not understand the community cache-extension, since it will also see and understand the private directive and thus default to the safe behavior. Unrecognized cache directives MUST be ignored; it is assumed that any cache directive likely to be unrecognized by an HTTP/1.1 cache will be combined with standard directives (or the response's default cacheability) such that the cache behavior will remain minimally correct even if the cache does not understand the extension(s). + The HTTP Cache Directive Registry defines the name space for the + cache directives. + + Registrations MUST include the following fields: + + o Cache Directive Name + + o Pointer to specification text + + Values to be added to this name space are subject to IETF review + ([RFC5226], Section 4.1). + + The registry itself is maintained at + . + 3.3. Expires The "Expires" entity-header field gives the date/time after which the response is considered stale. See Section 2.3 for further discussion of the freshness model. The presence of an Expires field does not imply that the original resource will change or cease to exist at, before, or after that time. @@ -1094,24 +1136,24 @@ This mechanism is deprecated; no new Pragma directives will be defined in HTTP. 3.5. Vary The "Vary" response-header field conveys the set of request-header fields that were used to select the representation. Caches use this information, in part, to determine whether a stored - response can be used to satisfy a given request; see Section 2.6. + response can be used to satisfy a given request; see Section 2.7. determines, while the response is fresh, whether a cache is permitted to use the response to reply to a subsequent request without - validation; see Section 2.6. + validation; see Section 2.7. In uncacheable or stale responses, the Vary field value advises the user agent about the criteria that were used to select the representation. Vary = "Vary" ":" OWS Vary-v Vary-v = "*" / 1#field-name The set of header fields named by the Vary field value is known as the selecting request-headers. @@ -1261,21 +1303,49 @@ The freshness model (Section 2.3) does not necessarily apply to history mechanisms. I.e., a history mechanism can display a previous representation even if it has expired. This does not prohibit the history mechanism from telling the user that a view might be stale, or from honoring cache directives (e.g., Cache-Control: no-store). 5. IANA Considerations -5.1. Message Header Registration +5.1. Cache Directive Registry + + The registration procedure for HTTP Cache Directives is defined by + Section 3.2.3 of this document. + + The HTTP Cache Directive Registry should be created at + and be + populated with the registrations below: + + +------------------------+------------------------------+ + | Cache Directive | Reference | + +------------------------+------------------------------+ + | max-age | Section 3.2.1, Section 3.2.2 | + | max-stale | Section 3.2.1 | + | min-fresh | Section 3.2.1 | + | must-revalidate | Section 3.2.2 | + | no-cache | Section 3.2.1, Section 3.2.2 | + | no-store | Section 3.2.1, Section 3.2.2 | + | no-transform | Section 3.2.1, Section 3.2.2 | + | only-if-cached | Section 3.2.1 | + | private | Section 3.2.2 | + | proxy-revalidate | Section 3.2.2 | + | public | Section 3.2.2 | + | s-maxage | Section 3.2.2 | + | stale-if-error | [RFC5861], Section 4 | + | stale-while-revalidate | [RFC5861], Section 3 | + +------------------------+------------------------------+ + +5.2. Message Header Registration The Message Header Registry located at should be updated with the permanent registrations below (see [RFC3864]): +-------------------+----------+----------+-------------+ | Header Field Name | Protocol | Status | Reference | +-------------------+----------+----------+-------------+ | Age | http | standard | Section 3.1 | | Cache-Control | http | standard | Section 3.2 | @@ -1304,93 +1374,104 @@ suggestions and comments from individuals including: Shel Kaphan, Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 8. References 8.1. Normative References [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, - and Message Parsing", draft-ietf-httpbis-p1-messaging-09 - (work in progress), March 2010. + and Message Parsing", draft-ietf-httpbis-p1-messaging-10 + (work in progress), July 2010. [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 2: Message - Semantics", draft-ietf-httpbis-p2-semantics-09 (work in - progress), March 2010. + Semantics", draft-ietf-httpbis-p2-semantics-10 (work in + progress), July 2010. [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional - Requests", draft-ietf-httpbis-p4-conditional-09 (work in - progress), March 2010. + Requests", draft-ietf-httpbis-p4-conditional-10 (work in + progress), July 2010. [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and - Partial Responses", draft-ietf-httpbis-p5-range-09 (work - in progress), March 2010. + Partial Responses", draft-ietf-httpbis-p5-range-10 (work + in progress), July 2010. [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", - draft-ietf-httpbis-p7-auth-09 (work in progress), - March 2010. + draft-ietf-httpbis-p7-auth-10 (work in progress), + July 2010. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [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) Specification, Implementation", RFC 1305, March 1992. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, September 2004. + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5861] Nottingham, M., "HTTP Cache-Control Extensions for Stale + Content", RFC 5861, April 2010. + Appendix A. Compatibility with Previous Versions A.1. Changes from RFC 2068 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage was introduced to add this missing case. (Sections 2.1, 3.2). Range request responses would become very verbose if all meta-data were always returned; by allowing the server to only send needed headers in a 206 response, this problem can be avoided. - (Section 2.7) + (Section 2.8) The Cache-Control: max-age directive was not properly defined for responses. (Section 3.2.2) Warnings could be cached incorrectly, or not updated appropriately. - (Section 2.3, 2.7, 3.2, and 3.6) Warning also needed to be a general + (Section 2.3, 2.8, 3.2, and 3.6) Warning also needed to be a general header, as PUT or other methods may have need for it in requests. A.2. Changes from RFC 2616 + Make the specified age calculation algorithm less conservative. + (Section 2.3.2) + Remove requirement to consider Content-Location in successful responses in order to determine the appropriate response to use. (Section 2.4) Clarify denial of service attack avoidance requirement. (Section 2.5) + Do not mention RFC 2047 encoding and multiple languages in Warning headers anymore, as these aspects never were implemented. (Section 3.6) Appendix B. Collected ABNF Age = "Age:" OWS Age-v Age-v = delta-seconds Cache-Control = "Cache-Control:" OWS Cache-Control-v @@ -1548,28 +1629,28 @@ C.7. Since draft-ietf-httpbis-p6-cache-05 This is a total rewrite of this part of the specification. Affected issues: o : "Definition of 1xx Warn-Codes" - o : "Placement - of 13.5.1 and 13.5.2" + o : "Placement of + 13.5.1 and 13.5.2" - o : "The role - of Warning and Semantic Transparency in Caching" + o : "The role of + Warning and Semantic Transparency in Caching" - o : "Methods - and Caching" + o : "Methods and + Caching" In addition: Final work on ABNF conversion (): o Add appendix containing collected and expanded ABNF, reorganize ABNF introduction. C.8. Since draft-ietf-httpbis-p6-cache-06 Closed issues: @@ -1611,211 +1692,236 @@ Affected issues: o : Status codes and caching Partly resolved issues: o : "Placement of 13.5.1 and 13.5.2" +C.11. Since draft-ietf-httpbis-p6-cache-09 + + Closed issues: + + o : "Age + calculation" + + o : "Clarify + differences between / requirements for request and response CC + directives" + + o : "Caching + authenticated responses" + + o : "IANA registry + for cache-control directives" + + o : "Heuristic + caching of URLs with query components" + + Partly resolved issues: + + o : "Term for the + requested resource's URI" + Index A age 6 Age header 17 C cache 5 Cache Directives max-age 19, 22 max-stale 19 - min-fresh 19 - must-revalidate 21 - no-cache 18, 21 - no-store 18, 21 - no-transform 19, 22 - only-if-cached 19 - private 20 + min-fresh 20 + must-revalidate 22 + no-cache 19, 21 + no-store 19, 22 + no-transform 20, 23 + only-if-cached 20 + private 21 proxy-revalidate 22 public 20 s-maxage 22 Cache-Control header 18 cacheable 5 E - Expires header 23 + Expires header 24 explicit expiration time 5 F first-hand 6 fresh 6 freshness lifetime 6 G Grammar - Age 17 - Age-v 17 + Age 18 + Age-v 18 Cache-Control 18 Cache-Control-v 18 cache-extension 18 - cache-request-directive 18 + cache-request-directive 19 cache-response-directive 20 - delta-seconds 17 - Expires 23 - Expires-v 23 - extension-pragma 24 - Pragma 24 - pragma-directive 24 - Pragma-v 24 - Vary 25 - Vary-v 25 - warn-agent 26 - warn-code 26 - warn-date 26 - warn-text 26 - Warning 26 - Warning-v 26 - warning-value 26 + delta-seconds 18 + Expires 24 + Expires-v 24 + extension-pragma 25 + Pragma 25 + pragma-directive 25 + Pragma-v 25 + Vary 26 + Vary-v 26 + warn-agent 27 + warn-code 27 + warn-date 27 + warn-text 27 + Warning 27 + Warning-v 27 + warning-value 27 H Headers Age 17 Cache-Control 18 - Expires 23 - Pragma 24 - Vary 24 - Warning 25 + Expires 24 + Pragma 25 + Vary 25 + Warning 26 heuristic expiration time 5 M max-age Cache Directive 19, 22 max-stale Cache Directive 19 min-fresh - Cache Directive 19 + Cache Directive 20 must-revalidate - Cache Directive 21 + Cache Directive 22 N no-cache - Cache Directive 18, 21 + Cache Directive 19, 21 no-store - Cache Directive 18, 21 - no-transform Cache Directive 19, 22 + no-transform + Cache Directive 20, 23 O only-if-cached - Cache Directive 19 + Cache Directive 20 P - Pragma header 24 + Pragma header 25 private - Cache Directive 20 + Cache Directive 21 proxy-revalidate Cache Directive 22 public Cache Directive 20 S s-maxage Cache Directive 22 stale 6 V validator 6 - Vary header 24 + Vary header 25 W - Warning header 25 + Warning header 26 Authors' Addresses Roy T. Fielding (editor) Day Software 23 Corporate Plaza DR, Suite 280 Newport Beach, CA 92660 USA Phone: +1-949-706-5300 Fax: +1-949-706-5305 - Email: fielding@gbiv.com + EMail: fielding@gbiv.com URI: http://roy.gbiv.com/ Jim Gettys - One Laptop per Child + Alcatel-Lucent Bell Labs 21 Oak Knoll Road Carlisle, MA 01741 USA - Email: jg@laptop.org - URI: http://www.laptop.org/ + EMail: jg@freedesktop.org + URI: http://gettys.wordpress.com/ Jeffrey C. Mogul Hewlett-Packard Company HP Labs, Large Scale Systems Group 1501 Page Mill Road, MS 1177 Palo Alto, CA 94304 USA - Email: JeffMogul@acm.org + EMail: JeffMogul@acm.org Henrik Frystyk Nielsen Microsoft Corporation 1 Microsoft Way Redmond, WA 98052 USA - Email: henrikn@microsoft.com + EMail: henrikn@microsoft.com Larry Masinter Adobe Systems, Incorporated 345 Park Ave San Jose, CA 95110 USA - Email: LMM@acm.org + EMail: LMM@acm.org URI: http://larry.masinter.net/ Paul J. Leach Microsoft Corporation 1 Microsoft Way Redmond, WA 98052 - Email: paulle@microsoft.com + EMail: paulle@microsoft.com Tim Berners-Lee World Wide Web Consortium MIT Computer Science and Artificial Intelligence Laboratory The Stata Center, Building 32 32 Vassar Street Cambridge, MA 02139 USA - Email: timbl@w3.org + EMail: timbl@w3.org URI: http://www.w3.org/People/Berners-Lee/ Yves Lafon (editor) World Wide Web Consortium W3C / ERCIM 2004, rte des Lucioles Sophia-Antipolis, AM 06902 France - Email: ylafon@w3.org + EMail: ylafon@w3.org URI: http://www.raubacapeu.net/people/yves/ Mark Nottingham (editor) - Email: mnot@mnot.net + EMail: mnot@mnot.net URI: http://www.mnot.net/ Julian F. Reschke (editor) greenbytes GmbH Hafenweg 16 Muenster, NW 48155 Germany Phone: +49 251 2807760 Fax: +49 251 2807761 - Email: julian.reschke@greenbytes.de + EMail: julian.reschke@greenbytes.de URI: http://greenbytes.de/tech/webdav/