idnits 2.17.1 draft-ietf-httpbis-p6-cache-04.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 30. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 2324. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2335. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2342. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2348. 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 : ---------------------------------------------------------------------------- No issues found here. 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 (August 29, 2008) is 5712 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) -- Possible downref: Non-RFC (?) normative reference: ref. 'ISO-8859-1' == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p1-messaging-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-04 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-04 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-04 -- Obsolete informational reference (is this intentional?): RFC 1305 (Obsoleted by RFC 5905) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 7 warnings (==), 11 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: 2616 (if approved) J. Gettys 5 Intended status: Standards Track One Laptop per Child 6 Expires: March 2, 2009 J. Mogul 7 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 Y. Lafon, Ed. 17 W3C 18 J. Reschke, Ed. 19 greenbytes 20 August 29, 2008 22 HTTP/1.1, part 6: Caching 23 draft-ietf-httpbis-p6-cache-04 25 Status of this Memo 27 By submitting this Internet-Draft, each author represents that any 28 applicable patent or other IPR claims of which he or she is aware 29 have been or will be disclosed, and any of which he or she becomes 30 aware will be disclosed, in accordance with Section 6 of BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF), its areas, and its working groups. Note that 34 other groups may also distribute working documents as Internet- 35 Drafts. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 The list of current Internet-Drafts can be accessed at 43 http://www.ietf.org/ietf/1id-abstracts.txt. 45 The list of Internet-Draft Shadow Directories can be accessed at 46 http://www.ietf.org/shadow.html. 48 This Internet-Draft will expire on March 2, 2009. 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 Discussion of this draft should take place on the HTTPBIS working 64 group mailing list (ietf-http-wg@w3.org). The current issues list is 65 at and related 66 documents (including fancy diffs) can be found at 67 . 69 The changes in this draft are summarized in Appendix B.4. 71 Table of Contents 73 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 74 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 5 75 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 6 76 1.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 7 77 2. Notational Conventions and Generic Grammar . . . . . . . . . . 8 78 3. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 79 3.1. Cache Correctness . . . . . . . . . . . . . . . . . . . . 8 80 3.2. Warnings . . . . . . . . . . . . . . . . . . . . . . . . . 9 81 3.3. Cache-control Mechanisms . . . . . . . . . . . . . . . . . 10 82 3.4. Explicit User Agent Warnings . . . . . . . . . . . . . . . 10 83 3.5. Exceptions to the Rules and Warnings . . . . . . . . . . . 11 84 3.6. Client-controlled Behavior . . . . . . . . . . . . . . . . 11 85 4. Expiration Model . . . . . . . . . . . . . . . . . . . . . . . 12 86 4.1. Server-Specified Expiration . . . . . . . . . . . . . . . 12 87 4.2. Heuristic Expiration . . . . . . . . . . . . . . . . . . . 13 88 4.3. Age Calculations . . . . . . . . . . . . . . . . . . . . . 13 89 4.4. Expiration Calculations . . . . . . . . . . . . . . . . . 15 90 4.5. Disambiguating Expiration Values . . . . . . . . . . . . . 16 91 4.6. Disambiguating Multiple Responses . . . . . . . . . . . . 17 92 5. Validation Model . . . . . . . . . . . . . . . . . . . . . . . 17 93 6. Response Cacheability . . . . . . . . . . . . . . . . . . . . 18 94 7. Constructing Responses From Caches . . . . . . . . . . . . . . 19 95 7.1. End-to-end and Hop-by-hop Headers . . . . . . . . . . . . 19 96 7.2. Non-modifiable Headers . . . . . . . . . . . . . . . . . . 20 97 7.3. Combining Headers . . . . . . . . . . . . . . . . . . . . 21 98 8. Caching Negotiated Responses . . . . . . . . . . . . . . . . . 22 99 9. Shared and Non-Shared Caches . . . . . . . . . . . . . . . . . 23 100 10. Errors or Incomplete Response Cache Behavior . . . . . . . . . 24 101 11. Side Effects of GET and HEAD . . . . . . . . . . . . . . . . . 24 102 12. Invalidation After Updates or Deletions . . . . . . . . . . . 24 103 13. Write-Through Mandatory . . . . . . . . . . . . . . . . . . . 25 104 14. Cache Replacement . . . . . . . . . . . . . . . . . . . . . . 26 105 15. History Lists . . . . . . . . . . . . . . . . . . . . . . . . 26 106 16. Header Field Definitions . . . . . . . . . . . . . . . . . . . 27 107 16.1. Age . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 108 16.2. Cache-Control . . . . . . . . . . . . . . . . . . . . . . 27 109 16.2.1. What is Cacheable . . . . . . . . . . . . . . . . . . 29 110 16.2.2. What May be Stored by Caches . . . . . . . . . . . . 30 111 16.2.3. Modifications of the Basic Expiration Mechanism . . . 31 112 16.2.4. Cache Revalidation and Reload Controls . . . . . . . 33 113 16.2.5. No-Transform Directive . . . . . . . . . . . . . . . 35 114 16.2.6. Cache Control Extensions . . . . . . . . . . . . . . 36 115 16.3. Expires . . . . . . . . . . . . . . . . . . . . . . . . . 37 116 16.4. Pragma . . . . . . . . . . . . . . . . . . . . . . . . . . 38 117 16.5. Vary . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 118 16.6. Warning . . . . . . . . . . . . . . . . . . . . . . . . . 39 120 17. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 121 17.1. Message Header Registration . . . . . . . . . . . . . . . 42 122 18. Security Considerations . . . . . . . . . . . . . . . . . . . 42 123 19. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 43 124 20. References . . . . . . . . . . . . . . . . . . . . . . . . . . 43 125 20.1. Normative References . . . . . . . . . . . . . . . . . . . 43 126 20.2. Informative References . . . . . . . . . . . . . . . . . . 44 127 Appendix A. Compatibility with Previous Versions . . . . . . . . 44 128 A.1. Changes from RFC 2068 . . . . . . . . . . . . . . . . . . 44 129 A.2. Changes from RFC 2616 . . . . . . . . . . . . . . . . . . 45 130 Appendix B. Change Log (to be removed by RFC Editor before 131 publication) . . . . . . . . . . . . . . . . . . . . 45 132 B.1. Since RFC2616 . . . . . . . . . . . . . . . . . . . . . . 45 133 B.2. Since draft-ietf-httpbis-p6-cache-00 . . . . . . . . . . . 45 134 B.3. Since draft-ietf-httpbis-p6-cache-01 . . . . . . . . . . . 46 135 B.4. Since draft-ietf-httpbis-p6-cache-02 . . . . . . . . . . . 46 136 B.5. Since draft-ietf-httpbis-p6-cache-03 . . . . . . . . . . . 46 137 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49 139 Intellectual Property and Copyright Statements . . . . . . . . . . 52 141 1. Introduction 143 HTTP is typically used for distributed information systems, where 144 performance can be improved by the use of response caches, and 145 includes a number of elements intended to make caching work as well 146 as possible. Because these elements interact with each other, it is 147 useful to describe the caching design of HTTP separately. This 148 document defines aspects of HTTP/1.1 related to caching and reusing 149 response messages. 151 1.1. Purpose 153 An HTTP cache is a local store of response messages and the subsystem 154 that controls its message storage, retrieval, and deletion. A cache 155 stores cacheable responses in order to reduce the response time and 156 network bandwidth consumption on future, equivalent requests. Any 157 client or server may include a cache, though a cache cannot be used 158 by a server that is acting as a tunnel. 160 Caching would be useless if it did not significantly improve 161 performance. The goal of caching in HTTP/1.1 is to reuse a prior 162 response message to satisfy a current request. In some cases, the 163 existing response can be reused without the need for a network 164 request, reducing latency and network round-trips; we use an 165 "expiration" mechanism for this purpose (see Section 4). Even when a 166 new request is required, it is often possible to reuse all or parts 167 of the payload of a prior response to satisfy the request, thereby 168 reducing network bandwidth usage; we use a "validation" mechanism for 169 this purpose (see Section 5). 171 A cache behaves in a "semantically transparent" manner, with respect 172 to a particular response, when its use affects neither the requesting 173 client nor the origin server, except to improve performance. When a 174 cache is semantically transparent, the client receives exactly the 175 same response status and payload that it would have received had its 176 request been handled directly by the origin server. 178 In an ideal world, all interactions with an HTTP cache would be 179 semantically transparent. However, for some resources, semantic 180 transparency is not always necessary and can be effectively traded 181 for the sake of bandwidth scaling, disconnected operation, and high 182 availability. HTTP/1.1 allows origin servers, caches, and clients to 183 explicitly reduce transparency when necessary. However, because non- 184 transparent operation may confuse non-expert users and might be 185 incompatible with certain server applications (such as those for 186 ordering merchandise), the protocol requires that transparency be 187 relaxed 188 o only by an explicit protocol-level request when relaxed by client 189 or origin server 191 o only with an explicit warning to the end user when relaxed by 192 cache or client 194 Therefore, HTTP/1.1 provides these important elements: 196 1. Protocol features that provide full semantic transparency when 197 this is required by all parties. 199 2. Protocol features that allow an origin server or user agent to 200 explicitly request and control non-transparent operation. 202 3. Protocol features that allow a cache to attach warnings to 203 responses that do not preserve the requested approximation of 204 semantic transparency. 206 A basic principle is that it must be possible for the clients to 207 detect any potential relaxation of semantic transparency. 209 Note: The server, cache, or client implementor might be faced with 210 design decisions not explicitly discussed in this specification. 211 If a decision might affect semantic transparency, the implementor 212 ought to err on the side of maintaining transparency unless a 213 careful and complete analysis shows significant benefits in 214 breaking transparency. 216 1.2. Terminology 218 This specification uses a number of terms to refer to the roles 219 played by participants in, and objects of, HTTP caching. 221 cacheable 223 A response is cacheable if a cache is allowed to store a copy of 224 the response message for use in answering subsequent requests. 225 Even when a response is cacheable, there may be additional 226 constraints on whether a cache can use the cached copy for a 227 particular request. 229 first-hand 231 A response is first-hand if it comes directly and without 232 unnecessary delay from the origin server, perhaps via one or more 233 proxies. A response is also first-hand if its validity has just 234 been checked directly with the origin server. 236 explicit expiration time 238 The time at which the origin server intends that an entity should 239 no longer be returned by a cache without further validation. 241 heuristic expiration time 243 An expiration time assigned by a cache when no explicit expiration 244 time is available. 246 age 248 The age of a response is the time since it was sent by, or 249 successfully validated with, the origin server. 251 freshness lifetime 253 The length of time between the generation of a response and its 254 expiration time. 256 fresh 258 A response is fresh if its age has not yet exceeded its freshness 259 lifetime. 261 stale 263 A response is stale if its age has passed its freshness lifetime. 265 validator 267 A protocol element (e.g., an entity tag or a Last-Modified time) 268 that is used to find out whether a cache entry is an equivalent 269 copy of an entity. 271 1.3. Requirements 273 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 274 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 275 document are to be interpreted as described in [RFC2119]. 277 An implementation is not compliant if it fails to satisfy one or more 278 of the MUST or REQUIRED level requirements for the protocols it 279 implements. An implementation that satisfies all the MUST or 280 REQUIRED level and all the SHOULD level requirements for its 281 protocols is said to be "unconditionally compliant"; one that 282 satisfies all the MUST level requirements but not all the SHOULD 283 level requirements for its protocols is said to be "conditionally 284 compliant." 286 2. Notational Conventions and Generic Grammar 288 This specification uses the ABNF syntax defined in Section 2.1 of 289 [Part1] and the core rules defined in Section 2.2 of [Part1]: 290 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 291 5234, see .]] 293 DIGIT = 294 DQUOTE = 295 SP = 297 quoted-string = 298 token = 300 The ABNF rules below are defined in other parts: 302 field-name = 303 HTTP-date = 304 port = 305 pseudonym = 306 uri-host = 308 3. Overview 310 3.1. Cache Correctness 312 A correct cache MUST respond to a request with the most up-to-date 313 response held by the cache that is appropriate to the request (see 314 Sections 4.5, 4.6, and 14) which meets one of the following 315 conditions: 317 1. It has been checked for equivalence with what the origin server 318 would have returned by revalidating the response with the origin 319 server (Section 5); 321 2. It is "fresh enough" (see Section 4). In the default case, this 322 means it meets the least restrictive freshness requirement of the 323 client, origin server, and cache (see Section 16.2); if the 324 origin server so specifies, it is the freshness requirement of 325 the origin server alone. If a stored response is not "fresh 326 enough" by the most restrictive freshness requirement of both the 327 client and the origin server, in carefully considered 328 circumstances the cache MAY still return the response with the 329 appropriate Warning header (see Sections 3.5 and 16.6), unless 330 such a response is prohibited (e.g., by a "no-store" cache- 331 directive, or by a "no-cache" cache-request-directive; see 332 Section 16.2). 334 3. It is an appropriate 304 (Not Modified), 305 (Use Proxy), or 335 error (4xx or 5xx) response message. 337 If the cache can not communicate with the origin server, then a 338 correct cache SHOULD respond as above if the response can be 339 correctly served from the cache; if not it MUST return an error or 340 warning indicating that there was a communication failure. 342 If a cache receives a response (either an entire response, or a 304 343 (Not Modified) response) that it would normally forward to the 344 requesting client, and the received response is no longer fresh, the 345 cache SHOULD forward it to the requesting client without adding a new 346 Warning (but without removing any existing Warning headers). A cache 347 SHOULD NOT attempt to revalidate a response simply because that 348 response became stale in transit; this might lead to an infinite 349 loop. A user agent that receives a stale response without a Warning 350 MAY display a warning indication to the user. 352 3.2. Warnings 354 Whenever a cache returns a response that is neither first-hand nor 355 "fresh enough" (in the sense of condition 2 in Section 3.1), it MUST 356 attach a warning to that effect, using a Warning general-header. The 357 Warning header and the currently defined warnings are described in 358 Section 16.6. The warning allows clients to take appropriate action. 360 Warnings MAY be used for other purposes, both cache-related and 361 otherwise. The use of a warning, rather than an error status code, 362 distinguish these responses from true failures. 364 Warnings are assigned three digit warn-codes. The first digit 365 indicates whether the Warning MUST or MUST NOT be deleted from a 366 stored cache entry after a successful revalidation: 368 1xx Warnings that describe the freshness or revalidation status of 369 the response, and so MUST be deleted after a successful 370 revalidation. 1xx warn-codes MAY be generated by a cache only when 371 validating a cached entry. It MUST NOT be generated by clients. 373 2xx Warnings that describe some aspect of the entity body or entity 374 headers that is not rectified by a revalidation (for example, a 375 lossy compression of the entity bodies) and which MUST NOT be 376 deleted after a successful revalidation. 378 See Section 16.6 for the definitions of the codes themselves. 380 HTTP/1.0 caches will cache all Warnings in responses, without 381 deleting the ones in the first category. Warnings in responses that 382 are passed to HTTP/1.0 caches carry an extra warning-date field, 383 which prevents a future HTTP/1.1 recipient from believing an 384 erroneously cached Warning. 386 Warnings also carry a warning text. The text MAY be in any 387 appropriate natural language (perhaps based on the client's Accept 388 headers), and include an OPTIONAL indication of what character set is 389 used. 391 Multiple warnings MAY be attached to a response (either by the origin 392 server or by a cache), including multiple warnings with the same code 393 number. For example, a server might provide the same warning with 394 texts in both English and Basque. 396 When multiple warnings are attached to a response, it might not be 397 practical or reasonable to display all of them to the user. This 398 version of HTTP does not specify strict priority rules for deciding 399 which warnings to display and in what order, but does suggest some 400 heuristics. 402 3.3. Cache-control Mechanisms 404 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 405 times and validators) are implicit directives to caches. In some 406 cases, a server or client might need to provide explicit directives 407 to the HTTP caches. We use the Cache-Control header for this 408 purpose. 410 The Cache-Control header allows a client or server to transmit a 411 variety of directives in either requests or responses. These 412 directives typically override the default caching algorithms. As a 413 general rule, if there is any apparent conflict between header 414 values, the most restrictive interpretation is applied (that is, the 415 one that is most likely to preserve semantic transparency). However, 416 in some cases, cache-control directives are explicitly specified as 417 weakening the approximation of semantic transparency (for example, 418 "max-stale" or "public"). 420 The cache-control directives are described in detail in Section 16.2. 422 3.4. Explicit User Agent Warnings 424 Many user agents make it possible for users to override the basic 425 caching mechanisms. For example, the user agent might allow the user 426 to specify that cached entities (even explicitly stale ones) are 427 never validated. Or the user agent might habitually add "Cache- 428 Control: max-stale=3600" to every request. The user agent SHOULD NOT 429 default to either non-transparent behavior, or behavior that results 430 in abnormally ineffective caching, but MAY be explicitly configured 431 to do so by an explicit action of the user. 433 If the user has overridden the basic caching mechanisms, the user 434 agent SHOULD explicitly indicate to the user whenever this results in 435 the display of information that might not meet the server's 436 transparency requirements (in particular, if the displayed entity is 437 known to be stale). Since the protocol normally allows the user 438 agent to determine if responses are stale or not, this indication 439 need only be displayed when this actually happens. The indication 440 need not be a dialog box; it could be an icon (for example, a picture 441 of a rotting fish) or some other indicator. 443 If the user has overridden the caching mechanisms in a way that would 444 abnormally reduce the effectiveness of caches, the user agent SHOULD 445 continually indicate this state to the user (for example, by a 446 display of a picture of currency in flames) so that the user does not 447 inadvertently consume excess resources or suffer from excessive 448 latency. 450 3.5. Exceptions to the Rules and Warnings 452 In some cases, the operator of a cache MAY choose to configure it to 453 return stale responses even when not requested by clients. This 454 decision ought not be made lightly, but may be necessary for reasons 455 of availability or performance, especially when the cache is poorly 456 connected to the origin server. Whenever a cache returns a stale 457 response, it MUST mark it as such (using a Warning header) enabling 458 the client software to alert the user that there might be a potential 459 problem. 461 It also allows the user agent to take steps to obtain a first-hand or 462 fresh response. For this reason, a cache SHOULD NOT return a stale 463 response if the client explicitly requests a first-hand or fresh one, 464 unless it is impossible to comply for technical or policy reasons. 466 3.6. Client-controlled Behavior 468 While the origin server (and to a lesser extent, intermediate caches, 469 by their contribution to the age of a response) are the primary 470 source of expiration information, in some cases the client might need 471 to control a cache's decision about whether to return a cached 472 response without validating it. Clients do this using several 473 directives of the Cache-Control header. 475 A client's request MAY specify the maximum age it is willing to 476 accept of an unvalidated response; specifying a value of zero forces 477 the cache(s) to revalidate all responses. A client MAY also specify 478 the minimum time remaining before a response expires. Both of these 479 options increase constraints on the behavior of caches, and so cannot 480 further relax the cache's approximation of semantic transparency. 482 A client MAY also specify that it will accept stale responses, up to 483 some maximum amount of staleness. This loosens the constraints on 484 the caches, and so might violate the origin server's specified 485 constraints on semantic transparency, but might be necessary to 486 support disconnected operation, or high availability in the face of 487 poor connectivity. 489 4. Expiration Model 491 4.1. Server-Specified Expiration 493 HTTP caching works best when caches can entirely avoid making 494 requests to the origin server. The primary mechanism for avoiding 495 requests is for an origin server to provide an explicit expiration 496 time in the future, indicating that a response MAY be used to satisfy 497 subsequent requests. In other words, a cache can return a fresh 498 response without first contacting the server. 500 Our expectation is that servers will assign future explicit 501 expiration times to responses in the belief that the entity is not 502 likely to change, in a semantically significant way, before the 503 expiration time is reached. This normally preserves semantic 504 transparency, as long as the server's expiration times are carefully 505 chosen. 507 The expiration mechanism applies only to responses taken from a cache 508 and not to first-hand responses forwarded immediately to the 509 requesting client. 511 If an origin server wishes to force a semantically transparent cache 512 to validate every request, it MAY assign an explicit expiration time 513 in the past. This means that the response is always stale, and so 514 the cache SHOULD validate it before using it for subsequent requests. 515 See Section 16.2.4 for a more restrictive way to force revalidation. 517 If an origin server wishes to force any HTTP/1.1 cache, no matter how 518 it is configured, to validate every request, it SHOULD use the "must- 519 revalidate" cache-control directive (see Section 16.2). 521 Servers specify explicit expiration times using either the Expires 522 header, or the max-age directive of the Cache-Control header. 524 An expiration time cannot be used to force a user agent to refresh 525 its display or reload a resource; its semantics apply only to caching 526 mechanisms, and such mechanisms need only check a resource's 527 expiration status when a new request for that resource is initiated. 528 See Section 15 for an explanation of the difference between caches 529 and history mechanisms. 531 4.2. Heuristic Expiration 533 Since origin servers do not always provide explicit expiration times, 534 HTTP caches typically assign heuristic expiration times, employing 535 algorithms that use other header values (such as the Last-Modified 536 time) to estimate a plausible expiration time. The HTTP/1.1 537 specification does not provide specific algorithms, but does impose 538 worst-case constraints on their results. Since heuristic expiration 539 times might compromise semantic transparency, they ought to be used 540 cautiously, and we encourage origin servers to provide explicit 541 expiration times as much as possible. 543 4.3. Age Calculations 545 In order to know if a cached entry is fresh, a cache needs to know if 546 its age exceeds its freshness lifetime. We discuss how to calculate 547 the latter in Section 4.4; this section describes how to calculate 548 the age of a response or cache entry. 550 In this discussion, we use the term "now" to mean "the current value 551 of the clock at the host performing the calculation." Hosts that use 552 HTTP, but especially hosts running origin servers and caches, SHOULD 553 use NTP [RFC1305] or some similar protocol to synchronize their 554 clocks to a globally accurate time standard. 556 HTTP/1.1 requires origin servers to send a Date header, if possible, 557 with every response, giving the time at which the response was 558 generated (see Section 8.3 of [Part1]). We use the term "date_value" 559 to denote the value of the Date header, in a form appropriate for 560 arithmetic operations. 562 HTTP/1.1 uses the Age response-header to convey the estimated age of 563 the response message when obtained from a cache. The Age field value 564 is the cache's estimate of the amount of time since the response was 565 generated or revalidated by the origin server. 567 In essence, the Age value is the sum of the time that the response 568 has been resident in each of the caches along the path from the 569 origin server, plus the amount of time it has been in transit along 570 network paths. 572 We use the term "age_value" to denote the value of the Age header, in 573 a form appropriate for arithmetic operations. 575 A response's age can be calculated in two entirely independent ways: 577 1. now minus date_value, if the local clock is reasonably well 578 synchronized to the origin server's clock. If the result is 579 negative, the result is replaced by zero. 581 2. age_value, if all of the caches along the response path implement 582 HTTP/1.1. 584 Given that we have two independent ways to compute the age of a 585 response when it is received, we can combine these as 587 corrected_received_age = max(now - date_value, age_value) 589 and as long as we have either nearly synchronized clocks or all- 590 HTTP/1.1 paths, one gets a reliable (conservative) result. 592 Because of network-imposed delays, some significant interval might 593 pass between the time that a server generates a response and the time 594 it is received at the next outbound cache or client. If uncorrected, 595 this delay could result in improperly low ages. 597 Because the request that resulted in the returned Age value must have 598 been initiated prior to that Age value's generation, we can correct 599 for delays imposed by the network by recording the time at which the 600 request was initiated. Then, when an Age value is received, it MUST 601 be interpreted relative to the time the request was initiated, not 602 the time that the response was received. This algorithm results in 603 conservative behavior no matter how much delay is experienced. So, 604 we compute: 606 corrected_initial_age = corrected_received_age 607 + (now - request_time) 609 where "request_time" is the time (according to the local clock) when 610 the request that elicited this response was sent. 612 Summary of age calculation algorithm, when a cache receives a 613 response: 615 /* 616 * age_value 617 * is the value of Age: header received by the cache with 618 * this response. 619 * date_value 620 * is the value of the origin server's Date: header 621 * request_time 622 * is the (local) time when the cache made the request 623 * that resulted in this cached response 624 * response_time 625 * is the (local) time when the cache received the 626 * response 627 * now 628 * is the current (local) time 629 */ 631 apparent_age = max(0, response_time - date_value); 632 corrected_received_age = max(apparent_age, age_value); 633 response_delay = response_time - request_time; 634 corrected_initial_age = corrected_received_age + response_delay; 635 resident_time = now - response_time; 636 current_age = corrected_initial_age + resident_time; 638 The current_age of a cache entry is calculated by adding the amount 639 of time (in seconds) since the cache entry was last validated by the 640 origin server to the corrected_initial_age. When a response is 641 generated from a cache entry, the cache MUST include a single Age 642 header field in the response with a value equal to the cache entry's 643 current_age. 645 The presence of an Age header field in a response implies that a 646 response is not first-hand. However, the converse is not true, since 647 the lack of an Age header field in a response does not imply that the 648 response is first-hand unless all caches along the request path are 649 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 650 the Age header field). 652 4.4. Expiration Calculations 654 In order to decide whether a response is fresh or stale, we need to 655 compare its freshness lifetime to its age. The age is calculated as 656 described in Section 4.3; this section describes how to calculate the 657 freshness lifetime, and to determine if a response has expired. In 658 the discussion below, the values can be represented in any form 659 appropriate for arithmetic operations. 661 We use the term "expires_value" to denote the value of the Expires 662 header. We use the term "max_age_value" to denote an appropriate 663 value of the number of seconds carried by the "max-age" directive of 664 the Cache-Control header in a response (see Section 16.2.3). 666 The max-age directive takes priority over Expires, so if max-age is 667 present in a response, the calculation is simply: 669 freshness_lifetime = max_age_value 671 Otherwise, if Expires is present in the response, the calculation is: 673 freshness_lifetime = expires_value - date_value 675 Note that neither of these calculations is vulnerable to clock skew, 676 since all of the information comes from the origin server. 678 If none of Expires, Cache-Control: max-age, or Cache-Control: 679 s-maxage (see Section 16.2.3) appears in the response, and the 680 response does not include other restrictions on caching, the cache 681 MAY compute a freshness lifetime using a heuristic. The cache MUST 682 attach Warning 113 to any response whose age is more than 24 hours if 683 such warning has not already been added. 685 Also, if the response does have a Last-Modified time, the heuristic 686 expiration value SHOULD be no more than some fraction of the interval 687 since that time. A typical setting of this fraction might be 10%. 689 The calculation to determine if a response has expired is quite 690 simple: 692 response_is_fresh = (freshness_lifetime > current_age) 694 4.5. Disambiguating Expiration Values 696 Because expiration values are assigned optimistically, it is possible 697 for two caches to contain fresh values for the same resource that are 698 different. 700 If a client performing a retrieval receives a non-first-hand response 701 for a request that was already fresh in its own cache, and the Date 702 header in its existing cache entry is newer than the Date on the new 703 response, then the client MAY ignore the response. If so, it MAY 704 retry the request with a "Cache-Control: max-age=0" directive (see 705 Section 16.2), to force a check with the origin server. 707 If a cache has two fresh responses for the same representation with 708 different validators, it MUST use the one with the more recent Date 709 header. This situation might arise because the cache is pooling 710 responses from other caches, or because a client has asked for a 711 reload or a revalidation of an apparently fresh cache entry. 713 4.6. Disambiguating Multiple Responses 715 Because a client might be receiving responses via multiple paths, so 716 that some responses flow through one set of caches and other 717 responses flow through a different set of caches, a client might 718 receive responses in an order different from that in which the origin 719 server sent them. We would like the client to use the most recently 720 generated response, even if older responses are still apparently 721 fresh. 723 Neither the entity tag nor the expiration value can impose an 724 ordering on responses, since it is possible that a later response 725 intentionally carries an earlier expiration time. The Date values 726 are ordered to a granularity of one second. 728 When a client tries to revalidate a cache entry, and the response it 729 receives contains a Date header that appears to be older than the one 730 for the existing entry, then the client SHOULD repeat the request 731 unconditionally, and include 733 Cache-Control: max-age=0 735 to force any intermediate caches to validate their copies directly 736 with the origin server, or 738 Cache-Control: no-cache 740 to force any intermediate caches to obtain a new copy from the origin 741 server. 743 If the Date values are equal, then the client MAY use either response 744 (or MAY, if it is being extremely prudent, request a new response). 745 Servers MUST NOT depend on clients being able to choose 746 deterministically between responses generated during the same second, 747 if their expiration times overlap. 749 5. Validation Model 751 When a cache has a stale entry that it would like to use as a 752 response to a client's request, it first has to check with the origin 753 server (or possibly an intermediate cache with a fresh response) to 754 see if its cached entry is still usable. We call this "validating" 755 the cache entry. 757 HTTP's conditional request mechanism, defined in [Part4], is used to 758 avoid retransmitting the response payload when the cached entry is 759 valid. When a cached response includes one or more "cache 760 validators," such as the field values of an ETag or Last-Modified 761 header field, then a validating GET request SHOULD be made 762 conditional to those field values. The server checks the conditional 763 request's validator against the current state of the requested 764 resource and, if they match, the server responds with a 304 (Not 765 Modified) status code to indicate that the cached response can be 766 refreshed and reused without retransmitting the response payload. If 767 the validator does not match the current state of the requested 768 resource, then the server returns a full response, including payload, 769 so that the request can be satisfied and the cache entry supplanted 770 without the need for an additional network round-trip. 772 6. Response Cacheability 774 Unless specifically constrained by a cache-control (Section 16.2) 775 directive, a caching system MAY always store a successful response 776 (see Section 10) as a cache entry, MAY return it without validation 777 if it is fresh, and MAY return it after successful validation. If 778 there is neither a cache validator nor an explicit expiration time 779 associated with a response, we do not expect it to be cached, but 780 certain caches MAY violate this expectation (for example, when little 781 or no network connectivity is available). A client can usually 782 detect that such a response was taken from a cache by comparing the 783 Date header to the current time. 785 Note: some HTTP/1.0 caches are known to violate this expectation 786 without providing any Warning. 788 However, in some cases it might be inappropriate for a cache to 789 retain an entity, or to return it in response to a subsequent 790 request. This might be because absolute semantic transparency is 791 deemed necessary by the service author, or because of security or 792 privacy considerations. Certain cache-control directives are 793 therefore provided so that the server can indicate that certain 794 resource entities, or portions thereof, are not to be cached 795 regardless of other considerations. 797 Note that Section 4.1 of [Part7] normally prevents a shared cache 798 from saving and returning a response to a previous request if that 799 request included an Authorization header. 801 A response received with a status code of 200, 203, 206, 300, 301 or 802 410 MAY be stored by a cache and used in reply to a subsequent 803 request, subject to the expiration mechanism, unless a cache-control 804 directive prohibits caching. However, a cache that does not support 805 the Range and Content-Range headers MUST NOT cache 206 (Partial 806 Content) responses. 808 A response received with any other status code (e.g. status codes 302 809 and 307) MUST NOT be returned in a reply to a subsequent request 810 unless there are cache-control directives or another header(s) that 811 explicitly allow it. For example, these include the following: an 812 Expires header (Section 16.3); a "max-age", "s-maxage", "must- 813 revalidate", "proxy-revalidate", "public" or "private" cache-control 814 directive (Section 16.2). 816 7. Constructing Responses From Caches 818 The purpose of an HTTP cache is to store information received in 819 response to requests for use in responding to future requests. In 820 many cases, a cache simply returns the appropriate parts of a 821 response to the requester. However, if the cache holds a cache entry 822 based on a previous response, it might have to combine parts of a new 823 response with what is held in the cache entry. 825 7.1. End-to-end and Hop-by-hop Headers 827 For the purpose of defining the behavior of caches and non-caching 828 proxies, we divide HTTP headers into two categories: 830 o End-to-end headers, which are transmitted to the ultimate 831 recipient of a request or response. End-to-end headers in 832 responses MUST be stored as part of a cache entry and MUST be 833 transmitted in any response formed from a cache entry. 835 o Hop-by-hop headers, which are meaningful only for a single 836 transport-level connection, and are not stored by caches or 837 forwarded by proxies. 839 The following HTTP/1.1 headers are hop-by-hop headers: 841 o Connection 843 o Keep-Alive 845 o Proxy-Authenticate 847 o Proxy-Authorization 849 o TE 850 o Trailer 852 o Transfer-Encoding 854 o Upgrade 856 All other headers defined by HTTP/1.1 are end-to-end headers. 858 Other hop-by-hop headers MUST be listed in a Connection header 859 (Section 8.1 of [Part1]). 861 7.2. Non-modifiable Headers 863 Some features of HTTP/1.1, such as Digest Authentication, depend on 864 the value of certain end-to-end headers. A transparent proxy SHOULD 865 NOT modify an end-to-end header unless the definition of that header 866 requires or specifically allows that. 868 A transparent proxy MUST NOT modify any of the following fields in a 869 request or response, and it MUST NOT add any of these fields if not 870 already present: 872 o Content-Location 874 o Content-MD5 876 o ETag 878 o Last-Modified 880 A transparent proxy MUST NOT modify any of the following fields in a 881 response: 883 o Expires 885 but it MAY add any of these fields if not already present. If an 886 Expires header is added, it MUST be given a field-value identical to 887 that of the Date header in that response. 889 A proxy MUST NOT modify or add any of the following fields in a 890 message that contains the no-transform cache-control directive, or in 891 any request: 893 o Content-Encoding 895 o Content-Range 896 o Content-Type 898 A non-transparent proxy MAY modify or add these fields to a message 899 that does not include no-transform, but if it does so, it MUST add a 900 Warning 214 (Transformation applied) if one does not already appear 901 in the message (see Section 16.6). 903 Warning: unnecessary modification of end-to-end headers might 904 cause authentication failures if stronger authentication 905 mechanisms are introduced in later versions of HTTP. Such 906 authentication mechanisms MAY rely on the values of header fields 907 not listed here. 909 The Content-Length field of a request or response is added or deleted 910 according to the rules in Section 4.4 of [Part1]. A transparent 911 proxy MUST preserve the entity-length (Section 4.2.2 of [Part3]) of 912 the entity-body, although it MAY change the transfer-length (Section 913 4.4 of [Part1]). 915 7.3. Combining Headers 917 When a cache makes a validating request to a server, and the server 918 provides a 304 (Not Modified) response or a 206 (Partial Content) 919 response, the cache then constructs a response to send to the 920 requesting client. 922 If the status code is 304 (Not Modified), the cache uses the entity- 923 body stored in the cache entry as the entity-body of this outgoing 924 response. If the status code is 206 (Partial Content) and the ETag 925 or Last-Modified headers match exactly, the cache MAY combine the 926 contents stored in the cache entry with the new contents received in 927 the response and use the result as the entity-body of this outgoing 928 response, (see Section 5 of [Part5]). 930 The end-to-end headers stored in the cache entry are used for the 931 constructed response, except that 933 o any stored Warning headers with warn-code 1xx (see Section 16.6) 934 MUST be deleted from the cache entry and the forwarded response. 936 o any stored Warning headers with warn-code 2xx MUST be retained in 937 the cache entry and the forwarded response. 939 o any end-to-end headers provided in the 304 or 206 response MUST 940 replace the corresponding headers from the cache entry. 942 Unless the cache decides to remove the cache entry, it MUST also 943 replace the end-to-end headers stored with the cache entry with 944 corresponding headers received in the incoming response, except for 945 Warning headers as described immediately above. If a header field- 946 name in the incoming response matches more than one header in the 947 cache entry, all such old headers MUST be replaced. 949 In other words, the set of end-to-end headers received in the 950 incoming response overrides all corresponding end-to-end headers 951 stored with the cache entry (except for stored Warning headers with 952 warn-code 1xx, which are deleted even if not overridden). 954 Note: this rule allows an origin server to use a 304 (Not 955 Modified) or a 206 (Partial Content) response to update any header 956 associated with a previous response for the same entity or sub- 957 ranges thereof, although it might not always be meaningful or 958 correct to do so. This rule does not allow an origin server to 959 use a 304 (Not Modified) or a 206 (Partial Content) response to 960 entirely delete a header that it had provided with a previous 961 response. 963 8. Caching Negotiated Responses 965 Use of server-driven content negotiation (Section 5.1 of [Part3]), as 966 indicated by the presence of a Vary header field in a response, 967 alters the conditions and procedure by which a cache can use the 968 response for subsequent requests. See Section 16.5 for use of the 969 Vary header field by servers. 971 A server SHOULD use the Vary header field to inform a cache of what 972 request-header fields were used to select among multiple 973 representations of a cacheable response subject to server-driven 974 negotiation. The set of header fields named by the Vary field value 975 is known as the "selecting" request-headers. 977 When the cache receives a subsequent request whose Request-URI 978 specifies one or more cache entries including a Vary header field, 979 the cache MUST NOT use such a cache entry to construct a response to 980 the new request unless all of the selecting request-headers present 981 in the new request match the corresponding stored request-headers in 982 the original request. 984 The selecting request-headers from two requests are defined to match 985 if and only if the selecting request-headers in the first request can 986 be transformed to the selecting request-headers in the second request 987 by adding or removing linear white space (LWS) at places where this 988 is allowed by the corresponding BNF, and/or combining multiple 989 message-header fields with the same field name following the rules 990 about message headers in Section 4.2 of [Part1]. 992 A Vary header field-value of "*" always fails to match and subsequent 993 requests on that resource can only be properly interpreted by the 994 origin server. 996 If the selecting request header fields for the cached entry do not 997 match the selecting request header fields of the new request, then 998 the cache MUST NOT use a cached entry to satisfy the request unless 999 it first relays the new request to the origin server in a conditional 1000 request and the server responds with 304 (Not Modified), including an 1001 entity tag or Content-Location that indicates the entity to be used. 1003 If an entity tag was assigned to a cached representation, the 1004 forwarded request SHOULD be conditional and include the entity tags 1005 in an If-None-Match header field from all its cache entries for the 1006 resource. This conveys to the server the set of entities currently 1007 held by the cache, so that if any one of these entities matches the 1008 requested entity, the server can use the ETag header field in its 304 1009 (Not Modified) response to tell the cache which entry is appropriate. 1010 If the entity-tag of the new response matches that of an existing 1011 entry, the new response SHOULD be used to update the header fields of 1012 the existing entry, and the result MUST be returned to the client. 1014 If any of the existing cache entries contains only partial content 1015 for the associated entity, its entity-tag SHOULD NOT be included in 1016 the If-None-Match header field unless the request is for a range that 1017 would be fully satisfied by that entry. 1019 If a cache receives a successful response whose Content-Location 1020 field matches that of an existing cache entry for the same Request- 1021 URI, whose entity-tag differs from that of the existing entry, and 1022 whose Date is more recent than that of the existing entry, the 1023 existing entry SHOULD NOT be returned in response to future requests 1024 and SHOULD be deleted from the cache. 1026 9. Shared and Non-Shared Caches 1028 For reasons of security and privacy, it is necessary to make a 1029 distinction between "shared" and "non-shared" caches. A non-shared 1030 cache is one that is accessible only to a single user. Accessibility 1031 in this case SHOULD be enforced by appropriate security mechanisms. 1032 All other caches are considered to be "shared." Other sections of 1033 this specification place certain constraints on the operation of 1034 shared caches in order to prevent loss of privacy or failure of 1035 access controls. 1037 10. Errors or Incomplete Response Cache Behavior 1039 A cache that receives an incomplete response (for example, with fewer 1040 bytes of data than specified in a Content-Length header) MAY store 1041 the response. However, the cache MUST treat this as a partial 1042 response. Partial responses MAY be combined as described in Section 1043 5 of [Part5]; the result might be a full response or might still be 1044 partial. A cache MUST NOT return a partial response to a client 1045 without explicitly marking it as such, using the 206 (Partial 1046 Content) status code. A cache MUST NOT return a partial response 1047 using a status code of 200 (OK). 1049 If a cache receives a 5xx response while attempting to revalidate an 1050 entry, it MAY either forward this response to the requesting client, 1051 or act as if the server failed to respond. In the latter case, it 1052 MAY return a previously received response unless the cached entry 1053 includes the "must-revalidate" cache-control directive (see 1054 Section 16.2). 1056 11. Side Effects of GET and HEAD 1058 Unless the origin server explicitly prohibits the caching of their 1059 responses, the application of GET and HEAD methods to any resources 1060 SHOULD NOT have side effects that would lead to erroneous behavior if 1061 these responses are taken from a cache. They MAY still have side 1062 effects, but a cache is not required to consider such side effects in 1063 its caching decisions. Caches are always expected to observe an 1064 origin server's explicit restrictions on caching. 1066 We note one exception to this rule: since some applications have 1067 traditionally used GET and HEAD requests with URLs containing a query 1068 part to perform operations with significant side effects, caches MUST 1069 NOT treat responses to such URIs as fresh unless the server provides 1070 an explicit expiration time. This specifically means that responses 1071 from HTTP/1.0 servers for such URIs SHOULD NOT be taken from a cache. 1072 See Section 8.1.1 of [Part2] for related information. 1074 12. Invalidation After Updates or Deletions 1076 The effect of certain methods performed on a resource at the origin 1077 server might cause one or more existing cache entries to become non- 1078 transparently invalid. That is, although they might continue to be 1079 "fresh," they do not accurately reflect what the origin server would 1080 return for a new request on that resource. 1082 There is no way for HTTP to guarantee that all such cache entries are 1083 marked invalid. For example, the request that caused the change at 1084 the origin server might not have gone through the proxy where a cache 1085 entry is stored. However, several rules help reduce the likelihood 1086 of erroneous behavior. 1088 In this section, the phrase "invalidate an entity" means that the 1089 cache will either remove all instances of that entity from its 1090 storage, or will mark these as "invalid" and in need of a mandatory 1091 revalidation before they can be returned in response to a subsequent 1092 request. 1094 Some HTTP methods MUST cause a cache to invalidate an entity. This 1095 is either the entity referred to by the Request-URI, or by the 1096 Location or Content-Location headers (if present). These methods 1097 are: 1099 o PUT 1101 o DELETE 1103 o POST 1105 An invalidation based on the URI in a Location or Content-Location 1106 header MUST NOT be performed if the host part of that URI differs 1107 from the host part in the Request-URI. This helps prevent denial of 1108 service attacks. 1110 A cache that passes through requests for methods it does not 1111 understand SHOULD invalidate any entities referred to by the Request- 1112 URI. 1114 13. Write-Through Mandatory 1116 All methods that might be expected to cause modifications to the 1117 origin server's resources MUST be written through to the origin 1118 server. This currently includes all methods except for GET and HEAD. 1119 A cache MUST NOT reply to such a request from a client before having 1120 transmitted the request to the inbound server, and having received a 1121 corresponding response from the inbound server. This does not 1122 prevent a proxy cache from sending a 100 (Continue) response before 1123 the inbound server has sent its final reply. 1125 The alternative (known as "write-back" or "copy-back" caching) is not 1126 allowed in HTTP/1.1, due to the difficulty of providing consistent 1127 updates and the problems arising from server, cache, or network 1128 failure prior to write-back. 1130 14. Cache Replacement 1132 If a new cacheable (see Sections 16.2.2, 4.5, 4.6 and 10) response is 1133 received from a resource while any existing responses for the same 1134 resource are cached, the cache SHOULD use the new response to reply 1135 to the current request. It MAY insert it into cache storage and MAY, 1136 if it meets all other requirements, use it to respond to any future 1137 requests that would previously have caused the old response to be 1138 returned. If it inserts the new response into cache storage the 1139 rules in Section 7.3 apply. 1141 Note: a new response that has an older Date header value than 1142 existing cached responses is not cacheable. 1144 15. History Lists 1146 User agents often have history mechanisms, such as "Back" buttons and 1147 history lists, which can be used to redisplay an entity retrieved 1148 earlier in a session. 1150 History mechanisms and caches are different. In particular history 1151 mechanisms SHOULD NOT try to show a semantically transparent view of 1152 the current state of a resource. Rather, a history mechanism is 1153 meant to show exactly what the user saw at the time when the resource 1154 was retrieved. 1156 By default, an expiration time does not apply to history mechanisms. 1157 If the entity is still in storage, a history mechanism SHOULD display 1158 it even if the entity has expired, unless the user has specifically 1159 configured the agent to refresh expired history documents. 1161 This is not to be construed to prohibit the history mechanism from 1162 telling the user that a view might be stale. 1164 Note: if history list mechanisms unnecessarily prevent users from 1165 viewing stale resources, this will tend to force service authors 1166 to avoid using HTTP expiration controls and cache controls when 1167 they would otherwise like to. Service authors may consider it 1168 important that users not be presented with error messages or 1169 warning messages when they use navigation controls (such as BACK) 1170 to view previously fetched resources. Even though sometimes such 1171 resources ought not be cached, or ought to expire quickly, user 1172 interface considerations may force service authors to resort to 1173 other means of preventing caching (e.g. "once-only" URLs) in order 1174 not to suffer the effects of improperly functioning history 1175 mechanisms. 1177 16. Header Field Definitions 1179 This section defines the syntax and semantics of HTTP/1.1 header 1180 fields related to caching. 1182 For entity-header fields, both sender and recipient refer to either 1183 the client or the server, depending on who sends and who receives the 1184 entity. 1186 16.1. Age 1188 The Age response-header field conveys the sender's estimate of the 1189 amount of time since the response (or its revalidation) was generated 1190 at the origin server. A cached response is "fresh" if its age does 1191 not exceed its freshness lifetime. Age values are calculated as 1192 specified in Section 4.3. 1194 Age = "Age" ":" age-value 1195 age-value = delta-seconds 1197 Age values are non-negative decimal integers, representing time in 1198 seconds. 1200 delta-seconds = 1*DIGIT 1202 If a cache receives a value larger than the largest positive integer 1203 it can represent, or if any of its age calculations overflows, it 1204 MUST transmit an Age header with a value of 2147483648 (2^31). An 1205 HTTP/1.1 server that includes a cache MUST include an Age header 1206 field in every response generated from its own cache. Caches SHOULD 1207 use an arithmetic type of at least 31 bits of range. 1209 16.2. Cache-Control 1211 The Cache-Control general-header field is used to specify directives 1212 that MUST be obeyed by all caching mechanisms along the request/ 1213 response chain. The directives specify behavior intended to prevent 1214 caches from adversely interfering with the request or response. 1215 These directives typically override the default caching algorithms. 1216 Cache directives are unidirectional in that the presence of a 1217 directive in a request does not imply that the same directive is to 1218 be given in the response. 1220 Note that HTTP/1.0 caches might not implement Cache-Control and 1221 might only implement Pragma: no-cache (see Section 16.4). 1223 Cache directives MUST be passed through by a proxy or gateway 1224 application, regardless of their significance to that application, 1225 since the directives might be applicable to all recipients along the 1226 request/response chain. It is not possible to specify a cache- 1227 directive for a specific cache. 1229 Cache-Control = "Cache-Control" ":" 1#cache-directive 1231 cache-directive = cache-request-directive 1232 | cache-response-directive 1234 cache-request-directive = 1235 "no-cache" ; Section 16.2.1 1236 | "no-store" ; Section 16.2.2 1237 | "max-age" "=" delta-seconds ; Section 16.2.3, 16.2.4 1238 | "max-stale" [ "=" delta-seconds ] ; Section 16.2.3 1239 | "min-fresh" "=" delta-seconds ; Section 16.2.3 1240 | "no-transform" ; Section 16.2.5 1241 | "only-if-cached" ; Section 16.2.4 1242 | cache-extension ; Section 16.2.6 1244 cache-response-directive = 1245 "public" ; Section 16.2.1 1246 | "private" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1247 | "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1248 | "no-store" ; Section 16.2.2 1249 | "no-transform" ; Section 16.2.5 1250 | "must-revalidate" ; Section 16.2.4 1251 | "proxy-revalidate" ; Section 16.2.4 1252 | "max-age" "=" delta-seconds ; Section 16.2.3 1253 | "s-maxage" "=" delta-seconds ; Section 16.2.3 1254 | cache-extension ; Section 16.2.6 1256 cache-extension = token [ "=" ( token | quoted-string ) ] 1258 When a directive appears without any 1#field-name parameter, the 1259 directive applies to the entire request or response. When such a 1260 directive appears with a 1#field-name parameter, it applies only to 1261 the named field or fields, and not to the rest of the request or 1262 response. This mechanism supports extensibility; implementations of 1263 future versions of HTTP might apply these directives to header fields 1264 not defined in HTTP/1.1. 1266 The cache-control directives can be broken down into these general 1267 categories: 1269 o Restrictions on what are cacheable; these may only be imposed by 1270 the origin server. 1272 o Restrictions on what may be stored by a cache; these may be 1273 imposed by either the origin server or the user agent. 1275 o Modifications of the basic expiration mechanism; these may be 1276 imposed by either the origin server or the user agent. 1278 o Controls over cache revalidation and reload; these may only be 1279 imposed by a user agent. 1281 o Control over transformation of entities. 1283 o Extensions to the caching system. 1285 16.2.1. What is Cacheable 1287 By default, a response is cacheable if the requirements of the 1288 request method, request header fields, and the response status 1289 indicate that it is cacheable. Section 6 summarizes these defaults 1290 for cacheability. The following Cache-Control response directives 1291 allow an origin server to override the default cacheability of a 1292 response: 1294 public 1296 Indicates that the response MAY be cached by any cache, even if it 1297 would normally be non-cacheable or cacheable only within a non- 1298 shared cache. (See also Authorization, Section 4.1 of [Part7], 1299 for additional details.) 1301 private 1303 Indicates that all or part of the response message is intended for 1304 a single user and MUST NOT be cached by a shared cache. This 1305 allows an origin server to state that the specified parts of the 1306 response are intended for only one user and are not a valid 1307 response for requests by other users. A private (non-shared) 1308 cache MAY cache the response. 1310 Note: This usage of the word private only controls where the 1311 response may be cached, and cannot ensure the privacy of the 1312 message content. 1314 no-cache 1316 If the no-cache directive does not specify a field-name, then a 1317 cache MUST NOT use the response to satisfy a subsequent request 1318 without successful revalidation with the origin server. This 1319 allows an origin server to prevent caching even by caches that 1320 have been configured to return stale responses to client requests. 1322 If the no-cache directive does specify one or more field-names, 1323 then a cache MAY use the response to satisfy a subsequent request, 1324 subject to any other restrictions on caching. However, the 1325 specified field-name(s) MUST NOT be sent in the response to a 1326 subsequent request without successful revalidation with the origin 1327 server. This allows an origin server to prevent the re-use of 1328 certain header fields in a response, while still allowing caching 1329 of the rest of the response. 1331 Note: Most HTTP/1.0 caches will not recognize or obey this 1332 directive. 1334 16.2.2. What May be Stored by Caches 1336 no-store 1338 The purpose of the no-store directive is to prevent the 1339 inadvertent release or retention of sensitive information (for 1340 example, on backup tapes). The no-store directive applies to the 1341 entire message, and MAY be sent either in a response or in a 1342 request. If sent in a request, a cache MUST NOT store any part of 1343 either this request or any response to it. If sent in a response, 1344 a cache MUST NOT store any part of either this response or the 1345 request that elicited it. This directive applies to both non- 1346 shared and shared caches. "MUST NOT store" in this context means 1347 that the cache MUST NOT intentionally store the information in 1348 non-volatile storage, and MUST make a best-effort attempt to 1349 remove the information from volatile storage as promptly as 1350 possible after forwarding it. 1352 Even when this directive is associated with a response, users 1353 might explicitly store such a response outside of the caching 1354 system (e.g., with a "Save As" dialog). History buffers MAY store 1355 such responses as part of their normal operation. 1357 The purpose of this directive is to meet the stated requirements 1358 of certain users and service authors who are concerned about 1359 accidental releases of information via unanticipated accesses to 1360 cache data structures. While the use of this directive might 1361 improve privacy in some cases, we caution that it is NOT in any 1362 way a reliable or sufficient mechanism for ensuring privacy. In 1363 particular, malicious or compromised caches might not recognize or 1364 obey this directive, and communications networks might be 1365 vulnerable to eavesdropping. 1367 16.2.3. Modifications of the Basic Expiration Mechanism 1369 The expiration time of an entity MAY be specified by the origin 1370 server using the Expires header (see Section 16.3). Alternatively, 1371 it MAY be specified using the max-age directive in a response. When 1372 the max-age cache-control directive is present in a cached response, 1373 the response is stale if its current age is greater than the age 1374 value given (in seconds) at the time of a new request for that 1375 resource. The max-age directive on a response implies that the 1376 response is cacheable (i.e., "public") unless some other, more 1377 restrictive cache directive is also present. 1379 If a response includes both an Expires header and a max-age 1380 directive, the max-age directive overrides the Expires header, even 1381 if the Expires header is more restrictive. This rule allows an 1382 origin server to provide, for a given response, a longer expiration 1383 time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This 1384 might be useful if certain HTTP/1.0 caches improperly calculate ages 1385 or expiration times, perhaps due to desynchronized clocks. 1387 Many HTTP/1.0 cache implementations will treat an Expires value that 1388 is less than or equal to the response Date value as being equivalent 1389 to the Cache-Control response directive "no-cache". If an HTTP/1.1 1390 cache receives such a response, and the response does not include a 1391 Cache-Control header field, it SHOULD consider the response to be 1392 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 1394 Note: An origin server might wish to use a relatively new HTTP 1395 cache control feature, such as the "private" directive, on a 1396 network including older caches that do not understand that 1397 feature. The origin server will need to combine the new feature 1398 with an Expires field whose value is less than or equal to the 1399 Date value. This will prevent older caches from improperly 1400 caching the response. 1402 s-maxage 1404 If a response includes an s-maxage directive, then for a shared 1405 cache (but not for a private cache), the maximum age specified by 1406 this directive overrides the maximum age specified by either the 1407 max-age directive or the Expires header. The s-maxage directive 1408 also implies the semantics of the proxy-revalidate directive (see 1409 Section 16.2.4), i.e., that the shared cache must not use the 1410 entry after it becomes stale to respond to a subsequent request 1411 without first revalidating it with the origin server. The 1412 s-maxage directive is always ignored by a private cache. 1414 Note that most older caches, not compliant with this specification, 1415 do not implement any cache-control directives. An origin server 1416 wishing to use a cache-control directive that restricts, but does not 1417 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 1418 requirement that the max-age directive overrides the Expires header, 1419 and the fact that pre-HTTP/1.1-compliant caches do not observe the 1420 max-age directive. 1422 Other directives allow a user agent to modify the basic expiration 1423 mechanism. These directives MAY be specified on a request: 1425 max-age 1427 Indicates that the client is willing to accept a response whose 1428 age is no greater than the specified time in seconds. Unless max- 1429 stale directive is also included, the client is not willing to 1430 accept a stale response. 1432 min-fresh 1434 Indicates that the client is willing to accept a response whose 1435 freshness lifetime is no less than its current age plus the 1436 specified time in seconds. That is, the client wants a response 1437 that will still be fresh for at least the specified number of 1438 seconds. 1440 max-stale 1442 Indicates that the client is willing to accept a response that has 1443 exceeded its expiration time. If max-stale is assigned a value, 1444 then the client is willing to accept a response that has exceeded 1445 its expiration time by no more than the specified number of 1446 seconds. If no value is assigned to max-stale, then the client is 1447 willing to accept a stale response of any age. 1449 If a cache returns a stale response, either because of a max-stale 1450 directive on a request, or because the cache is configured to 1451 override the expiration time of a response, the cache MUST attach a 1452 Warning header to the stale response, using Warning 110 (Response is 1453 stale). 1455 A cache MAY be configured to return stale responses without 1456 validation, but only if this does not conflict with any "MUST"-level 1457 requirements concerning cache validation (e.g., a "must-revalidate" 1458 cache-control directive). 1460 If both the new request and the cached entry include "max-age" 1461 directives, then the lesser of the two values is used for determining 1462 the freshness of the cached entry for that request. 1464 16.2.4. Cache Revalidation and Reload Controls 1466 Sometimes a user agent might want or need to insist that a cache 1467 revalidate its cache entry with the origin server (and not just with 1468 the next cache along the path to the origin server), or to reload its 1469 cache entry from the origin server. End-to-end revalidation might be 1470 necessary if either the cache or the origin server has overestimated 1471 the expiration time of the cached response. End-to-end reload may be 1472 necessary if the cache entry has become corrupted for some reason. 1474 End-to-end revalidation may be requested either when the client does 1475 not have its own local cached copy, in which case we call it 1476 "unspecified end-to-end revalidation", or when the client does have a 1477 local cached copy, in which case we call it "specific end-to-end 1478 revalidation." 1480 The client can specify these three kinds of action using Cache- 1481 Control request directives: 1483 End-to-end reload 1485 The request includes a "no-cache" cache-control directive or, for 1486 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 1487 names MUST NOT be included with the no-cache directive in a 1488 request. The server MUST NOT use a cached copy when responding to 1489 such a request. 1491 Specific end-to-end revalidation 1493 The request includes a "max-age=0" cache-control directive, which 1494 forces each cache along the path to the origin server to 1495 revalidate its own entry, if any, with the next cache or server. 1496 The initial request includes a cache-validating conditional with 1497 the client's current validator. 1499 Unspecified end-to-end revalidation 1501 The request includes "max-age=0" cache-control directive, which 1502 forces each cache along the path to the origin server to 1503 revalidate its own entry, if any, with the next cache or server. 1504 The initial request does not include a cache-validating 1505 conditional; the first cache along the path (if any) that holds a 1506 cache entry for this resource includes a cache-validating 1507 conditional with its current validator. 1509 max-age 1510 When an intermediate cache is forced, by means of a max-age=0 1511 directive, to revalidate its own cache entry, and the client has 1512 supplied its own validator in the request, the supplied validator 1513 might differ from the validator currently stored with the cache 1514 entry. In this case, the cache MAY use either validator in making 1515 its own request without affecting semantic transparency. 1517 However, the choice of validator might affect performance. The 1518 best approach is for the intermediate cache to use its own 1519 validator when making its request. If the server replies with 304 1520 (Not Modified), then the cache can return its now validated copy 1521 to the client with a 200 (OK) response. If the server replies 1522 with a new entity and cache validator, however, the intermediate 1523 cache can compare the returned validator with the one provided in 1524 the client's request, using the strong comparison function. If 1525 the client's validator is equal to the origin server's, then the 1526 intermediate cache simply returns 304 (Not Modified). Otherwise, 1527 it returns the new entity with a 200 (OK) response. 1529 If a request includes the no-cache directive, it SHOULD NOT 1530 include min-fresh, max-stale, or max-age. 1532 only-if-cached 1534 In some cases, such as times of extremely poor network 1535 connectivity, a client may want a cache to return only those 1536 responses that it currently has stored, and not to reload or 1537 revalidate with the origin server. To do this, the client may 1538 include the only-if-cached directive in a request. If it receives 1539 this directive, a cache SHOULD either respond using a cached entry 1540 that is consistent with the other constraints of the request, or 1541 respond with a 504 (Gateway Timeout) status. However, if a group 1542 of caches is being operated as a unified system with good internal 1543 connectivity, such a request MAY be forwarded within that group of 1544 caches. 1546 must-revalidate 1548 Because a cache MAY be configured to ignore a server's specified 1549 expiration time, and because a client request MAY include a max- 1550 stale directive (which has a similar effect), the protocol also 1551 includes a mechanism for the origin server to require revalidation 1552 of a cache entry on any subsequent use. When the must-revalidate 1553 directive is present in a response received by a cache, that cache 1554 MUST NOT use the entry after it becomes stale to respond to a 1555 subsequent request without first revalidating it with the origin 1556 server. (I.e., the cache MUST do an end-to-end revalidation every 1557 time, if, based solely on the origin server's Expires or max-age 1558 value, the cached response is stale.) 1560 The must-revalidate directive is necessary to support reliable 1561 operation for certain protocol features. In all circumstances an 1562 HTTP/1.1 cache MUST obey the must-revalidate directive; in 1563 particular, if the cache cannot reach the origin server for any 1564 reason, it MUST generate a 504 (Gateway Timeout) response. 1566 Servers SHOULD send the must-revalidate directive if and only if 1567 failure to revalidate a request on the entity could result in 1568 incorrect operation, such as a silently unexecuted financial 1569 transaction. Recipients MUST NOT take any automated action that 1570 violates this directive, and MUST NOT automatically provide an 1571 unvalidated copy of the entity if revalidation fails. 1573 Although this is not recommended, user agents operating under 1574 severe connectivity constraints MAY violate this directive but, if 1575 so, MUST explicitly warn the user that an unvalidated response has 1576 been provided. The warning MUST be provided on each unvalidated 1577 access, and SHOULD require explicit user confirmation. 1579 proxy-revalidate 1581 The proxy-revalidate directive has the same meaning as the must- 1582 revalidate directive, except that it does not apply to non-shared 1583 user agent caches. It can be used on a response to an 1584 authenticated request to permit the user's cache to store and 1585 later return the response without needing to revalidate it (since 1586 it has already been authenticated once by that user), while still 1587 requiring proxies that service many users to revalidate each time 1588 (in order to make sure that each user has been authenticated). 1589 Note that such authenticated responses also need the public cache 1590 control directive in order to allow them to be cached at all. 1592 16.2.5. No-Transform Directive 1594 no-transform 1596 Implementors of intermediate caches (proxies) have found it useful 1597 to convert the media type of certain entity bodies. A non- 1598 transparent proxy might, for example, convert between image 1599 formats in order to save cache space or to reduce the amount of 1600 traffic on a slow link. 1602 Serious operational problems occur, however, when these 1603 transformations are applied to entity bodies intended for certain 1604 kinds of applications. For example, applications for medical 1605 imaging, scientific data analysis and those using end-to-end 1606 authentication, all depend on receiving an entity body that is bit 1607 for bit identical to the original entity-body. 1609 Therefore, if a message includes the no-transform directive, an 1610 intermediate cache or proxy MUST NOT change those headers that are 1611 listed in Section 7.2 as being subject to the no-transform 1612 directive. This implies that the cache or proxy MUST NOT change 1613 any aspect of the entity-body that is specified by these headers, 1614 including the value of the entity-body itself. 1616 16.2.6. Cache Control Extensions 1618 The Cache-Control header field can be extended through the use of one 1619 or more cache-extension tokens, each with an optional assigned value. 1620 Informational extensions (those which do not require a change in 1621 cache behavior) MAY be added without changing the semantics of other 1622 directives. Behavioral extensions are designed to work by acting as 1623 modifiers to the existing base of cache directives. Both the new 1624 directive and the standard directive are supplied, such that 1625 applications which do not understand the new directive will default 1626 to the behavior specified by the standard directive, and those that 1627 understand the new directive will recognize it as modifying the 1628 requirements associated with the standard directive. In this way, 1629 extensions to the cache-control directives can be made without 1630 requiring changes to the base protocol. 1632 This extension mechanism depends on an HTTP cache obeying all of the 1633 cache-control directives defined for its native HTTP-version, obeying 1634 certain extensions, and ignoring all directives that it does not 1635 understand. 1637 For example, consider a hypothetical new response directive called 1638 community which acts as a modifier to the private directive. We 1639 define this new directive to mean that, in addition to any non-shared 1640 cache, any cache which is shared only by members of the community 1641 named within its value may cache the response. An origin server 1642 wishing to allow the UCI community to use an otherwise private 1643 response in their shared cache(s) could do so by including 1645 Cache-Control: private, community="UCI" 1647 A cache seeing this header field will act correctly even if the cache 1648 does not understand the community cache-extension, since it will also 1649 see and understand the private directive and thus default to the safe 1650 behavior. 1652 Unrecognized cache-directives MUST be ignored; it is assumed that any 1653 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 1654 be combined with standard directives (or the response's default 1655 cacheability) such that the cache behavior will remain minimally 1656 correct even if the cache does not understand the extension(s). 1658 16.3. Expires 1660 The Expires entity-header field gives the date/time after which the 1661 response is considered stale. A stale cache entry may not normally 1662 be returned by a cache (either a proxy cache or a user agent cache) 1663 unless it is first validated with the origin server (or with an 1664 intermediate cache that has a fresh copy of the entity). See 1665 Section 4 for further discussion of the expiration model. 1667 The presence of an Expires field does not imply that the original 1668 resource will change or cease to exist at, before, or after that 1669 time. 1671 The format is an absolute date and time as defined by HTTP-date in 1672 Section 3.3.1 of [Part1]; it MUST be sent in rfc1123-date format. 1674 Expires = "Expires" ":" HTTP-date 1676 An example of its use is 1678 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1680 Note: if a response includes a Cache-Control field with the max- 1681 age directive (see Section 16.2.3), that directive overrides the 1682 Expires field. 1684 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1685 especially including the value "0", as in the past (i.e., "already 1686 expired"). 1688 To mark a response as "already expired," an origin server sends an 1689 Expires date that is equal to the Date header value. (See the rules 1690 for expiration calculations in Section 4.4.) 1692 To mark a response as "never expires," an origin server sends an 1693 Expires date approximately one year from the time the response is 1694 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 1695 year in the future. 1697 The presence of an Expires header field with a date value of some 1698 time in the future on a response that otherwise would by default be 1699 non-cacheable indicates that the response is cacheable, unless 1700 indicated otherwise by a Cache-Control header field (Section 16.2). 1702 16.4. Pragma 1704 The Pragma general-header field is used to include implementation- 1705 specific directives that might apply to any recipient along the 1706 request/response chain. All pragma directives specify optional 1707 behavior from the viewpoint of the protocol; however, some systems 1708 MAY require that behavior be consistent with the directives. 1710 Pragma = "Pragma" ":" 1#pragma-directive 1711 pragma-directive = "no-cache" | extension-pragma 1712 extension-pragma = token [ "=" ( token | quoted-string ) ] 1714 When the no-cache directive is present in a request message, an 1715 application SHOULD forward the request toward the origin server even 1716 if it has a cached copy of what is being requested. This pragma 1717 directive has the same semantics as the no-cache cache-directive (see 1718 Section 16.2) and is defined here for backward compatibility with 1719 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 1720 request is sent to a server not known to be HTTP/1.1 compliant. 1722 Pragma directives MUST be passed through by a proxy or gateway 1723 application, regardless of their significance to that application, 1724 since the directives might be applicable to all recipients along the 1725 request/response chain. It is not possible to specify a pragma for a 1726 specific recipient; however, any pragma directive not relevant to a 1727 recipient SHOULD be ignored by that recipient. 1729 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1730 sent "Cache-Control: no-cache". No new Pragma directives will be 1731 defined in HTTP. 1733 Note: because the meaning of "Pragma: no-cache" as a response- 1734 header field is not actually specified, it does not provide a 1735 reliable replacement for "Cache-Control: no-cache" in a response. 1737 16.5. Vary 1739 The Vary response-header field's value indicates the set of request- 1740 header fields that fully determines, while the response is fresh, 1741 whether a cache is permitted to use the response to reply to a 1742 subsequent request without revalidation. For uncacheable or stale 1743 responses, the Vary field value advises the user agent about the 1744 criteria that were used to select the representation. A Vary field 1745 value of "*" implies that a cache cannot determine from the request 1746 headers of a subsequent request whether this response is the 1747 appropriate representation. See Section 8 for use of the Vary header 1748 field by caches. 1750 Vary = "Vary" ":" ( "*" | 1#field-name ) 1752 An HTTP/1.1 server SHOULD include a Vary header field with any 1753 cacheable response that is subject to server-driven negotiation. 1754 Doing so allows a cache to properly interpret future requests on that 1755 resource and informs the user agent about the presence of negotiation 1756 on that resource. A server MAY include a Vary header field with a 1757 non-cacheable response that is subject to server-driven negotiation, 1758 since this might provide the user agent with useful information about 1759 the dimensions over which the response varies at the time of the 1760 response. 1762 A Vary field value consisting of a list of field-names signals that 1763 the representation selected for the response is based on a selection 1764 algorithm which considers ONLY the listed request-header field values 1765 in selecting the most appropriate representation. A cache MAY assume 1766 that the same selection will be made for future requests with the 1767 same values for the listed field names, for the duration of time for 1768 which the response is fresh. 1770 The field-names given are not limited to the set of standard request- 1771 header fields defined by this specification. Field names are case- 1772 insensitive. 1774 A Vary field value of "*" signals that unspecified parameters not 1775 limited to the request-headers (e.g., the network address of the 1776 client), play a role in the selection of the response representation. 1777 The "*" value MUST NOT be generated by a proxy server; it may only be 1778 generated by an origin server. 1780 16.6. Warning 1782 The Warning general-header field is used to carry additional 1783 information about the status or transformation of a message which 1784 might not be reflected in the message. This information is typically 1785 used to warn about a possible lack of semantic transparency from 1786 caching operations or transformations applied to the entity body of 1787 the message. 1789 Warning headers are sent with responses using: 1791 Warning = "Warning" ":" 1#warning-value 1793 warning-value = warn-code SP warn-agent SP warn-text 1794 [SP warn-date] 1796 warn-code = 3DIGIT 1797 warn-agent = ( uri-host [ ":" port ] ) | pseudonym 1798 ; the name or pseudonym of the server adding 1799 ; the Warning header, for use in debugging 1800 warn-text = quoted-string 1801 warn-date = DQUOTE HTTP-date DQUOTE 1803 A response MAY carry more than one Warning header. 1805 The warn-text SHOULD be in a natural language and character set that 1806 is most likely to be intelligible to the human user receiving the 1807 response. This decision MAY be based on any available knowledge, 1808 such as the location of the cache or user, the Accept-Language field 1809 in a request, the Content-Language field in a response, etc. The 1810 default language is English and the default character set is ISO- 1811 8859-1 ([ISO-8859-1]). 1813 If a character set other than ISO-8859-1 is used, it MUST be encoded 1814 in the warn-text using the method described in [RFC2047]. 1816 Warning headers can in general be applied to any message, however 1817 some specific warn-codes are specific to caches and can only be 1818 applied to response messages. New Warning headers SHOULD be added 1819 after any existing Warning headers. A cache MUST NOT delete any 1820 Warning header that it received with a message. However, if a cache 1821 successfully validates a cache entry, it SHOULD remove any Warning 1822 headers previously attached to that entry except as specified for 1823 specific Warning codes. It MUST then add any Warning headers 1824 received in the validating response. In other words, Warning headers 1825 are those that would be attached to the most recent relevant 1826 response. 1828 When multiple Warning headers are attached to a response, the user 1829 agent ought to inform the user of as many of them as possible, in the 1830 order that they appear in the response. If it is not possible to 1831 inform the user of all of the warnings, the user agent SHOULD follow 1832 these heuristics: 1834 o Warnings that appear early in the response take priority over 1835 those appearing later in the response. 1837 o Warnings in the user's preferred character set take priority over 1838 warnings in other character sets but with identical warn-codes and 1839 warn-agents. 1841 Systems that generate multiple Warning headers SHOULD order them with 1842 this user agent behavior in mind. 1844 Requirements for the behavior of caches with respect to Warnings are 1845 stated in Section 3.2. 1847 This is a list of the currently-defined warn-codes, each with a 1848 recommended warn-text in English, and a description of its meaning. 1850 110 Response is stale 1852 MUST be included whenever the returned response is stale. 1854 111 Revalidation failed 1856 MUST be included if a cache returns a stale response because an 1857 attempt to revalidate the response failed, due to an inability to 1858 reach the server. 1860 112 Disconnected operation 1862 SHOULD be included if the cache is intentionally disconnected from 1863 the rest of the network for a period of time. 1865 113 Heuristic expiration 1867 MUST be included if the cache heuristically chose a freshness 1868 lifetime greater than 24 hours and the response's age is greater 1869 than 24 hours. 1871 199 Miscellaneous warning 1873 The warning text MAY include arbitrary information to be presented 1874 to a human user, or logged. A system receiving this warning MUST 1875 NOT take any automated action, besides presenting the warning to 1876 the user. 1878 214 Transformation applied 1880 MUST be added by an intermediate cache or proxy if it applies any 1881 transformation changing the content-coding (as specified in the 1882 Content-Encoding header) or media-type (as specified in the 1883 Content-Type header) of the response, or the entity-body of the 1884 response, unless this Warning code already appears in the 1885 response. 1887 299 Miscellaneous persistent warning 1889 The warning text MAY include arbitrary information to be presented 1890 to a human user, or logged. A system receiving this warning MUST 1891 NOT take any automated action. 1893 If an implementation sends a message with one or more Warning headers 1894 whose version is HTTP/1.0 or lower, then the sender MUST include in 1895 each warning-value a warn-date that matches the date in the response. 1897 If an implementation receives a message with a warning-value that 1898 includes a warn-date, and that warn-date is different from the Date 1899 value in the response, then that warning-value MUST be deleted from 1900 the message before storing, forwarding, or using it. (This prevents 1901 bad consequences of naive caching of Warning header fields.) If all 1902 of the warning-values are deleted for this reason, the Warning header 1903 MUST be deleted as well. 1905 17. IANA Considerations 1907 17.1. Message Header Registration 1909 The Message Header Registry located at should be 1911 updated with the permanent registrations below (see [RFC3864]): 1913 +-------------------+----------+----------+--------------+ 1914 | Header Field Name | Protocol | Status | Reference | 1915 +-------------------+----------+----------+--------------+ 1916 | Age | http | standard | Section 16.1 | 1917 | Cache-Control | http | standard | Section 16.2 | 1918 | Expires | http | standard | Section 16.3 | 1919 | Pragma | http | standard | Section 16.4 | 1920 | Vary | http | standard | Section 16.5 | 1921 | Warning | http | standard | Section 16.6 | 1922 +-------------------+----------+----------+--------------+ 1924 The change controller is: "IETF (iesg@ietf.org) - Internet 1925 Engineering Task Force". 1927 18. Security Considerations 1929 Caching proxies provide additional potential vulnerabilities, since 1930 the contents of the cache represent an attractive target for 1931 malicious exploitation. Because cache contents persist after an HTTP 1932 request is complete, an attack on the cache can reveal information 1933 long after a user believes that the information has been removed from 1934 the network. Therefore, cache contents should be protected as 1935 sensitive information. 1937 19. Acknowledgments 1939 Much of the content and presentation of the caching design is due to 1940 suggestions and comments from individuals including: Shel Kaphan, 1941 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1943 20. References 1945 20.1. Normative References 1947 [ISO-8859-1] 1948 International Organization for Standardization, 1949 "Information technology -- 8-bit single-byte coded graphic 1950 character sets -- Part 1: Latin alphabet No. 1", ISO/ 1951 IEC 8859-1:1998, 1998. 1953 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1954 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1955 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1956 and Message Parsing", draft-ietf-httpbis-p1-messaging-04 1957 (work in progress), August 2008. 1959 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1960 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1961 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1962 Semantics", draft-ietf-httpbis-p2-semantics-04 (work in 1963 progress), August 2008. 1965 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1966 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1967 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1968 and Content Negotiation", draft-ietf-httpbis-p3-payload-04 1969 (work in progress), August 2008. 1971 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1972 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1973 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1974 Requests", draft-ietf-httpbis-p4-conditional-04 (work in 1975 progress), August 2008. 1977 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1978 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1979 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1980 Partial Responses", draft-ietf-httpbis-p5-range-04 (work 1981 in progress), August 2008. 1983 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1984 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1985 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1986 draft-ietf-httpbis-p7-auth-04 (work in progress), 1987 August 2008. 1989 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1990 Part Three: Message Header Extensions for Non-ASCII Text", 1991 RFC 2047, November 1996. 1993 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1994 Requirement Levels", BCP 14, RFC 2119, March 1997. 1996 20.2. Informative References 1998 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1999 Specification, Implementation", RFC 1305, March 1992. 2001 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2002 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2003 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2005 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2006 Procedures for Message Header Fields", BCP 90, RFC 3864, 2007 September 2004. 2009 Appendix A. Compatibility with Previous Versions 2011 A.1. Changes from RFC 2068 2013 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 2014 was introduced to add this missing case. (Sections 6, 16.2, 16.2.3) 2016 Transfer-coding and message lengths all interact in ways that 2017 required fixing exactly when chunked encoding is used (to allow for 2018 transfer encoding that may not be self delimiting); it was important 2019 to straighten out exactly how message lengths are computed. 2020 (Section 7.2, see also [Part1], [Part3] and [Part5]) 2022 Proxies should be able to add Content-Length when appropriate. 2023 (Section 7.2) 2025 Range request responses would become very verbose if all meta-data 2026 were always returned; by allowing the server to only send needed 2027 headers in a 206 response, this problem can be avoided. 2028 (Section 7.3) 2030 The Cache-Control: max-age directive was not properly defined for 2031 responses. (Section 16.2.3) 2033 Warnings could be cached incorrectly, or not updated appropriately. 2034 (Section 3.2, 4.4, 7.2, 7.3, 16.2.3, and 16.6) Warning also needed to 2035 be a general header, as PUT or other methods may have need for it in 2036 requests. 2038 A.2. Changes from RFC 2616 2040 Clarify denial of service attack avoidance requirement. (Section 12) 2042 Appendix B. Change Log (to be removed by RFC Editor before publication) 2044 B.1. Since RFC2616 2046 Extracted relevant partitions from [RFC2616]. 2048 B.2. Since draft-ietf-httpbis-p6-cache-00 2050 Closed issues: 2052 o : "Trailer" 2053 () 2055 o : 2056 "Invalidation after Update or Delete" 2057 () 2059 o : "Normative 2060 and Informative references" 2062 o : "Date 2063 reference typo" 2065 o : 2066 "Connection header text" 2068 o : 2069 "Informative references" 2071 o : 2072 "ISO-8859-1 Reference" 2074 o : "Normative 2075 up-to-date references" 2077 o : "typo in 2078 13.2.2" 2080 Other changes: 2082 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 2083 on ) 2085 B.3. Since draft-ietf-httpbis-p6-cache-01 2087 Closed issues: 2089 o : "rel_path 2090 not used" 2092 Other changes: 2094 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 2095 in progress on 2096 ) 2098 o Add explicit references to BNF syntax and rules imported from 2099 other parts of the specification. 2101 B.4. Since draft-ietf-httpbis-p6-cache-02 2103 Ongoing work on IANA Message Header Registration 2104 (): 2106 o Reference RFC 3984, and update header registrations for headers 2107 defined in this document. 2109 B.5. Since draft-ietf-httpbis-p6-cache-03 2111 Closed issues: 2113 o : "Vary 2114 header classification" 2116 Index 2118 A 2119 age 7 2120 Age header 27 2122 C 2123 cache 5 2124 Cache Directives 2125 max-age 32-33 2126 max-stale 32 2127 min-fresh 32 2128 must-revalidate 34 2129 no-cache 29 2130 no-store 30 2131 no-transform 35 2132 only-if-cached 34 2133 private 29 2134 proxy-revalidate 35 2135 public 29 2136 s-maxage 31 2137 Cache-Control header 27 2138 cacheable 6 2140 E 2141 Expires header 37 2142 explicit expiration time 7 2144 F 2145 first-hand 6 2146 fresh 7 2147 freshness lifetime 7 2149 G 2150 Grammar 2151 Age 27 2152 age-value 27 2153 Cache-Control 28 2154 cache-directive 28 2155 cache-extension 28 2156 cache-request-directive 28 2157 cache-response-directive 28 2158 delta-seconds 27 2159 Expires 37 2160 extension-pragma 38 2161 Pragma 38 2162 pragma-directive 38 2163 Vary 38 2164 warn-agent 40 2165 warn-code 40 2166 warn-date 40 2167 warn-text 40 2168 Warning 40 2169 warning-value 40 2171 H 2172 Headers 2173 Age 27 2174 Cache-Control 27 2175 Expires 37 2176 Pragma 38 2177 Vary 38 2178 Warning 39 2179 heuristic expiration time 7 2181 M 2182 max-age 2183 Cache Directive 32-33 2184 max-stale 2185 Cache Directive 32 2186 min-fresh 2187 Cache Directive 32 2188 must-revalidate 2189 Cache Directive 34 2191 N 2192 no-cache 2193 Cache Directive 29 2194 no-store 2195 Cache Directive 30 2196 no-transform 2197 Cache Directive 35 2199 O 2200 only-if-cached 2201 Cache Directive 34 2203 P 2204 Pragma header 38 2205 private 2206 Cache Directive 29 2207 proxy-revalidate 2208 Cache Directive 35 2209 public 2210 Cache Directive 29 2212 S 2213 s-maxage 2214 Cache Directive 31 2215 semantically transparent 5 2216 stale 7 2218 V 2219 validator 7 2220 Vary header 38 2222 W 2223 Warning header 39 2225 Authors' Addresses 2227 Roy T. Fielding (editor) 2228 Day Software 2229 23 Corporate Plaza DR, Suite 280 2230 Newport Beach, CA 92660 2231 USA 2233 Phone: +1-949-706-5300 2234 Fax: +1-949-706-5305 2235 Email: fielding@gbiv.com 2236 URI: http://roy.gbiv.com/ 2238 Jim Gettys 2239 One Laptop per Child 2240 21 Oak Knoll Road 2241 Carlisle, MA 01741 2242 USA 2244 Email: jg@laptop.org 2245 URI: http://www.laptop.org/ 2247 Jeffrey C. Mogul 2248 Hewlett-Packard Company 2249 HP Labs, Large Scale Systems Group 2250 1501 Page Mill Road, MS 1177 2251 Palo Alto, CA 94304 2252 USA 2254 Email: JeffMogul@acm.org 2255 Henrik Frystyk Nielsen 2256 Microsoft Corporation 2257 1 Microsoft Way 2258 Redmond, WA 98052 2259 USA 2261 Email: henrikn@microsoft.com 2263 Larry Masinter 2264 Adobe Systems, Incorporated 2265 345 Park Ave 2266 San Jose, CA 95110 2267 USA 2269 Email: LMM@acm.org 2270 URI: http://larry.masinter.net/ 2272 Paul J. Leach 2273 Microsoft Corporation 2274 1 Microsoft Way 2275 Redmond, WA 98052 2277 Email: paulle@microsoft.com 2279 Tim Berners-Lee 2280 World Wide Web Consortium 2281 MIT Computer Science and Artificial Intelligence Laboratory 2282 The Stata Center, Building 32 2283 32 Vassar Street 2284 Cambridge, MA 02139 2285 USA 2287 Email: timbl@w3.org 2288 URI: http://www.w3.org/People/Berners-Lee/ 2289 Yves Lafon (editor) 2290 World Wide Web Consortium 2291 W3C / ERCIM 2292 2004, rte des Lucioles 2293 Sophia-Antipolis, AM 06902 2294 France 2296 Email: ylafon@w3.org 2297 URI: http://www.raubacapeu.net/people/yves/ 2299 Julian F. Reschke (editor) 2300 greenbytes GmbH 2301 Hafenweg 16 2302 Muenster, NW 48155 2303 Germany 2305 Phone: +49 251 2807760 2306 Fax: +49 251 2807761 2307 Email: julian.reschke@greenbytes.de 2308 URI: http://greenbytes.de/tech/webdav/ 2310 Full Copyright Statement 2312 Copyright (C) The IETF Trust (2008). 2314 This document is subject to the rights, licenses and restrictions 2315 contained in BCP 78, and except as set forth therein, the authors 2316 retain all their rights. 2318 This document and the information contained herein are provided on an 2319 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2320 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2321 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2322 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2323 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2324 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2326 Intellectual Property 2328 The IETF takes no position regarding the validity or scope of any 2329 Intellectual Property Rights or other rights that might be claimed to 2330 pertain to the implementation or use of the technology described in 2331 this document or the extent to which any license under such rights 2332 might or might not be available; nor does it represent that it has 2333 made any independent effort to identify any such rights. Information 2334 on the procedures with respect to rights in RFC documents can be 2335 found in BCP 78 and BCP 79. 2337 Copies of IPR disclosures made to the IETF Secretariat and any 2338 assurances of licenses to be made available, or the result of an 2339 attempt made to obtain a general license or permission for the use of 2340 such proprietary rights by implementers or users of this 2341 specification can be obtained from the IETF on-line IPR repository at 2342 http://www.ietf.org/ipr. 2344 The IETF invites any interested party to bring to its attention any 2345 copyrights, patents or patent applications, or other proprietary 2346 rights that may cover technology that may be required to implement 2347 this standard. Please address the information to the IETF at 2348 ietf-ipr@ietf.org.