idnits 2.17.1 draft-ietf-httpbis-p6-cache-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 26. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2201. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2212. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2219. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2225. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([RFC2616]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 291: '... A correct cache MUST respond to a req...' RFC 2119 keyword, line 307: '...tances the cache MAY still return the ...' RFC 2119 keyword, line 317: '... correct cache SHOULD respond as abo...' RFC 2119 keyword, line 318: '...cache; if not it MUST return an error ...' RFC 2119 keyword, line 324: '... cache SHOULD forward it to the requ...' (177 more instances...) -- The draft header indicates that this document obsoletes RFC2068, but the abstract doesn't seem to mention this, which it should. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (December 20, 2007) is 5970 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-00 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-00 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-00 ** Obsolete normative reference: RFC 1305 (Obsoleted by RFC 5905) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 6 errors (**), 0 flaws (~~), 7 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Fielding, Ed. 3 Internet-Draft Day Software 4 Obsoletes: 2068, 2616 J. Gettys 5 (if approved) One Laptop per Child 6 Intended status: Standards Track J. Mogul 7 Expires: June 22, 2008 HP 8 H. Frystyk 9 Microsoft 10 L. Masinter 11 Adobe Systems 12 P. Leach 13 Microsoft 14 T. Berners-Lee 15 W3C/MIT 16 December 20, 2007 18 HTTP/1.1, part 6: Caching 19 draft-ietf-httpbis-p6-cache-00 21 Status of this Memo 23 By submitting this Internet-Draft, each author represents that any 24 applicable patent or other IPR claims of which he or she is aware 25 have been or will be disclosed, and any of which he or she becomes 26 aware will be disclosed, in accordance with Section 6 of BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF), its areas, and its working groups. Note that 30 other groups may also distribute working documents as Internet- 31 Drafts. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 The list of current Internet-Drafts can be accessed at 39 http://www.ietf.org/ietf/1id-abstracts.txt. 41 The list of Internet-Draft Shadow Directories can be accessed at 42 http://www.ietf.org/shadow.html. 44 This Internet-Draft will expire on June 22, 2008. 46 Copyright Notice 48 Copyright (C) The IETF Trust (2007). 50 Abstract 52 The Hypertext Transfer Protocol (HTTP) is an application-level 53 protocol for distributed, collaborative, hypermedia information 54 systems. HTTP has been in use by the World Wide Web global 55 information initiative since 1990. This document is Part 6 of the 56 seven-part specification that defines the protocol referred to as 57 "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 defines 58 requirements on HTTP caches and the associated header fields that 59 control cache behavior or indicate cacheable response messages. 61 Editorial Note (To be removed by RFC Editor) 63 This version of the HTTP specification contains only minimal 64 editorial changes from [RFC2616] (abstract, introductory paragraph, 65 and authors' addresses). All other changes are due to partitioning 66 the original into seven mostly independent parts. The intent is for 67 readers of future drafts to able to use draft 00 as the basis for 68 comparison when the WG makes later changes to the specification text. 69 This draft will shortly be followed by draft 01 (containing the first 70 round of changes that have already been agreed to on the mailing 71 list). There is no point in reviewing this draft other than to 72 verify that the partitioning has been done correctly. Roy T. 73 Fielding, Yves Lafon, and Julian Reschke will be the editors after 74 draft 00 is submitted. 76 Discussion of this draft should take place on the HTTPBIS working 77 group mailing list (ietf-http-wg@w3.org). The current issues list is 78 at and related 79 documents (including fancy diffs) can be found at 80 . 82 Table of Contents 84 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 85 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 5 86 1.2. Delta Seconds . . . . . . . . . . . . . . . . . . . . . . 6 87 2. Caching in HTTP . . . . . . . . . . . . . . . . . . . . . . . 6 88 2.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 6 89 2.1.1. Cache Correctness . . . . . . . . . . . . . . . . . . 8 90 2.1.2. Warnings . . . . . . . . . . . . . . . . . . . . . . . 9 91 2.1.3. Cache-control Mechanisms . . . . . . . . . . . . . . . 10 92 2.1.4. Explicit User Agent Warnings . . . . . . . . . . . . . 10 93 2.1.5. Exceptions to the Rules and Warnings . . . . . . . . . 11 94 2.1.6. Client-controlled Behavior . . . . . . . . . . . . . . 11 95 2.2. Expiration Model . . . . . . . . . . . . . . . . . . . . . 11 96 2.2.1. Server-Specified Expiration . . . . . . . . . . . . . 11 97 2.2.2. Heuristic Expiration . . . . . . . . . . . . . . . . . 12 98 2.2.3. Age Calculations . . . . . . . . . . . . . . . . . . . 13 99 2.2.4. Expiration Calculations . . . . . . . . . . . . . . . 15 100 2.2.5. Disambiguating Expiration Values . . . . . . . . . . . 16 101 2.2.6. Disambiguating Multiple Responses . . . . . . . . . . 16 102 2.3. Validation Model . . . . . . . . . . . . . . . . . . . . . 17 103 2.3.1. Last-Modified Dates . . . . . . . . . . . . . . . . . 18 104 2.3.2. Entity Tag Cache Validators . . . . . . . . . . . . . 18 105 2.3.3. Non-validating Conditionals . . . . . . . . . . . . . 18 106 2.4. Response Cacheability . . . . . . . . . . . . . . . . . . 18 107 2.5. Constructing Responses From Caches . . . . . . . . . . . . 19 108 2.5.1. End-to-end and Hop-by-hop Headers . . . . . . . . . . 19 109 2.5.2. Non-modifiable Headers . . . . . . . . . . . . . . . . 20 110 2.5.3. Combining Headers . . . . . . . . . . . . . . . . . . 21 111 2.6. Caching Negotiated Responses . . . . . . . . . . . . . . . 22 112 2.7. Shared and Non-Shared Caches . . . . . . . . . . . . . . . 24 113 2.8. Errors or Incomplete Response Cache Behavior . . . . . . . 24 114 2.9. Side Effects of GET and HEAD . . . . . . . . . . . . . . . 24 115 2.10. Invalidation After Updates or Deletions . . . . . . . . . 25 116 2.11. Write-Through Mandatory . . . . . . . . . . . . . . . . . 25 117 2.12. Cache Replacement . . . . . . . . . . . . . . . . . . . . 26 118 2.13. History Lists . . . . . . . . . . . . . . . . . . . . . . 26 119 3. Header Field Definitions . . . . . . . . . . . . . . . . . . . 27 120 3.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 121 3.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 27 122 3.2.1. What is Cacheable . . . . . . . . . . . . . . . . . . 29 123 3.2.2. What May be Stored by Caches . . . . . . . . . . . . . 30 124 3.2.3. Modifications of the Basic Expiration Mechanism . . . 31 125 3.2.4. Cache Revalidation and Reload Controls . . . . . . . . 33 126 3.2.5. No-Transform Directive . . . . . . . . . . . . . . . . 35 127 3.2.6. Cache Control Extensions . . . . . . . . . . . . . . . 36 128 3.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 37 129 3.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 38 130 3.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 131 3.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 39 132 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 133 5. Security Considerations . . . . . . . . . . . . . . . . . . . 42 134 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 42 135 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 42 136 Appendix A. Changes from RFC 2068 . . . . . . . . . . . . . . . . 43 137 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 46 139 Intellectual Property and Copyright Statements . . . . . . . . . . 49 141 1. Introduction 143 This document will define aspects of HTTP related to caching response 144 messages. Right now it only includes the extracted relevant sections 145 of RFC 2616 [RFC2616] without edit. 147 1.1. Terminology 149 This specification uses a number of terms to refer to the roles 150 played by participants in, and objects of, the HTTP communication. 152 cache 154 A program's local store of response messages and the subsystem 155 that controls its message storage, retrieval, and deletion. A 156 cache stores cacheable responses in order to reduce the response 157 time and network bandwidth consumption on future, equivalent 158 requests. Any client or server may include a cache, though a 159 cache cannot be used by a server that is acting as a tunnel. 161 cacheable 163 A response is cacheable if a cache is allowed to store a copy of 164 the response message for use in answering subsequent requests. 165 The rules for determining the cacheability of HTTP responses are 166 defined in Section 2. Even if a resource is cacheable, there may 167 be additional constraints on whether a cache can use the cached 168 copy for a particular request. 170 first-hand 172 A response is first-hand if it comes directly and without 173 unnecessary delay from the origin server, perhaps via one or more 174 proxies. A response is also first-hand if its validity has just 175 been checked directly with the origin server. 177 explicit expiration time 179 The time at which the origin server intends that an entity should 180 no longer be returned by a cache without further validation. 182 heuristic expiration time 184 An expiration time assigned by a cache when no explicit expiration 185 time is available. 187 age 188 The age of a response is the time since it was sent by, or 189 successfully validated with, the origin server. 191 freshness lifetime 193 The length of time between the generation of a response and its 194 expiration time. 196 fresh 198 A response is fresh if its age has not yet exceeded its freshness 199 lifetime. 201 stale 203 A response is stale if its age has passed its freshness lifetime. 205 semantically transparent 207 A cache behaves in a "semantically transparent" manner, with 208 respect to a particular response, when its use affects neither the 209 requesting client nor the origin server, except to improve 210 performance. When a cache is semantically transparent, the client 211 receives exactly the same response (except for hop-by-hop headers) 212 that it would have received had its request been handled directly 213 by the origin server. 215 validator 217 A protocol element (e.g., an entity tag or a Last-Modified time) 218 that is used to find out whether a cache entry is an equivalent 219 copy of an entity. 221 1.2. Delta Seconds 223 Some HTTP header fields allow a time value to be specified as an 224 integer number of seconds, represented in decimal, after the time 225 that the message was received. 227 delta-seconds = 1*DIGIT 229 2. Caching in HTTP 231 2.1. Overview 233 HTTP is typically used for distributed information systems, where 234 performance can be improved by the use of response caches. The 235 HTTP/1.1 protocol includes a number of elements intended to make 236 caching work as well as possible. Because these elements are 237 inextricable from other aspects of the protocol, and because they 238 interact with each other, it is useful to describe the basic caching 239 design of HTTP separately from the detailed descriptions of methods, 240 headers, response codes, etc. 242 Caching would be useless if it did not significantly improve 243 performance. The goal of caching in HTTP/1.1 is to eliminate the 244 need to send requests in many cases, and to eliminate the need to 245 send full responses in many other cases. The former reduces the 246 number of network round-trips required for many operations; we use an 247 "expiration" mechanism for this purpose (see Section 2.2). The 248 latter reduces network bandwidth requirements; we use a "validation" 249 mechanism for this purpose (see Section 2.3). 251 Requirements for performance, availability, and disconnected 252 operation require us to be able to relax the goal of semantic 253 transparency. The HTTP/1.1 protocol allows origin servers, caches, 254 and clients to explicitly reduce transparency when necessary. 255 However, because non-transparent operation may confuse non-expert 256 users, and might be incompatible with certain server applications 257 (such as those for ordering merchandise), the protocol requires that 258 transparency be relaxed 260 o only by an explicit protocol-level request when relaxed by client 261 or origin server 263 o only with an explicit warning to the end user when relaxed by 264 cache or client 266 Therefore, the HTTP/1.1 protocol provides these important elements: 268 1. Protocol features that provide full semantic transparency when 269 this is required by all parties. 271 2. Protocol features that allow an origin server or user agent to 272 explicitly request and control non-transparent operation. 274 3. Protocol features that allow a cache to attach warnings to 275 responses that do not preserve the requested approximation of 276 semantic transparency. 278 A basic principle is that it must be possible for the clients to 279 detect any potential relaxation of semantic transparency. 281 Note: The server, cache, or client implementor might be faced with 282 design decisions not explicitly discussed in this specification. 284 If a decision might affect semantic transparency, the implementor 285 ought to err on the side of maintaining transparency unless a 286 careful and complete analysis shows significant benefits in 287 breaking transparency. 289 2.1.1. Cache Correctness 291 A correct cache MUST respond to a request with the most up-to-date 292 response held by the cache that is appropriate to the request (see 293 sections 2.2.5, 2.2.6, and 2.12) which meets one of the following 294 conditions: 296 1. It has been checked for equivalence with what the origin server 297 would have returned by revalidating the response with the origin 298 server (Section 2.3); 300 2. It is "fresh enough" (see Section 2.2). In the default case, 301 this means it meets the least restrictive freshness requirement 302 of the client, origin server, and cache (see Section 3.2); if the 303 origin server so specifies, it is the freshness requirement of 304 the origin server alone. If a stored response is not "fresh 305 enough" by the most restrictive freshness requirement of both the 306 client and the origin server, in carefully considered 307 circumstances the cache MAY still return the response with the 308 appropriate Warning header (see section 2.1.5 and 3.6), unless 309 such a response is prohibited (e.g., by a "no-store" cache- 310 directive, or by a "no-cache" cache-request-directive; see 311 Section 3.2). 313 3. It is an appropriate 304 (Not Modified), 305 (Proxy Redirect), or 314 error (4xx or 5xx) response message. 316 If the cache can not communicate with the origin server, then a 317 correct cache SHOULD respond as above if the response can be 318 correctly served from the cache; if not it MUST return an error or 319 warning indicating that there was a communication failure. 321 If a cache receives a response (either an entire response, or a 304 322 (Not Modified) response) that it would normally forward to the 323 requesting client, and the received response is no longer fresh, the 324 cache SHOULD forward it to the requesting client without adding a new 325 Warning (but without removing any existing Warning headers). A cache 326 SHOULD NOT attempt to revalidate a response simply because that 327 response became stale in transit; this might lead to an infinite 328 loop. A user agent that receives a stale response without a Warning 329 MAY display a warning indication to the user. 331 2.1.2. Warnings 333 Whenever a cache returns a response that is neither first-hand nor 334 "fresh enough" (in the sense of condition 2 in Section 2.1.1), it 335 MUST attach a warning to that effect, using a Warning general-header. 336 The Warning header and the currently defined warnings are described 337 in Section 3.6. The warning allows clients to take appropriate 338 action. 340 Warnings MAY be used for other purposes, both cache-related and 341 otherwise. The use of a warning, rather than an error status code, 342 distinguish these responses from true failures. 344 Warnings are assigned three digit warn-codes. The first digit 345 indicates whether the Warning MUST or MUST NOT be deleted from a 346 stored cache entry after a successful revalidation: 348 1xx Warnings that describe the freshness or revalidation status of 349 the response, and so MUST be deleted after a successful 350 revalidation. 1XX warn-codes MAY be generated by a cache only when 351 validating a cached entry. It MUST NOT be generated by clients. 353 2xx Warnings that describe some aspect of the entity body or entity 354 headers that is not rectified by a revalidation (for example, a 355 lossy compression of the entity bodies) and which MUST NOT be 356 deleted after a successful revalidation. 358 See Section 3.6 for the definitions of the codes themselves. 360 HTTP/1.0 caches will cache all Warnings in responses, without 361 deleting the ones in the first category. Warnings in responses that 362 are passed to HTTP/1.0 caches carry an extra warning-date field, 363 which prevents a future HTTP/1.1 recipient from believing an 364 erroneously cached Warning. 366 Warnings also carry a warning text. The text MAY be in any 367 appropriate natural language (perhaps based on the client's Accept 368 headers), and include an OPTIONAL indication of what character set is 369 used. 371 Multiple warnings MAY be attached to a response (either by the origin 372 server or by a cache), including multiple warnings with the same code 373 number. For example, a server might provide the same warning with 374 texts in both English and Basque. 376 When multiple warnings are attached to a response, it might not be 377 practical or reasonable to display all of them to the user. This 378 version of HTTP does not specify strict priority rules for deciding 379 which warnings to display and in what order, but does suggest some 380 heuristics. 382 2.1.3. Cache-control Mechanisms 384 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 385 times and validators) are implicit directives to caches. In some 386 cases, a server or client might need to provide explicit directives 387 to the HTTP caches. We use the Cache-Control header for this 388 purpose. 390 The Cache-Control header allows a client or server to transmit a 391 variety of directives in either requests or responses. These 392 directives typically override the default caching algorithms. As a 393 general rule, if there is any apparent conflict between header 394 values, the most restrictive interpretation is applied (that is, the 395 one that is most likely to preserve semantic transparency). However, 396 in some cases, cache-control directives are explicitly specified as 397 weakening the approximation of semantic transparency (for example, 398 "max-stale" or "public"). 400 The cache-control directives are described in detail in Section 3.2. 402 2.1.4. Explicit User Agent Warnings 404 Many user agents make it possible for users to override the basic 405 caching mechanisms. For example, the user agent might allow the user 406 to specify that cached entities (even explicitly stale ones) are 407 never validated. Or the user agent might habitually add "Cache- 408 Control: max-stale=3600" to every request. The user agent SHOULD NOT 409 default to either non-transparent behavior, or behavior that results 410 in abnormally ineffective caching, but MAY be explicitly configured 411 to do so by an explicit action of the user. 413 If the user has overridden the basic caching mechanisms, the user 414 agent SHOULD explicitly indicate to the user whenever this results in 415 the display of information that might not meet the server's 416 transparency requirements (in particular, if the displayed entity is 417 known to be stale). Since the protocol normally allows the user 418 agent to determine if responses are stale or not, this indication 419 need only be displayed when this actually happens. The indication 420 need not be a dialog box; it could be an icon (for example, a picture 421 of a rotting fish) or some other indicator. 423 If the user has overridden the caching mechanisms in a way that would 424 abnormally reduce the effectiveness of caches, the user agent SHOULD 425 continually indicate this state to the user (for example, by a 426 display of a picture of currency in flames) so that the user does not 427 inadvertently consume excess resources or suffer from excessive 428 latency. 430 2.1.5. Exceptions to the Rules and Warnings 432 In some cases, the operator of a cache MAY choose to configure it to 433 return stale responses even when not requested by clients. This 434 decision ought not be made lightly, but may be necessary for reasons 435 of availability or performance, especially when the cache is poorly 436 connected to the origin server. Whenever a cache returns a stale 437 response, it MUST mark it as such (using a Warning header) enabling 438 the client software to alert the user that there might be a potential 439 problem. 441 It also allows the user agent to take steps to obtain a first-hand or 442 fresh response. For this reason, a cache SHOULD NOT return a stale 443 response if the client explicitly requests a first-hand or fresh one, 444 unless it is impossible to comply for technical or policy reasons. 446 2.1.6. Client-controlled Behavior 448 While the origin server (and to a lesser extent, intermediate caches, 449 by their contribution to the age of a response) are the primary 450 source of expiration information, in some cases the client might need 451 to control a cache's decision about whether to return a cached 452 response without validating it. Clients do this using several 453 directives of the Cache-Control header. 455 A client's request MAY specify the maximum age it is willing to 456 accept of an unvalidated response; specifying a value of zero forces 457 the cache(s) to revalidate all responses. A client MAY also specify 458 the minimum time remaining before a response expires. Both of these 459 options increase constraints on the behavior of caches, and so cannot 460 further relax the cache's approximation of semantic transparency. 462 A client MAY also specify that it will accept stale responses, up to 463 some maximum amount of staleness. This loosens the constraints on 464 the caches, and so might violate the origin server's specified 465 constraints on semantic transparency, but might be necessary to 466 support disconnected operation, or high availability in the face of 467 poor connectivity. 469 2.2. Expiration Model 471 2.2.1. Server-Specified Expiration 473 HTTP caching works best when caches can entirely avoid making 474 requests to the origin server. The primary mechanism for avoiding 475 requests is for an origin server to provide an explicit expiration 476 time in the future, indicating that a response MAY be used to satisfy 477 subsequent requests. In other words, a cache can return a fresh 478 response without first contacting the server. 480 Our expectation is that servers will assign future explicit 481 expiration times to responses in the belief that the entity is not 482 likely to change, in a semantically significant way, before the 483 expiration time is reached. This normally preserves semantic 484 transparency, as long as the server's expiration times are carefully 485 chosen. 487 The expiration mechanism applies only to responses taken from a cache 488 and not to first-hand responses forwarded immediately to the 489 requesting client. 491 If an origin server wishes to force a semantically transparent cache 492 to validate every request, it MAY assign an explicit expiration time 493 in the past. This means that the response is always stale, and so 494 the cache SHOULD validate it before using it for subsequent requests. 495 See Section 3.2.4 for a more restrictive way to force revalidation. 497 If an origin server wishes to force any HTTP/1.1 cache, no matter how 498 it is configured, to validate every request, it SHOULD use the "must- 499 revalidate" cache-control directive (see Section 3.2). 501 Servers specify explicit expiration times using either the Expires 502 header, or the max-age directive of the Cache-Control header. 504 An expiration time cannot be used to force a user agent to refresh 505 its display or reload a resource; its semantics apply only to caching 506 mechanisms, and such mechanisms need only check a resource's 507 expiration status when a new request for that resource is initiated. 508 See Section 2.13 for an explanation of the difference between caches 509 and history mechanisms. 511 2.2.2. Heuristic Expiration 513 Since origin servers do not always provide explicit expiration times, 514 HTTP caches typically assign heuristic expiration times, employing 515 algorithms that use other header values (such as the Last-Modified 516 time) to estimate a plausible expiration time. The HTTP/1.1 517 specification does not provide specific algorithms, but does impose 518 worst-case constraints on their results. Since heuristic expiration 519 times might compromise semantic transparency, they ought to used 520 cautiously, and we encourage origin servers to provide explicit 521 expiration times as much as possible. 523 2.2.3. Age Calculations 525 In order to know if a cached entry is fresh, a cache needs to know if 526 its age exceeds its freshness lifetime. We discuss how to calculate 527 the latter in Section 2.2.4; this section describes how to calculate 528 the age of a response or cache entry. 530 In this discussion, we use the term "now" to mean "the current value 531 of the clock at the host performing the calculation." Hosts that use 532 HTTP, but especially hosts running origin servers and caches, SHOULD 533 use NTP [RFC1305] or some similar protocol to synchronize their 534 clocks to a globally accurate time standard. 536 HTTP/1.1 requires origin servers to send a Date header, if possible, 537 with every response, giving the time at which the response was 538 generated (see Section 8.3 of [Part1]). We use the term "date_value" 539 to denote the value of the Date header, in a form appropriate for 540 arithmetic operations. 542 HTTP/1.1 uses the Age response-header to convey the estimated age of 543 the response message when obtained from a cache. The Age field value 544 is the cache's estimate of the amount of time since the response was 545 generated or revalidated by the origin server. 547 In essence, the Age value is the sum of the time that the response 548 has been resident in each of the caches along the path from the 549 origin server, plus the amount of time it has been in transit along 550 network paths. 552 We use the term "age_value" to denote the value of the Age header, in 553 a form appropriate for arithmetic operations. 555 A response's age can be calculated in two entirely independent ways: 557 1. now minus date_value, if the local clock is reasonably well 558 synchronized to the origin server's clock. If the result is 559 negative, the result is replaced by zero. 561 2. age_value, if all of the caches along the response path implement 562 HTTP/1.1. 564 Given that we have two independent ways to compute the age of a 565 response when it is received, we can combine these as 567 corrected_received_age = max(now - date_value, age_value) 569 and as long as we have either nearly synchronized clocks or all- 570 HTTP/1.1 paths, one gets a reliable (conservative) result. 572 Because of network-imposed delays, some significant interval might 573 pass between the time that a server generates a response and the time 574 it is received at the next outbound cache or client. If uncorrected, 575 this delay could result in improperly low ages. 577 Because the request that resulted in the returned Age value must have 578 been initiated prior to that Age value's generation, we can correct 579 for delays imposed by the network by recording the time at which the 580 request was initiated. Then, when an Age value is received, it MUST 581 be interpreted relative to the time the request was initiated, not 582 the time that the response was received. This algorithm results in 583 conservative behavior no matter how much delay is experienced. So, 584 we compute: 586 corrected_initial_age = corrected_received_age 587 + (now - request_time) 589 where "request_time" is the time (according to the local clock) when 590 the request that elicited this response was sent. 592 Summary of age calculation algorithm, when a cache receives a 593 response: 595 /* 596 * age_value 597 * is the value of Age: header received by the cache with 598 * this response. 599 * date_value 600 * is the value of the origin server's Date: header 601 * request_time 602 * is the (local) time when the cache made the request 603 * that resulted in this cached response 604 * response_time 605 * is the (local) time when the cache received the 606 * response 607 * now 608 * is the current (local) time 609 */ 611 apparent_age = max(0, response_time - date_value); 612 corrected_received_age = max(apparent_age, age_value); 613 response_delay = response_time - request_time; 614 corrected_initial_age = corrected_received_age + response_delay; 615 resident_time = now - response_time; 616 current_age = corrected_initial_age + resident_time; 618 The current_age of a cache entry is calculated by adding the amount 619 of time (in seconds) since the cache entry was last validated by the 620 origin server to the corrected_initial_age. When a response is 621 generated from a cache entry, the cache MUST include a single Age 622 header field in the response with a value equal to the cache entry's 623 current_age. 625 The presence of an Age header field in a response implies that a 626 response is not first-hand. However, the converse is not true, since 627 the lack of an Age header field in a response does not imply that the 628 response is first-hand unless all caches along the request path are 629 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 630 the Age header field). 632 2.2.4. Expiration Calculations 634 In order to decide whether a response is fresh or stale, we need to 635 compare its freshness lifetime to its age. The age is calculated as 636 described in Section 2.2.3; this section describes how to calculate 637 the freshness lifetime, and to determine if a response has expired. 638 In the discussion below, the values can be represented in any form 639 appropriate for arithmetic operations. 641 We use the term "expires_value" to denote the value of the Expires 642 header. We use the term "max_age_value" to denote an appropriate 643 value of the number of seconds carried by the "max-age" directive of 644 the Cache-Control header in a response (see Section 3.2.3). 646 The max-age directive takes priority over Expires, so if max-age is 647 present in a response, the calculation is simply: 649 freshness_lifetime = max_age_value 651 Otherwise, if Expires is present in the response, the calculation is: 653 freshness_lifetime = expires_value - date_value 655 Note that neither of these calculations is vulnerable to clock skew, 656 since all of the information comes from the origin server. 658 If none of Expires, Cache-Control: max-age, or Cache-Control: 659 s-maxage (see Section 3.2.3) appears in the response, and the 660 response does not include other restrictions on caching, the cache 661 MAY compute a freshness lifetime using a heuristic. The cache MUST 662 attach Warning 113 to any response whose age is more than 24 hours if 663 such warning has not already been added. 665 Also, if the response does have a Last-Modified time, the heuristic 666 expiration value SHOULD be no more than some fraction of the interval 667 since that time. A typical setting of this fraction might be 10%. 669 The calculation to determine if a response has expired is quite 670 simple: 672 response_is_fresh = (freshness_lifetime > current_age) 674 2.2.5. Disambiguating Expiration Values 676 Because expiration values are assigned optimistically, it is possible 677 for two caches to contain fresh values for the same resource that are 678 different. 680 If a client performing a retrieval receives a non-first-hand response 681 for a request that was already fresh in its own cache, and the Date 682 header in its existing cache entry is newer than the Date on the new 683 response, then the client MAY ignore the response. If so, it MAY 684 retry the request with a "Cache-Control: max-age=0" directive (see 685 Section 3.2), to force a check with the origin server. 687 If a cache has two fresh responses for the same representation with 688 different validators, it MUST use the one with the more recent Date 689 header. This situation might arise because the cache is pooling 690 responses from other caches, or because a client has asked for a 691 reload or a revalidation of an apparently fresh cache entry. 693 2.2.6. Disambiguating Multiple Responses 695 Because a client might be receiving responses via multiple paths, so 696 that some responses flow through one set of caches and other 697 responses flow through a different set of caches, a client might 698 receive responses in an order different from that in which the origin 699 server sent them. We would like the client to use the most recently 700 generated response, even if older responses are still apparently 701 fresh. 703 Neither the entity tag nor the expiration value can impose an 704 ordering on responses, since it is possible that a later response 705 intentionally carries an earlier expiration time. The Date values 706 are ordered to a granularity of one second. 708 When a client tries to revalidate a cache entry, and the response it 709 receives contains a Date header that appears to be older than the one 710 for the existing entry, then the client SHOULD repeat the request 711 unconditionally, and include 713 Cache-Control: max-age=0 715 to force any intermediate caches to validate their copies directly 716 with the origin server, or 717 Cache-Control: no-cache 719 to force any intermediate caches to obtain a new copy from the origin 720 server. 722 If the Date values are equal, then the client MAY use either response 723 (or MAY, if it is being extremely prudent, request a new response). 724 Servers MUST NOT depend on clients being able to choose 725 deterministically between responses generated during the same second, 726 if their expiration times overlap. 728 2.3. Validation Model 730 When a cache has a stale entry that it would like to use as a 731 response to a client's request, it first has to check with the origin 732 server (or possibly an intermediate cache with a fresh response) to 733 see if its cached entry is still usable. We call this "validating" 734 the cache entry. Since we do not want to have to pay the overhead of 735 retransmitting the full response if the cached entry is good, and we 736 do not want to pay the overhead of an extra round trip if the cached 737 entry is invalid, the HTTP/1.1 protocol supports the use of 738 conditional methods. 740 The key protocol features for supporting conditional methods are 741 those concerned with "cache validators." When an origin server 742 generates a full response, it attaches some sort of validator to it, 743 which is kept with the cache entry. When a client (user agent or 744 proxy cache) makes a conditional request for a resource for which it 745 has a cache entry, it includes the associated validator in the 746 request. 748 The server then checks that validator against the current validator 749 for the entity, and, if they match (see Section 4 of [Part4]), it 750 responds with a special status code (usually, 304 (Not Modified)) and 751 no entity-body. Otherwise, it returns a full response (including 752 entity-body). Thus, we avoid transmitting the full response if the 753 validator matches, and we avoid an extra round trip if it does not 754 match. 756 In HTTP/1.1, a conditional request looks exactly the same as a normal 757 request for the same resource, except that it carries a special 758 header (which includes the validator) that implicitly turns the 759 method (usually, GET) into a conditional. 761 The protocol includes both positive and negative senses of cache- 762 validating conditions. That is, it is possible to request either 763 that a method be performed if and only if a validator matches or if 764 and only if no validators match. 766 Note: a response that lacks a validator may still be cached, and 767 served from cache until it expires, unless this is explicitly 768 prohibited by a cache-control directive. However, a cache cannot 769 do a conditional retrieval if it does not have a validator for the 770 entity, which means it will not be refreshable after it expires. 772 2.3.1. Last-Modified Dates 774 The Last-Modified entity-header field value is often used as a cache 775 validator. In simple terms, a cache entry is considered to be valid 776 if the entity has not been modified since the Last-Modified value. 778 2.3.2. Entity Tag Cache Validators 780 The ETag response-header field value, an entity tag, provides for an 781 "opaque" cache validator. This might allow more reliable validation 782 in situations where it is inconvenient to store modification dates, 783 where the one-second resolution of HTTP date values is not 784 sufficient, or where the origin server wishes to avoid certain 785 paradoxes that might arise from the use of modification dates. 787 Entity Tags are described in Section 2 of [Part4]. 789 2.3.3. Non-validating Conditionals 791 The principle behind entity tags is that only the service author 792 knows the semantics of a resource well enough to select an 793 appropriate cache validation mechanism, and the specification of any 794 validator comparison function more complex than byte-equality would 795 open up a can of worms. Thus, comparisons of any other headers 796 (except Last-Modified, for compatibility with HTTP/1.0) are never 797 used for purposes of validating a cache entry. 799 2.4. Response Cacheability 801 Unless specifically constrained by a cache-control (Section 3.2) 802 directive, a caching system MAY always store a successful response 803 (see Section 2.8) as a cache entry, MAY return it without validation 804 if it is fresh, and MAY return it after successful validation. If 805 there is neither a cache validator nor an explicit expiration time 806 associated with a response, we do not expect it to be cached, but 807 certain caches MAY violate this expectation (for example, when little 808 or no network connectivity is available). A client can usually 809 detect that such a response was taken from a cache by comparing the 810 Date header to the current time. 812 Note: some HTTP/1.0 caches are known to violate this expectation 813 without providing any Warning. 815 However, in some cases it might be inappropriate for a cache to 816 retain an entity, or to return it in response to a subsequent 817 request. This might be because absolute semantic transparency is 818 deemed necessary by the service author, or because of security or 819 privacy considerations. Certain cache-control directives are 820 therefore provided so that the server can indicate that certain 821 resource entities, or portions thereof, are not to be cached 822 regardless of other considerations. 824 Note that Section 3.1 of [Part7] normally prevents a shared cache 825 from saving and returning a response to a previous request if that 826 request included an Authorization header. 828 A response received with a status code of 200, 203, 206, 300, 301 or 829 410 MAY be stored by a cache and used in reply to a subsequent 830 request, subject to the expiration mechanism, unless a cache-control 831 directive prohibits caching. However, a cache that does not support 832 the Range and Content-Range headers MUST NOT cache 206 (Partial 833 Content) responses. 835 A response received with any other status code (e.g. status codes 302 836 and 307) MUST NOT be returned in a reply to a subsequent request 837 unless there are cache-control directives or another header(s) that 838 explicitly allow it. For example, these include the following: an 839 Expires header (Section 3.3); a "max-age", "s-maxage", "must- 840 revalidate", "proxy-revalidate", "public" or "private" cache-control 841 directive (Section 3.2). 843 2.5. Constructing Responses From Caches 845 The purpose of an HTTP cache is to store information received in 846 response to requests for use in responding to future requests. In 847 many cases, a cache simply returns the appropriate parts of a 848 response to the requester. However, if the cache holds a cache entry 849 based on a previous response, it might have to combine parts of a new 850 response with what is held in the cache entry. 852 2.5.1. End-to-end and Hop-by-hop Headers 854 For the purpose of defining the behavior of caches and non-caching 855 proxies, we divide HTTP headers into two categories: 857 o End-to-end headers, which are transmitted to the ultimate 858 recipient of a request or response. End-to-end headers in 859 responses MUST be stored as part of a cache entry and MUST be 860 transmitted in any response formed from a cache entry. 862 o Hop-by-hop headers, which are meaningful only for a single 863 transport-level connection, and are not stored by caches or 864 forwarded by proxies. 866 The following HTTP/1.1 headers are hop-by-hop headers: 868 o Connection 870 o Keep-Alive 872 o Proxy-Authenticate 874 o Proxy-Authorization 876 o TE 878 o Trailers 880 o Transfer-Encoding 882 o Upgrade 884 All other headers defined by HTTP/1.1 are end-to-end headers. 886 Other hop-by-hop headers MUST be listed in a Connection header, 887 (Section 8.1 of [Part1]) to be introduced into HTTP/1.1 (or later). 889 2.5.2. Non-modifiable Headers 891 Some features of the HTTP/1.1 protocol, such as Digest 892 Authentication, depend on the value of certain end-to-end headers. A 893 transparent proxy SHOULD NOT modify an end-to-end header unless the 894 definition of that header requires or specifically allows that. 896 A transparent proxy MUST NOT modify any of the following fields in a 897 request or response, and it MUST NOT add any of these fields if not 898 already present: 900 o Content-Location 902 o Content-MD5 904 o ETag 906 o Last-Modified 908 A transparent proxy MUST NOT modify any of the following fields in a 909 response: 911 o Expires 913 but it MAY add any of these fields if not already present. If an 914 Expires header is added, it MUST be given a field-value identical to 915 that of the Date header in that response. 917 A proxy MUST NOT modify or add any of the following fields in a 918 message that contains the no-transform cache-control directive, or in 919 any request: 921 o Content-Encoding 923 o Content-Range 925 o Content-Type 927 A non-transparent proxy MAY modify or add these fields to a message 928 that does not include no-transform, but if it does so, it MUST add a 929 Warning 214 (Transformation applied) if one does not already appear 930 in the message (see Section 3.6). 932 Warning: unnecessary modification of end-to-end headers might 933 cause authentication failures if stronger authentication 934 mechanisms are introduced in later versions of HTTP. Such 935 authentication mechanisms MAY rely on the values of header fields 936 not listed here. 938 The Content-Length field of a request or response is added or deleted 939 according to the rules in Section 4.4 of [Part1]. A transparent 940 proxy MUST preserve the entity-length (Section 3.2.2 of [Part3]) of 941 the entity-body, although it MAY change the transfer-length (Section 942 4.4 of [Part1]). 944 2.5.3. Combining Headers 946 When a cache makes a validating request to a server, and the server 947 provides a 304 (Not Modified) response or a 206 (Partial Content) 948 response, the cache then constructs a response to send to the 949 requesting client. 951 If the status code is 304 (Not Modified), the cache uses the entity- 952 body stored in the cache entry as the entity-body of this outgoing 953 response. If the status code is 206 (Partial Content) and the ETag 954 or Last-Modified headers match exactly, the cache MAY combine the 955 contents stored in the cache entry with the new contents received in 956 the response and use the result as the entity-body of this outgoing 957 response, (see Section 4 of [Part5]). 959 The end-to-end headers stored in the cache entry are used for the 960 constructed response, except that 962 o any stored Warning headers with warn-code 1xx (see Section 3.6) 963 MUST be deleted from the cache entry and the forwarded response. 965 o any stored Warning headers with warn-code 2xx MUST be retained in 966 the cache entry and the forwarded response. 968 o any end-to-end headers provided in the 304 or 206 response MUST 969 replace the corresponding headers from the cache entry. 971 Unless the cache decides to remove the cache entry, it MUST also 972 replace the end-to-end headers stored with the cache entry with 973 corresponding headers received in the incoming response, except for 974 Warning headers as described immediately above. If a header field- 975 name in the incoming response matches more than one header in the 976 cache entry, all such old headers MUST be replaced. 978 In other words, the set of end-to-end headers received in the 979 incoming response overrides all corresponding end-to-end headers 980 stored with the cache entry (except for stored Warning headers with 981 warn-code 1xx, which are deleted even if not overridden). 983 Note: this rule allows an origin server to use a 304 (Not 984 Modified) or a 206 (Partial Content) response to update any header 985 associated with a previous response for the same entity or sub- 986 ranges thereof, although it might not always be meaningful or 987 correct to do so. This rule does not allow an origin server to 988 use a 304 (Not Modified) or a 206 (Partial Content) response to 989 entirely delete a header that it had provided with a previous 990 response. 992 2.6. Caching Negotiated Responses 994 Use of server-driven content negotiation (Section 4.1 of [Part3]), as 995 indicated by the presence of a Vary header field in a response, 996 alters the conditions and procedure by which a cache can use the 997 response for subsequent requests. See Section 3.5 for use of the 998 Vary header field by servers. 1000 A server SHOULD use the Vary header field to inform a cache of what 1001 request-header fields were used to select among multiple 1002 representations of a cacheable response subject to server-driven 1003 negotiation. The set of header fields named by the Vary field value 1004 is known as the "selecting" request-headers. 1006 When the cache receives a subsequent request whose Request-URI 1007 specifies one or more cache entries including a Vary header field, 1008 the cache MUST NOT use such a cache entry to construct a response to 1009 the new request unless all of the selecting request-headers present 1010 in the new request match the corresponding stored request-headers in 1011 the original request. 1013 The selecting request-headers from two requests are defined to match 1014 if and only if the selecting request-headers in the first request can 1015 be transformed to the selecting request-headers in the second request 1016 by adding or removing linear white space (LWS) at places where this 1017 is allowed by the corresponding BNF, and/or combining multiple 1018 message-header fields with the same field name following the rules 1019 about message headers in Section 4.2 of [Part1]. 1021 A Vary header field-value of "*" always fails to match and subsequent 1022 requests on that resource can only be properly interpreted by the 1023 origin server. 1025 If the selecting request header fields for the cached entry do not 1026 match the selecting request header fields of the new request, then 1027 the cache MUST NOT use a cached entry to satisfy the request unless 1028 it first relays the new request to the origin server in a conditional 1029 request and the server responds with 304 (Not Modified), including an 1030 entity tag or Content-Location that indicates the entity to be used. 1032 If an entity tag was assigned to a cached representation, the 1033 forwarded request SHOULD be conditional and include the entity tags 1034 in an If-None-Match header field from all its cache entries for the 1035 resource. This conveys to the server the set of entities currently 1036 held by the cache, so that if any one of these entities matches the 1037 requested entity, the server can use the ETag header field in its 304 1038 (Not Modified) response to tell the cache which entry is appropriate. 1039 If the entity-tag of the new response matches that of an existing 1040 entry, the new response SHOULD be used to update the header fields of 1041 the existing entry, and the result MUST be returned to the client. 1043 If any of the existing cache entries contains only partial content 1044 for the associated entity, its entity-tag SHOULD NOT be included in 1045 the If-None-Match header field unless the request is for a range that 1046 would be fully satisfied by that entry. 1048 If a cache receives a successful response whose Content-Location 1049 field matches that of an existing cache entry for the same Request- 1050 URI, whose entity-tag differs from that of the existing entry, and 1051 whose Date is more recent than that of the existing entry, the 1052 existing entry SHOULD NOT be returned in response to future requests 1053 and SHOULD be deleted from the cache. 1055 2.7. Shared and Non-Shared Caches 1057 For reasons of security and privacy, it is necessary to make a 1058 distinction between "shared" and "non-shared" caches. A non-shared 1059 cache is one that is accessible only to a single user. Accessibility 1060 in this case SHOULD be enforced by appropriate security mechanisms. 1061 All other caches are considered to be "shared." Other sections of 1062 this specification place certain constraints on the operation of 1063 shared caches in order to prevent loss of privacy or failure of 1064 access controls. 1066 2.8. Errors or Incomplete Response Cache Behavior 1068 A cache that receives an incomplete response (for example, with fewer 1069 bytes of data than specified in a Content-Length header) MAY store 1070 the response. However, the cache MUST treat this as a partial 1071 response. Partial responses MAY be combined as described in Section 1072 4 of [Part5]; the result might be a full response or might still be 1073 partial. A cache MUST NOT return a partial response to a client 1074 without explicitly marking it as such, using the 206 (Partial 1075 Content) status code. A cache MUST NOT return a partial response 1076 using a status code of 200 (OK). 1078 If a cache receives a 5xx response while attempting to revalidate an 1079 entry, it MAY either forward this response to the requesting client, 1080 or act as if the server failed to respond. In the latter case, it 1081 MAY return a previously received response unless the cached entry 1082 includes the "must-revalidate" cache-control directive (see 1083 Section 3.2). 1085 2.9. Side Effects of GET and HEAD 1087 Unless the origin server explicitly prohibits the caching of their 1088 responses, the application of GET and HEAD methods to any resources 1089 SHOULD NOT have side effects that would lead to erroneous behavior if 1090 these responses are taken from a cache. They MAY still have side 1091 effects, but a cache is not required to consider such side effects in 1092 its caching decisions. Caches are always expected to observe an 1093 origin server's explicit restrictions on caching. 1095 We note one exception to this rule: since some applications have 1096 traditionally used GETs and HEADs with query URLs (those containing a 1097 "?" in the rel_path part) to perform operations with significant side 1098 effects, caches MUST NOT treat responses to such URIs as fresh unless 1099 the server provides an explicit expiration time. This specifically 1100 means that responses from HTTP/1.0 servers for such URIs SHOULD NOT 1101 be taken from a cache. See Section 8.1.1 of [Part2] for related 1102 information. 1104 2.10. Invalidation After Updates or Deletions 1106 The effect of certain methods performed on a resource at the origin 1107 server might cause one or more existing cache entries to become non- 1108 transparently invalid. That is, although they might continue to be 1109 "fresh," they do not accurately reflect what the origin server would 1110 return for a new request on that resource. 1112 There is no way for the HTTP protocol to guarantee that all such 1113 cache entries are marked invalid. For example, the request that 1114 caused the change at the origin server might not have gone through 1115 the proxy where a cache entry is stored. However, several rules help 1116 reduce the likelihood of erroneous behavior. 1118 In this section, the phrase "invalidate an entity" means that the 1119 cache will either remove all instances of that entity from its 1120 storage, or will mark these as "invalid" and in need of a mandatory 1121 revalidation before they can be returned in response to a subsequent 1122 request. 1124 Some HTTP methods MUST cause a cache to invalidate an entity. This 1125 is either the entity referred to by the Request-URI, or by the 1126 Location or Content-Location headers (if present). These methods 1127 are: 1129 o PUT 1131 o DELETE 1133 o POST 1135 In order to prevent denial of service attacks, an invalidation based 1136 on the URI in a Location or Content-Location header MUST only be 1137 performed if the host part is the same as in the Request-URI. 1139 A cache that passes through requests for methods it does not 1140 understand SHOULD invalidate any entities referred to by the Request- 1141 URI. 1143 2.11. Write-Through Mandatory 1145 All methods that might be expected to cause modifications to the 1146 origin server's resources MUST be written through to the origin 1147 server. This currently includes all methods except for GET and HEAD. 1148 A cache MUST NOT reply to such a request from a client before having 1149 transmitted the request to the inbound server, and having received a 1150 corresponding response from the inbound server. This does not 1151 prevent a proxy cache from sending a 100 (Continue) response before 1152 the inbound server has sent its final reply. 1154 The alternative (known as "write-back" or "copy-back" caching) is not 1155 allowed in HTTP/1.1, due to the difficulty of providing consistent 1156 updates and the problems arising from server, cache, or network 1157 failure prior to write-back. 1159 2.12. Cache Replacement 1161 If a new cacheable (see sections 3.2.2, 2.2.5, 2.2.6 and 2.8) 1162 response is received from a resource while any existing responses for 1163 the same resource are cached, the cache SHOULD use the new response 1164 to reply to the current request. It MAY insert it into cache storage 1165 and MAY, if it meets all other requirements, use it to respond to any 1166 future requests that would previously have caused the old response to 1167 be returned. If it inserts the new response into cache storage the 1168 rules in Section 2.5.3 apply. 1170 Note: a new response that has an older Date header value than 1171 existing cached responses is not cacheable. 1173 2.13. History Lists 1175 User agents often have history mechanisms, such as "Back" buttons and 1176 history lists, which can be used to redisplay an entity retrieved 1177 earlier in a session. 1179 History mechanisms and caches are different. In particular history 1180 mechanisms SHOULD NOT try to show a semantically transparent view of 1181 the current state of a resource. Rather, a history mechanism is 1182 meant to show exactly what the user saw at the time when the resource 1183 was retrieved. 1185 By default, an expiration time does not apply to history mechanisms. 1186 If the entity is still in storage, a history mechanism SHOULD display 1187 it even if the entity has expired, unless the user has specifically 1188 configured the agent to refresh expired history documents. 1190 This is not to be construed to prohibit the history mechanism from 1191 telling the user that a view might be stale. 1193 Note: if history list mechanisms unnecessarily prevent users from 1194 viewing stale resources, this will tend to force service authors 1195 to avoid using HTTP expiration controls and cache controls when 1196 they would otherwise like to. Service authors may consider it 1197 important that users not be presented with error messages or 1198 warning messages when they use navigation controls (such as BACK) 1199 to view previously fetched resources. Even though sometimes such 1200 resources ought not to cached, or ought to expire quickly, user 1201 interface considerations may force service authors to resort to 1202 other means of preventing caching (e.g. "once-only" URLs) in order 1203 not to suffer the effects of improperly functioning history 1204 mechanisms. 1206 3. Header Field Definitions 1208 This section defines the syntax and semantics of all standard 1209 HTTP/1.1 header fields. For entity-header fields, both sender and 1210 recipient refer to either the client or the server, depending on who 1211 sends and who receives the entity. 1213 3.1. Age 1215 The Age response-header field conveys the sender's estimate of the 1216 amount of time since the response (or its revalidation) was generated 1217 at the origin server. A cached response is "fresh" if its age does 1218 not exceed its freshness lifetime. Age values are calculated as 1219 specified in Section 2.2.3. 1221 Age = "Age" ":" age-value 1222 age-value = delta-seconds 1224 Age values are non-negative decimal integers, representing time in 1225 seconds. 1227 If a cache receives a value larger than the largest positive integer 1228 it can represent, or if any of its age calculations overflows, it 1229 MUST transmit an Age header with a value of 2147483648 (2^31). An 1230 HTTP/1.1 server that includes a cache MUST include an Age header 1231 field in every response generated from its own cache. Caches SHOULD 1232 use an arithmetic type of at least 31 bits of range. 1234 3.2. Cache-Control 1236 The Cache-Control general-header field is used to specify directives 1237 that MUST be obeyed by all caching mechanisms along the request/ 1238 response chain. The directives specify behavior intended to prevent 1239 caches from adversely interfering with the request or response. 1240 These directives typically override the default caching algorithms. 1241 Cache directives are unidirectional in that the presence of a 1242 directive in a request does not imply that the same directive is to 1243 be given in the response. 1245 Note that HTTP/1.0 caches might not implement Cache-Control and 1246 might only implement Pragma: no-cache (see Section 3.4). 1248 Cache directives MUST be passed through by a proxy or gateway 1249 application, regardless of their significance to that application, 1250 since the directives might be applicable to all recipients along the 1251 request/response chain. It is not possible to specify a cache- 1252 directive for a specific cache. 1254 Cache-Control = "Cache-Control" ":" 1#cache-directive 1256 cache-directive = cache-request-directive 1257 | cache-response-directive 1259 cache-request-directive = 1260 "no-cache" ; Section 3.2.1 1261 | "no-store" ; Section 3.2.2 1262 | "max-age" "=" delta-seconds ; Section 3.2.3, 3.2.4 1263 | "max-stale" [ "=" delta-seconds ] ; Section 3.2.3 1264 | "min-fresh" "=" delta-seconds ; Section 3.2.3 1265 | "no-transform" ; Section 3.2.5 1266 | "only-if-cached" ; Section 3.2.4 1267 | cache-extension ; Section 3.2.6 1269 cache-response-directive = 1270 "public" ; Section 3.2.1 1271 | "private" [ "=" <"> 1#field-name <"> ] ; Section 3.2.1 1272 | "no-cache" [ "=" <"> 1#field-name <"> ]; Section 3.2.1 1273 | "no-store" ; Section 3.2.2 1274 | "no-transform" ; Section 3.2.5 1275 | "must-revalidate" ; Section 3.2.4 1276 | "proxy-revalidate" ; Section 3.2.4 1277 | "max-age" "=" delta-seconds ; Section 3.2.3 1278 | "s-maxage" "=" delta-seconds ; Section 3.2.3 1279 | cache-extension ; Section 3.2.6 1281 cache-extension = token [ "=" ( token | quoted-string ) ] 1283 When a directive appears without any 1#field-name parameter, the 1284 directive applies to the entire request or response. When such a 1285 directive appears with a 1#field-name parameter, it applies only to 1286 the named field or fields, and not to the rest of the request or 1287 response. This mechanism supports extensibility; implementations of 1288 future versions of the HTTP protocol might apply these directives to 1289 header fields not defined in HTTP/1.1. 1291 The cache-control directives can be broken down into these general 1292 categories: 1294 o Restrictions on what are cacheable; these may only be imposed by 1295 the origin server. 1297 o Restrictions on what may be stored by a cache; these may be 1298 imposed by either the origin server or the user agent. 1300 o Modifications of the basic expiration mechanism; these may be 1301 imposed by either the origin server or the user agent. 1303 o Controls over cache revalidation and reload; these may only be 1304 imposed by a user agent. 1306 o Control over transformation of entities. 1308 o Extensions to the caching system. 1310 3.2.1. What is Cacheable 1312 By default, a response is cacheable if the requirements of the 1313 request method, request header fields, and the response status 1314 indicate that it is cacheable. Section 2.4 summarizes these defaults 1315 for cacheability. The following Cache-Control response directives 1316 allow an origin server to override the default cacheability of a 1317 response: 1319 public 1321 Indicates that the response MAY be cached by any cache, even if it 1322 would normally be non-cacheable or cacheable only within a non- 1323 shared cache. (See also Authorization, Section 3.1 of [Part7], 1324 for additional details.) 1326 private 1328 Indicates that all or part of the response message is intended for 1329 a single user and MUST NOT be cached by a shared cache. This 1330 allows an origin server to state that the specified parts of the 1331 response are intended for only one user and are not a valid 1332 response for requests by other users. A private (non-shared) 1333 cache MAY cache the response. 1335 Note: This usage of the word private only controls where the 1336 response may be cached, and cannot ensure the privacy of the 1337 message content. 1339 no-cache 1341 If the no-cache directive does not specify a field-name, then a 1342 cache MUST NOT use the response to satisfy a subsequent request 1343 without successful revalidation with the origin server. This 1344 allows an origin server to prevent caching even by caches that 1345 have been configured to return stale responses to client requests. 1347 If the no-cache directive does specify one or more field-names, 1348 then a cache MAY use the response to satisfy a subsequent request, 1349 subject to any other restrictions on caching. However, the 1350 specified field-name(s) MUST NOT be sent in the response to a 1351 subsequent request without successful revalidation with the origin 1352 server. This allows an origin server to prevent the re-use of 1353 certain header fields in a response, while still allowing caching 1354 of the rest of the response. 1356 Note: Most HTTP/1.0 caches will not recognize or obey this 1357 directive. 1359 3.2.2. What May be Stored by Caches 1361 no-store 1363 The purpose of the no-store directive is to prevent the 1364 inadvertent release or retention of sensitive information (for 1365 example, on backup tapes). The no-store directive applies to the 1366 entire message, and MAY be sent either in a response or in a 1367 request. If sent in a request, a cache MUST NOT store any part of 1368 either this request or any response to it. If sent in a response, 1369 a cache MUST NOT store any part of either this response or the 1370 request that elicited it. This directive applies to both non- 1371 shared and shared caches. "MUST NOT store" in this context means 1372 that the cache MUST NOT intentionally store the information in 1373 non-volatile storage, and MUST make a best-effort attempt to 1374 remove the information from volatile storage as promptly as 1375 possible after forwarding it. 1377 Even when this directive is associated with a response, users 1378 might explicitly store such a response outside of the caching 1379 system (e.g., with a "Save As" dialog). History buffers MAY store 1380 such responses as part of their normal operation. 1382 The purpose of this directive is to meet the stated requirements 1383 of certain users and service authors who are concerned about 1384 accidental releases of information via unanticipated accesses to 1385 cache data structures. While the use of this directive might 1386 improve privacy in some cases, we caution that it is NOT in any 1387 way a reliable or sufficient mechanism for ensuring privacy. In 1388 particular, malicious or compromised caches might not recognize or 1389 obey this directive, and communications networks might be 1390 vulnerable to eavesdropping. 1392 3.2.3. Modifications of the Basic Expiration Mechanism 1394 The expiration time of an entity MAY be specified by the origin 1395 server using the Expires header (see Section 3.3). Alternatively, it 1396 MAY be specified using the max-age directive in a response. When the 1397 max-age cache-control directive is present in a cached response, the 1398 response is stale if its current age is greater than the age value 1399 given (in seconds) at the time of a new request for that resource. 1400 The max-age directive on a response implies that the response is 1401 cacheable (i.e., "public") unless some other, more restrictive cache 1402 directive is also present. 1404 If a response includes both an Expires header and a max-age 1405 directive, the max-age directive overrides the Expires header, even 1406 if the Expires header is more restrictive. This rule allows an 1407 origin server to provide, for a given response, a longer expiration 1408 time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This 1409 might be useful if certain HTTP/1.0 caches improperly calculate ages 1410 or expiration times, perhaps due to desynchronized clocks. 1412 Many HTTP/1.0 cache implementations will treat an Expires value that 1413 is less than or equal to the response Date value as being equivalent 1414 to the Cache-Control response directive "no-cache". If an HTTP/1.1 1415 cache receives such a response, and the response does not include a 1416 Cache-Control header field, it SHOULD consider the response to be 1417 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 1419 Note: An origin server might wish to use a relatively new HTTP 1420 cache control feature, such as the "private" directive, on a 1421 network including older caches that do not understand that 1422 feature. The origin server will need to combine the new feature 1423 with an Expires field whose value is less than or equal to the 1424 Date value. This will prevent older caches from improperly 1425 caching the response. 1427 s-maxage 1429 If a response includes an s-maxage directive, then for a shared 1430 cache (but not for a private cache), the maximum age specified by 1431 this directive overrides the maximum age specified by either the 1432 max-age directive or the Expires header. The s-maxage directive 1433 also implies the semantics of the proxy-revalidate directive (see 1434 Section 3.2.4), i.e., that the shared cache must not use the entry 1435 after it becomes stale to respond to a subsequent request without 1436 first revalidating it with the origin server. The s-maxage 1437 directive is always ignored by a private cache. 1439 Note that most older caches, not compliant with this specification, 1440 do not implement any cache-control directives. An origin server 1441 wishing to use a cache-control directive that restricts, but does not 1442 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 1443 requirement that the max-age directive overrides the Expires header, 1444 and the fact that pre-HTTP/1.1-compliant caches do not observe the 1445 max-age directive. 1447 Other directives allow a user agent to modify the basic expiration 1448 mechanism. These directives MAY be specified on a request: 1450 max-age 1452 Indicates that the client is willing to accept a response whose 1453 age is no greater than the specified time in seconds. Unless max- 1454 stale directive is also included, the client is not willing to 1455 accept a stale response. 1457 min-fresh 1459 Indicates that the client is willing to accept a response whose 1460 freshness lifetime is no less than its current age plus the 1461 specified time in seconds. That is, the client wants a response 1462 that will still be fresh for at least the specified number of 1463 seconds. 1465 max-stale 1467 Indicates that the client is willing to accept a response that has 1468 exceeded its expiration time. If max-stale is assigned a value, 1469 then the client is willing to accept a response that has exceeded 1470 its expiration time by no more than the specified number of 1471 seconds. If no value is assigned to max-stale, then the client is 1472 willing to accept a stale response of any age. 1474 If a cache returns a stale response, either because of a max-stale 1475 directive on a request, or because the cache is configured to 1476 override the expiration time of a response, the cache MUST attach a 1477 Warning header to the stale response, using Warning 110 (Response is 1478 stale). 1480 A cache MAY be configured to return stale responses without 1481 validation, but only if this does not conflict with any "MUST"-level 1482 requirements concerning cache validation (e.g., a "must-revalidate" 1483 cache-control directive). 1485 If both the new request and the cached entry include "max-age" 1486 directives, then the lesser of the two values is used for determining 1487 the freshness of the cached entry for that request. 1489 3.2.4. Cache Revalidation and Reload Controls 1491 Sometimes a user agent might want or need to insist that a cache 1492 revalidate its cache entry with the origin server (and not just with 1493 the next cache along the path to the origin server), or to reload its 1494 cache entry from the origin server. End-to-end revalidation might be 1495 necessary if either the cache or the origin server has overestimated 1496 the expiration time of the cached response. End-to-end reload may be 1497 necessary if the cache entry has become corrupted for some reason. 1499 End-to-end revalidation may be requested either when the client does 1500 not have its own local cached copy, in which case we call it 1501 "unspecified end-to-end revalidation", or when the client does have a 1502 local cached copy, in which case we call it "specific end-to-end 1503 revalidation." 1505 The client can specify these three kinds of action using Cache- 1506 Control request directives: 1508 End-to-end reload 1510 The request includes a "no-cache" cache-control directive or, for 1511 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 1512 names MUST NOT be included with the no-cache directive in a 1513 request. The server MUST NOT use a cached copy when responding to 1514 such a request. 1516 Specific end-to-end revalidation 1518 The request includes a "max-age=0" cache-control directive, which 1519 forces each cache along the path to the origin server to 1520 revalidate its own entry, if any, with the next cache or server. 1521 The initial request includes a cache-validating conditional with 1522 the client's current validator. 1524 Unspecified end-to-end revalidation 1526 The request includes "max-age=0" cache-control directive, which 1527 forces each cache along the path to the origin server to 1528 revalidate its own entry, if any, with the next cache or server. 1529 The initial request does not include a cache-validating 1530 conditional; the first cache along the path (if any) that holds a 1531 cache entry for this resource includes a cache-validating 1532 conditional with its current validator. 1534 max-age 1535 When an intermediate cache is forced, by means of a max-age=0 1536 directive, to revalidate its own cache entry, and the client has 1537 supplied its own validator in the request, the supplied validator 1538 might differ from the validator currently stored with the cache 1539 entry. In this case, the cache MAY use either validator in making 1540 its own request without affecting semantic transparency. 1542 However, the choice of validator might affect performance. The 1543 best approach is for the intermediate cache to use its own 1544 validator when making its request. If the server replies with 304 1545 (Not Modified), then the cache can return its now validated copy 1546 to the client with a 200 (OK) response. If the server replies 1547 with a new entity and cache validator, however, the intermediate 1548 cache can compare the returned validator with the one provided in 1549 the client's request, using the strong comparison function. If 1550 the client's validator is equal to the origin server's, then the 1551 intermediate cache simply returns 304 (Not Modified). Otherwise, 1552 it returns the new entity with a 200 (OK) response. 1554 If a request includes the no-cache directive, it SHOULD NOT 1555 include min-fresh, max-stale, or max-age. 1557 only-if-cached 1559 In some cases, such as times of extremely poor network 1560 connectivity, a client may want a cache to return only those 1561 responses that it currently has stored, and not to reload or 1562 revalidate with the origin server. To do this, the client may 1563 include the only-if-cached directive in a request. If it receives 1564 this directive, a cache SHOULD either respond using a cached entry 1565 that is consistent with the other constraints of the request, or 1566 respond with a 504 (Gateway Timeout) status. However, if a group 1567 of caches is being operated as a unified system with good internal 1568 connectivity, such a request MAY be forwarded within that group of 1569 caches. 1571 must-revalidate 1573 Because a cache MAY be configured to ignore a server's specified 1574 expiration time, and because a client request MAY include a max- 1575 stale directive (which has a similar effect), the protocol also 1576 includes a mechanism for the origin server to require revalidation 1577 of a cache entry on any subsequent use. When the must-revalidate 1578 directive is present in a response received by a cache, that cache 1579 MUST NOT use the entry after it becomes stale to respond to a 1580 subsequent request without first revalidating it with the origin 1581 server. (I.e., the cache MUST do an end-to-end revalidation every 1582 time, if, based solely on the origin server's Expires or max-age 1583 value, the cached response is stale.) 1585 The must-revalidate directive is necessary to support reliable 1586 operation for certain protocol features. In all circumstances an 1587 HTTP/1.1 cache MUST obey the must-revalidate directive; in 1588 particular, if the cache cannot reach the origin server for any 1589 reason, it MUST generate a 504 (Gateway Timeout) response. 1591 Servers SHOULD send the must-revalidate directive if and only if 1592 failure to revalidate a request on the entity could result in 1593 incorrect operation, such as a silently unexecuted financial 1594 transaction. Recipients MUST NOT take any automated action that 1595 violates this directive, and MUST NOT automatically provide an 1596 unvalidated copy of the entity if revalidation fails. 1598 Although this is not recommended, user agents operating under 1599 severe connectivity constraints MAY violate this directive but, if 1600 so, MUST explicitly warn the user that an unvalidated response has 1601 been provided. The warning MUST be provided on each unvalidated 1602 access, and SHOULD require explicit user confirmation. 1604 proxy-revalidate 1606 The proxy-revalidate directive has the same meaning as the must- 1607 revalidate directive, except that it does not apply to non-shared 1608 user agent caches. It can be used on a response to an 1609 authenticated request to permit the user's cache to store and 1610 later return the response without needing to revalidate it (since 1611 it has already been authenticated once by that user), while still 1612 requiring proxies that service many users to revalidate each time 1613 (in order to make sure that each user has been authenticated). 1614 Note that such authenticated responses also need the public cache 1615 control directive in order to allow them to be cached at all. 1617 3.2.5. No-Transform Directive 1619 no-transform 1621 Implementors of intermediate caches (proxies) have found it useful 1622 to convert the media type of certain entity bodies. A non- 1623 transparent proxy might, for example, convert between image 1624 formats in order to save cache space or to reduce the amount of 1625 traffic on a slow link. 1627 Serious operational problems occur, however, when these 1628 transformations are applied to entity bodies intended for certain 1629 kinds of applications. For example, applications for medical 1630 imaging, scientific data analysis and those using end-to-end 1631 authentication, all depend on receiving an entity body that is bit 1632 for bit identical to the original entity-body. 1634 Therefore, if a message includes the no-transform directive, an 1635 intermediate cache or proxy MUST NOT change those headers that are 1636 listed in Section 2.5.2 as being subject to the no-transform 1637 directive. This implies that the cache or proxy MUST NOT change 1638 any aspect of the entity-body that is specified by these headers, 1639 including the value of the entity-body itself. 1641 3.2.6. Cache Control Extensions 1643 The Cache-Control header field can be extended through the use of one 1644 or more cache-extension tokens, each with an optional assigned value. 1645 Informational extensions (those which do not require a change in 1646 cache behavior) MAY be added without changing the semantics of other 1647 directives. Behavioral extensions are designed to work by acting as 1648 modifiers to the existing base of cache directives. Both the new 1649 directive and the standard directive are supplied, such that 1650 applications which do not understand the new directive will default 1651 to the behavior specified by the standard directive, and those that 1652 understand the new directive will recognize it as modifying the 1653 requirements associated with the standard directive. In this way, 1654 extensions to the cache-control directives can be made without 1655 requiring changes to the base protocol. 1657 This extension mechanism depends on an HTTP cache obeying all of the 1658 cache-control directives defined for its native HTTP-version, obeying 1659 certain extensions, and ignoring all directives that it does not 1660 understand. 1662 For example, consider a hypothetical new response directive called 1663 community which acts as a modifier to the private directive. We 1664 define this new directive to mean that, in addition to any non-shared 1665 cache, any cache which is shared only by members of the community 1666 named within its value may cache the response. An origin server 1667 wishing to allow the UCI community to use an otherwise private 1668 response in their shared cache(s) could do so by including 1670 Cache-Control: private, community="UCI" 1672 A cache seeing this header field will act correctly even if the cache 1673 does not understand the community cache-extension, since it will also 1674 see and understand the private directive and thus default to the safe 1675 behavior. 1677 Unrecognized cache-directives MUST be ignored; it is assumed that any 1678 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 1679 be combined with standard directives (or the response's default 1680 cacheability) such that the cache behavior will remain minimally 1681 correct even if the cache does not understand the extension(s). 1683 3.3. Expires 1685 The Expires entity-header field gives the date/time after which the 1686 response is considered stale. A stale cache entry may not normally 1687 be returned by a cache (either a proxy cache or a user agent cache) 1688 unless it is first validated with the origin server (or with an 1689 intermediate cache that has a fresh copy of the entity). See 1690 Section 2.2 for further discussion of the expiration model. 1692 The presence of an Expires field does not imply that the original 1693 resource will change or cease to exist at, before, or after that 1694 time. 1696 The format is an absolute date and time as defined by HTTP-date in 1697 Section 3.3.1 of [Part1]; it MUST be in RFC 1123 date format: 1699 Expires = "Expires" ":" HTTP-date 1701 An example of its use is 1703 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1705 Note: if a response includes a Cache-Control field with the max- 1706 age directive (see Section 3.2.3), that directive overrides the 1707 Expires field. 1709 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1710 especially including the value "0", as in the past (i.e., "already 1711 expired"). 1713 To mark a response as "already expired," an origin server sends an 1714 Expires date that is equal to the Date header value. (See the rules 1715 for expiration calculations in Section 2.2.4.) 1717 To mark a response as "never expires," an origin server sends an 1718 Expires date approximately one year from the time the response is 1719 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 1720 year in the future. 1722 The presence of an Expires header field with a date value of some 1723 time in the future on a response that otherwise would by default be 1724 non-cacheable indicates that the response is cacheable, unless 1725 indicated otherwise by a Cache-Control header field (Section 3.2). 1727 3.4. Pragma 1729 The Pragma general-header field is used to include implementation- 1730 specific directives that might apply to any recipient along the 1731 request/response chain. All pragma directives specify optional 1732 behavior from the viewpoint of the protocol; however, some systems 1733 MAY require that behavior be consistent with the directives. 1735 Pragma = "Pragma" ":" 1#pragma-directive 1736 pragma-directive = "no-cache" | extension-pragma 1737 extension-pragma = token [ "=" ( token | quoted-string ) ] 1739 When the no-cache directive is present in a request message, an 1740 application SHOULD forward the request toward the origin server even 1741 if it has a cached copy of what is being requested. This pragma 1742 directive has the same semantics as the no-cache cache-directive (see 1743 Section 3.2) and is defined here for backward compatibility with 1744 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 1745 request is sent to a server not known to be HTTP/1.1 compliant. 1747 Pragma directives MUST be passed through by a proxy or gateway 1748 application, regardless of their significance to that application, 1749 since the directives might be applicable to all recipients along the 1750 request/response chain. It is not possible to specify a pragma for a 1751 specific recipient; however, any pragma directive not relevant to a 1752 recipient SHOULD be ignored by that recipient. 1754 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1755 sent "Cache-Control: no-cache". No new Pragma directives will be 1756 defined in HTTP. 1758 Note: because the meaning of "Pragma: no-cache as a response 1759 header field is not actually specified, it does not provide a 1760 reliable replacement for "Cache-Control: no-cache" in a response 1762 3.5. Vary 1764 The Vary field value indicates the set of request-header fields that 1765 fully determines, while the response is fresh, whether a cache is 1766 permitted to use the response to reply to a subsequent request 1767 without revalidation. For uncacheable or stale responses, the Vary 1768 field value advises the user agent about the criteria that were used 1769 to select the representation. A Vary field value of "*" implies that 1770 a cache cannot determine from the request headers of a subsequent 1771 request whether this response is the appropriate representation. See 1772 Section 2.6 for use of the Vary header field by caches. 1774 Vary = "Vary" ":" ( "*" | 1#field-name ) 1776 An HTTP/1.1 server SHOULD include a Vary header field with any 1777 cacheable response that is subject to server-driven negotiation. 1778 Doing so allows a cache to properly interpret future requests on that 1779 resource and informs the user agent about the presence of negotiation 1780 on that resource. A server MAY include a Vary header field with a 1781 non-cacheable response that is subject to server-driven negotiation, 1782 since this might provide the user agent with useful information about 1783 the dimensions over which the response varies at the time of the 1784 response. 1786 A Vary field value consisting of a list of field-names signals that 1787 the representation selected for the response is based on a selection 1788 algorithm which considers ONLY the listed request-header field values 1789 in selecting the most appropriate representation. A cache MAY assume 1790 that the same selection will be made for future requests with the 1791 same values for the listed field names, for the duration of time for 1792 which the response is fresh. 1794 The field-names given are not limited to the set of standard request- 1795 header fields defined by this specification. Field names are case- 1796 insensitive. 1798 A Vary field value of "*" signals that unspecified parameters not 1799 limited to the request-headers (e.g., the network address of the 1800 client), play a role in the selection of the response representation. 1801 The "*" value MUST NOT be generated by a proxy server; it may only be 1802 generated by an origin server. 1804 3.6. Warning 1806 The Warning general-header field is used to carry additional 1807 information about the status or transformation of a message which 1808 might not be reflected in the message. This information is typically 1809 used to warn about a possible lack of semantic transparency from 1810 caching operations or transformations applied to the entity body of 1811 the message. 1813 Warning headers are sent with responses using: 1815 Warning = "Warning" ":" 1#warning-value 1817 warning-value = warn-code SP warn-agent SP warn-text 1818 [SP warn-date] 1820 warn-code = 3DIGIT 1821 warn-agent = ( host [ ":" port ] ) | pseudonym 1822 ; the name or pseudonym of the server adding 1823 ; the Warning header, for use in debugging 1824 warn-text = quoted-string 1825 warn-date = <"> HTTP-date <"> 1827 A response MAY carry more than one Warning header. 1829 The warn-text SHOULD be in a natural language and character set that 1830 is most likely to be intelligible to the human user receiving the 1831 response. This decision MAY be based on any available knowledge, 1832 such as the location of the cache or user, the Accept-Language field 1833 in a request, the Content-Language field in a response, etc. The 1834 default language is English and the default character set is ISO- 1835 8859-1. 1837 If a character set other than ISO-8859-1 is used, it MUST be encoded 1838 in the warn-text using the method described in RFC 2047 [RFC2047]. 1840 Warning headers can in general be applied to any message, however 1841 some specific warn-codes are specific to caches and can only be 1842 applied to response messages. New Warning headers SHOULD be added 1843 after any existing Warning headers. A cache MUST NOT delete any 1844 Warning header that it received with a message. However, if a cache 1845 successfully validates a cache entry, it SHOULD remove any Warning 1846 headers previously attached to that entry except as specified for 1847 specific Warning codes. It MUST then add any Warning headers 1848 received in the validating response. In other words, Warning headers 1849 are those that would be attached to the most recent relevant 1850 response. 1852 When multiple Warning headers are attached to a response, the user 1853 agent ought to inform the user of as many of them as possible, in the 1854 order that they appear in the response. If it is not possible to 1855 inform the user of all of the warnings, the user agent SHOULD follow 1856 these heuristics: 1858 o Warnings that appear early in the response take priority over 1859 those appearing later in the response. 1861 o Warnings in the user's preferred character set take priority over 1862 warnings in other character sets but with identical warn-codes and 1863 warn-agents. 1865 Systems that generate multiple Warning headers SHOULD order them with 1866 this user agent behavior in mind. 1868 Requirements for the behavior of caches with respect to Warnings are 1869 stated in Section 2.1.2. 1871 This is a list of the currently-defined warn-codes, each with a 1872 recommended warn-text in English, and a description of its meaning. 1874 110 Response is stale 1876 MUST be included whenever the returned response is stale. 1878 111 Revalidation failed 1880 MUST be included if a cache returns a stale response because an 1881 attempt to revalidate the response failed, due to an inability to 1882 reach the server. 1884 112 Disconnected operation 1886 SHOULD be included if the cache is intentionally disconnected from 1887 the rest of the network for a period of time. 1889 113 Heuristic expiration 1891 MUST be included if the cache heuristically chose a freshness 1892 lifetime greater than 24 hours and the response's age is greater 1893 than 24 hours. 1895 199 Miscellaneous warning 1897 The warning text MAY include arbitrary information to be presented 1898 to a human user, or logged. A system receiving this warning MUST 1899 NOT take any automated action, besides presenting the warning to 1900 the user. 1902 214 Transformation applied 1904 MUST be added by an intermediate cache or proxy if it applies any 1905 transformation changing the content-coding (as specified in the 1906 Content-Encoding header) or media-type (as specified in the 1907 Content-Type header) of the response, or the entity-body of the 1908 response, unless this Warning code already appears in the 1909 response. 1911 299 Miscellaneous persistent warning 1913 The warning text MAY include arbitrary information to be presented 1914 to a human user, or logged. A system receiving this warning MUST 1915 NOT take any automated action. 1917 If an implementation sends a message with one or more Warning headers 1918 whose version is HTTP/1.0 or lower, then the sender MUST include in 1919 each warning-value a warn-date that matches the date in the response. 1921 If an implementation receives a message with a warning-value that 1922 includes a warn-date, and that warn-date is different from the Date 1923 value in the response, then that warning-value MUST be deleted from 1924 the message before storing, forwarding, or using it. (This prevents 1925 bad consequences of naive caching of Warning header fields.) If all 1926 of the warning-values are deleted for this reason, the Warning header 1927 MUST be deleted as well. 1929 4. IANA Considerations 1931 TBD. 1933 5. Security Considerations 1935 Caching proxies provide additional potential vulnerabilities, since 1936 the contents of the cache represent an attractive target for 1937 malicious exploitation. Because cache contents persist after an HTTP 1938 request is complete, an attack on the cache can reveal information 1939 long after a user believes that the information has been removed from 1940 the network. Therefore, cache contents should be protected as 1941 sensitive information. 1943 6. Acknowledgments 1945 Much of the content and presentation of the caching design is due to 1946 suggestions and comments from individuals including: Shel Kaphan, 1947 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1949 Based on an XML translation of RFC 2616 by Julian Reschke. 1951 7. References 1953 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1954 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1955 part 1: URIs, Connections, and Message Parsing", 1956 draft-ietf-httpbis-p1-messaging-00 (work in progress), 1957 December 2007. 1959 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1960 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1961 part 2: Message Semantics", 1962 draft-ietf-httpbis-p2-semantics-00 (work in progress), 1963 December 2007. 1965 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1966 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1967 part 3: Message Payload and Content Negotiation", 1968 draft-ietf-httpbis-p3-payload-00 (work in progress), 1969 December 2007. 1971 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1972 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1973 part 4: Conditional Requests", 1974 draft-ietf-httpbis-p4-conditional-00 (work in progress), 1975 December 2007. 1977 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1978 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1979 part 5: Range Requests and Partial Responses", 1980 draft-ietf-httpbis-p5-range-00 (work in progress), 1981 December 2007. 1983 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1984 Masinter, L., Leach, P., and T. Berners-Lee, "HTTP/1.1, 1985 part 7: Authentication", draft-ietf-httpbis-p7-auth-00 1986 (work in progress), December 2007. 1988 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1989 Specification, Implementation", RFC 1305, March 1992. 1991 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1992 Part Three: Message Header Extensions for Non-ASCII Text", 1993 RFC 2047, November 1996. 1995 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 1996 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 1997 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 1999 Appendix A. Changes from RFC 2068 2001 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 2002 was introduced to add this missing case. (Sections 2.4, 3.2, 3.2.3) 2004 The Cache-Control: max-age directive was not properly defined for 2005 responses. (Section 3.2.3) 2007 Warnings could be cached incorrectly, or not updated appropriately. 2008 (Section 2.1.2, 2.2.4, 2.5.2, 2.5.3, 3.2.3, and 3.6) Warning also 2009 needed to be a general header, as PUT or other methods may have need 2010 for it in requests. 2012 Index 2014 A 2015 age 5 2016 Age header 27 2018 C 2019 cache 5 2020 Cache Directives 2021 max-age 32 2022 max-age 33 2023 max-stale 32 2024 min-fresh 32 2025 must-revalidate 34 2026 no-cache 29 2027 no-store 30 2028 no-transform 35 2029 only-if-cached 34 2030 private 29 2031 proxy-revalidate 35 2032 public 29 2033 s-maxage 31 2034 Cache-Control header 27 2035 cacheable 5 2037 E 2038 Expires header 37 2039 explicit expiration time 5 2041 F 2042 first-hand 5 2043 fresh 6 2044 freshness lifetime 6 2046 G 2047 Grammar 2048 Age 27 2049 age-value 27 2050 Cache-Control 28 2051 cache-directive 28 2052 cache-extension 28 2053 cache-request-directive 28 2054 cache-response-directive 28 2055 delta-seconds 6 2056 Expires 37 2057 extension-pragma 38 2058 Pragma 38 2059 pragma-directive 38 2060 Vary 38 2061 warn-agent 40 2062 warn-code 40 2063 warn-date 40 2064 warn-text 40 2065 Warning 40 2066 warning-value 40 2068 H 2069 Headers 2070 Age 27 2071 Cache-Control 27 2072 Expires 37 2073 Pragma 38 2074 Vary 38 2075 Warning 39 2076 heuristic expiration time 5 2078 M 2079 max-age 2080 Cache Directive 32 2081 Cache Directive 33 2082 max-stale 2083 Cache Directive 32 2084 min-fresh 2085 Cache Directive 32 2086 must-revalidate 2087 Cache Directive 34 2089 N 2090 no-cache 2091 Cache Directive 29 2092 no-store 2093 Cache Directive 30 2094 no-transform 2095 Cache Directive 35 2097 O 2098 only-if-cached 2099 Cache Directive 34 2101 P 2102 Pragma header 38 2103 private 2104 Cache Directive 29 2105 proxy-revalidate 2106 Cache Directive 35 2107 public 2108 Cache Directive 29 2110 S 2111 s-maxage 2112 Cache Directive 31 2113 semantically transparent 6 2114 stale 6 2116 V 2117 validator 6 2118 Vary header 38 2120 W 2121 Warning header 39 2123 Authors' Addresses 2125 Roy T. Fielding (editor) 2126 Day Software 2127 23 Corporate Plaza DR, Suite 280 2128 Newport Beach, CA 92660 2129 USA 2131 Phone: +1-949-706-5300 2132 Fax: +1-949-706-5305 2133 Email: fielding@gbiv.com 2134 URI: http://roy.gbiv.com/ 2135 Jim Gettys 2136 One Laptop per Child 2137 21 Oak Knoll Road 2138 Carlisle, MA 01741 2139 USA 2141 Email: jg@laptop.org 2142 URI: http://www.laptop.org/ 2144 Jeffrey C. Mogul 2145 Hewlett-Packard Company 2146 HP Labs, Large Scale Systems Group 2147 1501 Page Mill Road, MS 1177 2148 Palo Alto, CA 94304 2149 USA 2151 Email: JeffMogul@acm.org 2153 Henrik Frystyk Nielsen 2154 Microsoft Corporation 2155 1 Microsoft Way 2156 Redmond, WA 98052 2157 USA 2159 Email: henrikn@microsoft.com 2161 Larry Masinter 2162 Adobe Systems, Incorporated 2163 345 Park Ave 2164 San Jose, CA 95110 2165 USA 2167 Email: LMM@acm.org 2168 URI: http://larry.masinter.net/ 2170 Paul J. Leach 2171 Microsoft Corporation 2172 1 Microsoft Way 2173 Redmond, WA 98052 2175 Email: paulle@microsoft.com 2176 Tim Berners-Lee 2177 World Wide Web Consortium 2178 MIT Computer Science and Artificial Intelligence Laboratory 2179 The Stata Center, Building 32 2180 32 Vassar Street 2181 Cambridge, MA 02139 2182 USA 2184 Email: timbl@w3.org 2185 URI: http://www.w3.org/People/Berners-Lee/ 2187 Full Copyright Statement 2189 Copyright (C) The IETF Trust (2007). 2191 This document is subject to the rights, licenses and restrictions 2192 contained in BCP 78, and except as set forth therein, the authors 2193 retain all their rights. 2195 This document and the information contained herein are provided on an 2196 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2197 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2198 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2199 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2200 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2201 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2203 Intellectual Property 2205 The IETF takes no position regarding the validity or scope of any 2206 Intellectual Property Rights or other rights that might be claimed to 2207 pertain to the implementation or use of the technology described in 2208 this document or the extent to which any license under such rights 2209 might or might not be available; nor does it represent that it has 2210 made any independent effort to identify any such rights. Information 2211 on the procedures with respect to rights in RFC documents can be 2212 found in BCP 78 and BCP 79. 2214 Copies of IPR disclosures made to the IETF Secretariat and any 2215 assurances of licenses to be made available, or the result of an 2216 attempt made to obtain a general license or permission for the use of 2217 such proprietary rights by implementers or users of this 2218 specification can be obtained from the IETF on-line IPR repository at 2219 http://www.ietf.org/ipr. 2221 The IETF invites any interested party to bring to its attention any 2222 copyrights, patents or patent applications, or other proprietary 2223 rights that may cover technology that may be required to implement 2224 this standard. Please address the information to the IETF at 2225 ietf-ipr@ietf.org. 2227 Acknowledgment 2229 Funding for the RFC Editor function is provided by the IETF 2230 Administrative Support Activity (IASA).