idnits 2.17.1 draft-ietf-httpbis-p6-cache-03.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 2315. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2326. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2333. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2339. 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 (June 17, 2008) is 5791 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-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p2-semantics-03 == Outdated reference: A later version (-20) exists of draft-ietf-httpbis-p3-payload-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p4-conditional-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p5-range-03 == Outdated reference: A later version (-26) exists of draft-ietf-httpbis-p7-auth-03 -- 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: December 19, 2008 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 June 17, 2008 22 HTTP/1.1, part 6: Caching 23 draft-ietf-httpbis-p6-cache-03 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 December 19, 2008. 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 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 137 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49 138 Intellectual Property and Copyright Statements . . . . . . . . . . 52 140 1. Introduction 142 HTTP is typically used for distributed information systems, where 143 performance can be improved by the use of response caches, and 144 includes a number of elements intended to make caching work as well 145 as possible. Because these elements interact with each other, it is 146 useful to describe the caching design of HTTP separately. This 147 document defines aspects of HTTP/1.1 related to caching and reusing 148 response messages. 150 1.1. Purpose 152 An HTTP cache is a local store of response messages and the subsystem 153 that controls its message storage, retrieval, and deletion. A cache 154 stores cacheable responses in order to reduce the response time and 155 network bandwidth consumption on future, equivalent requests. Any 156 client or server may include a cache, though a cache cannot be used 157 by a server that is acting as a tunnel. 159 Caching would be useless if it did not significantly improve 160 performance. The goal of caching in HTTP/1.1 is to reuse a prior 161 response message to satisfy a current request. In some cases, the 162 existing response can be reused without the need for a network 163 request, reducing latency and network round-trips; we use an 164 "expiration" mechanism for this purpose (see Section 4). Even when a 165 new request is required, it is often possible to reuse all or parts 166 of the payload of a prior response to satisfy the request, thereby 167 reducing network bandwidth usage; we use a "validation" mechanism for 168 this purpose (see Section 5). 170 A cache behaves in a "semantically transparent" manner, with respect 171 to a particular response, when its use affects neither the requesting 172 client nor the origin server, except to improve performance. When a 173 cache is semantically transparent, the client receives exactly the 174 same response status and payload that it would have received had its 175 request been handled directly by the origin server. 177 In an ideal world, all interactions with an HTTP cache would be 178 semantically transparent. However, for some resources, semantic 179 transparency is not always necessary and can be effectively traded 180 for the sake of bandwidth scaling, disconnected operation, and high 181 availability. HTTP/1.1 allows origin servers, caches, and clients to 182 explicitly reduce transparency when necessary. However, because non- 183 transparent operation may confuse non-expert users and might be 184 incompatible with certain server applications (such as those for 185 ordering merchandise), the protocol requires that transparency be 186 relaxed 187 o only by an explicit protocol-level request when relaxed by client 188 or origin server 190 o only with an explicit warning to the end user when relaxed by 191 cache or client 193 Therefore, HTTP/1.1 provides these important elements: 195 1. Protocol features that provide full semantic transparency when 196 this is required by all parties. 198 2. Protocol features that allow an origin server or user agent to 199 explicitly request and control non-transparent operation. 201 3. Protocol features that allow a cache to attach warnings to 202 responses that do not preserve the requested approximation of 203 semantic transparency. 205 A basic principle is that it must be possible for the clients to 206 detect any potential relaxation of semantic transparency. 208 Note: The server, cache, or client implementor might be faced with 209 design decisions not explicitly discussed in this specification. 210 If a decision might affect semantic transparency, the implementor 211 ought to err on the side of maintaining transparency unless a 212 careful and complete analysis shows significant benefits in 213 breaking transparency. 215 1.2. Terminology 217 This specification uses a number of terms to refer to the roles 218 played by participants in, and objects of, HTTP caching. 220 cacheable 222 A response is cacheable if a cache is allowed to store a copy of 223 the response message for use in answering subsequent requests. 224 Even when a response is cacheable, there may be additional 225 constraints on whether a cache can use the cached copy for a 226 particular request. 228 first-hand 230 A response is first-hand if it comes directly and without 231 unnecessary delay from the origin server, perhaps via one or more 232 proxies. A response is also first-hand if its validity has just 233 been checked directly with the origin server. 235 explicit expiration time 237 The time at which the origin server intends that an entity should 238 no longer be returned by a cache without further validation. 240 heuristic expiration time 242 An expiration time assigned by a cache when no explicit expiration 243 time is available. 245 age 247 The age of a response is the time since it was sent by, or 248 successfully validated with, the origin server. 250 freshness lifetime 252 The length of time between the generation of a response and its 253 expiration time. 255 fresh 257 A response is fresh if its age has not yet exceeded its freshness 258 lifetime. 260 stale 262 A response is stale if its age has passed its freshness lifetime. 264 validator 266 A protocol element (e.g., an entity tag or a Last-Modified time) 267 that is used to find out whether a cache entry is an equivalent 268 copy of an entity. 270 1.3. Requirements 272 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 273 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 274 document are to be interpreted as described in [RFC2119]. 276 An implementation is not compliant if it fails to satisfy one or more 277 of the MUST or REQUIRED level requirements for the protocols it 278 implements. An implementation that satisfies all the MUST or 279 REQUIRED level and all the SHOULD level requirements for its 280 protocols is said to be "unconditionally compliant"; one that 281 satisfies all the MUST level requirements but not all the SHOULD 282 level requirements for its protocols is said to be "conditionally 283 compliant." 285 2. Notational Conventions and Generic Grammar 287 This specification uses the ABNF syntax defined in Section 2.1 of 288 [Part1] and the core rules defined in Section 2.2 of [Part1]: 289 [[abnf.dep: ABNF syntax and basic rules will be adopted from RFC 290 5234, see .]] 292 DIGIT = 293 DQUOTE = 294 SP = 296 quoted-string = 297 token = 299 The ABNF rules below are defined in other parts: 301 field-name = 302 HTTP-date = 303 port = 304 pseudonym = 305 uri-host = 307 3. Overview 309 3.1. Cache Correctness 311 A correct cache MUST respond to a request with the most up-to-date 312 response held by the cache that is appropriate to the request (see 313 Sections 4.5, 4.6, and 14) which meets one of the following 314 conditions: 316 1. It has been checked for equivalence with what the origin server 317 would have returned by revalidating the response with the origin 318 server (Section 5); 320 2. It is "fresh enough" (see Section 4). In the default case, this 321 means it meets the least restrictive freshness requirement of the 322 client, origin server, and cache (see Section 16.2); if the 323 origin server so specifies, it is the freshness requirement of 324 the origin server alone. If a stored response is not "fresh 325 enough" by the most restrictive freshness requirement of both the 326 client and the origin server, in carefully considered 327 circumstances the cache MAY still return the response with the 328 appropriate Warning header (see Sections 3.5 and 16.6), unless 329 such a response is prohibited (e.g., by a "no-store" cache- 330 directive, or by a "no-cache" cache-request-directive; see 331 Section 16.2). 333 3. It is an appropriate 304 (Not Modified), 305 (Use Proxy), or 334 error (4xx or 5xx) response message. 336 If the cache can not communicate with the origin server, then a 337 correct cache SHOULD respond as above if the response can be 338 correctly served from the cache; if not it MUST return an error or 339 warning indicating that there was a communication failure. 341 If a cache receives a response (either an entire response, or a 304 342 (Not Modified) response) that it would normally forward to the 343 requesting client, and the received response is no longer fresh, the 344 cache SHOULD forward it to the requesting client without adding a new 345 Warning (but without removing any existing Warning headers). A cache 346 SHOULD NOT attempt to revalidate a response simply because that 347 response became stale in transit; this might lead to an infinite 348 loop. A user agent that receives a stale response without a Warning 349 MAY display a warning indication to the user. 351 3.2. Warnings 353 Whenever a cache returns a response that is neither first-hand nor 354 "fresh enough" (in the sense of condition 2 in Section 3.1), it MUST 355 attach a warning to that effect, using a Warning general-header. The 356 Warning header and the currently defined warnings are described in 357 Section 16.6. The warning allows clients to take appropriate action. 359 Warnings MAY be used for other purposes, both cache-related and 360 otherwise. The use of a warning, rather than an error status code, 361 distinguish these responses from true failures. 363 Warnings are assigned three digit warn-codes. The first digit 364 indicates whether the Warning MUST or MUST NOT be deleted from a 365 stored cache entry after a successful revalidation: 367 1xx Warnings that describe the freshness or revalidation status of 368 the response, and so MUST be deleted after a successful 369 revalidation. 1xx warn-codes MAY be generated by a cache only when 370 validating a cached entry. It MUST NOT be generated by clients. 372 2xx Warnings that describe some aspect of the entity body or entity 373 headers that is not rectified by a revalidation (for example, a 374 lossy compression of the entity bodies) and which MUST NOT be 375 deleted after a successful revalidation. 377 See Section 16.6 for the definitions of the codes themselves. 379 HTTP/1.0 caches will cache all Warnings in responses, without 380 deleting the ones in the first category. Warnings in responses that 381 are passed to HTTP/1.0 caches carry an extra warning-date field, 382 which prevents a future HTTP/1.1 recipient from believing an 383 erroneously cached Warning. 385 Warnings also carry a warning text. The text MAY be in any 386 appropriate natural language (perhaps based on the client's Accept 387 headers), and include an OPTIONAL indication of what character set is 388 used. 390 Multiple warnings MAY be attached to a response (either by the origin 391 server or by a cache), including multiple warnings with the same code 392 number. For example, a server might provide the same warning with 393 texts in both English and Basque. 395 When multiple warnings are attached to a response, it might not be 396 practical or reasonable to display all of them to the user. This 397 version of HTTP does not specify strict priority rules for deciding 398 which warnings to display and in what order, but does suggest some 399 heuristics. 401 3.3. Cache-control Mechanisms 403 The basic cache mechanisms in HTTP/1.1 (server-specified expiration 404 times and validators) are implicit directives to caches. In some 405 cases, a server or client might need to provide explicit directives 406 to the HTTP caches. We use the Cache-Control header for this 407 purpose. 409 The Cache-Control header allows a client or server to transmit a 410 variety of directives in either requests or responses. These 411 directives typically override the default caching algorithms. As a 412 general rule, if there is any apparent conflict between header 413 values, the most restrictive interpretation is applied (that is, the 414 one that is most likely to preserve semantic transparency). However, 415 in some cases, cache-control directives are explicitly specified as 416 weakening the approximation of semantic transparency (for example, 417 "max-stale" or "public"). 419 The cache-control directives are described in detail in Section 16.2. 421 3.4. Explicit User Agent Warnings 423 Many user agents make it possible for users to override the basic 424 caching mechanisms. For example, the user agent might allow the user 425 to specify that cached entities (even explicitly stale ones) are 426 never validated. Or the user agent might habitually add "Cache- 427 Control: max-stale=3600" to every request. The user agent SHOULD NOT 428 default to either non-transparent behavior, or behavior that results 429 in abnormally ineffective caching, but MAY be explicitly configured 430 to do so by an explicit action of the user. 432 If the user has overridden the basic caching mechanisms, the user 433 agent SHOULD explicitly indicate to the user whenever this results in 434 the display of information that might not meet the server's 435 transparency requirements (in particular, if the displayed entity is 436 known to be stale). Since the protocol normally allows the user 437 agent to determine if responses are stale or not, this indication 438 need only be displayed when this actually happens. The indication 439 need not be a dialog box; it could be an icon (for example, a picture 440 of a rotting fish) or some other indicator. 442 If the user has overridden the caching mechanisms in a way that would 443 abnormally reduce the effectiveness of caches, the user agent SHOULD 444 continually indicate this state to the user (for example, by a 445 display of a picture of currency in flames) so that the user does not 446 inadvertently consume excess resources or suffer from excessive 447 latency. 449 3.5. Exceptions to the Rules and Warnings 451 In some cases, the operator of a cache MAY choose to configure it to 452 return stale responses even when not requested by clients. This 453 decision ought not be made lightly, but may be necessary for reasons 454 of availability or performance, especially when the cache is poorly 455 connected to the origin server. Whenever a cache returns a stale 456 response, it MUST mark it as such (using a Warning header) enabling 457 the client software to alert the user that there might be a potential 458 problem. 460 It also allows the user agent to take steps to obtain a first-hand or 461 fresh response. For this reason, a cache SHOULD NOT return a stale 462 response if the client explicitly requests a first-hand or fresh one, 463 unless it is impossible to comply for technical or policy reasons. 465 3.6. Client-controlled Behavior 467 While the origin server (and to a lesser extent, intermediate caches, 468 by their contribution to the age of a response) are the primary 469 source of expiration information, in some cases the client might need 470 to control a cache's decision about whether to return a cached 471 response without validating it. Clients do this using several 472 directives of the Cache-Control header. 474 A client's request MAY specify the maximum age it is willing to 475 accept of an unvalidated response; specifying a value of zero forces 476 the cache(s) to revalidate all responses. A client MAY also specify 477 the minimum time remaining before a response expires. Both of these 478 options increase constraints on the behavior of caches, and so cannot 479 further relax the cache's approximation of semantic transparency. 481 A client MAY also specify that it will accept stale responses, up to 482 some maximum amount of staleness. This loosens the constraints on 483 the caches, and so might violate the origin server's specified 484 constraints on semantic transparency, but might be necessary to 485 support disconnected operation, or high availability in the face of 486 poor connectivity. 488 4. Expiration Model 490 4.1. Server-Specified Expiration 492 HTTP caching works best when caches can entirely avoid making 493 requests to the origin server. The primary mechanism for avoiding 494 requests is for an origin server to provide an explicit expiration 495 time in the future, indicating that a response MAY be used to satisfy 496 subsequent requests. In other words, a cache can return a fresh 497 response without first contacting the server. 499 Our expectation is that servers will assign future explicit 500 expiration times to responses in the belief that the entity is not 501 likely to change, in a semantically significant way, before the 502 expiration time is reached. This normally preserves semantic 503 transparency, as long as the server's expiration times are carefully 504 chosen. 506 The expiration mechanism applies only to responses taken from a cache 507 and not to first-hand responses forwarded immediately to the 508 requesting client. 510 If an origin server wishes to force a semantically transparent cache 511 to validate every request, it MAY assign an explicit expiration time 512 in the past. This means that the response is always stale, and so 513 the cache SHOULD validate it before using it for subsequent requests. 514 See Section 16.2.4 for a more restrictive way to force revalidation. 516 If an origin server wishes to force any HTTP/1.1 cache, no matter how 517 it is configured, to validate every request, it SHOULD use the "must- 518 revalidate" cache-control directive (see Section 16.2). 520 Servers specify explicit expiration times using either the Expires 521 header, or the max-age directive of the Cache-Control header. 523 An expiration time cannot be used to force a user agent to refresh 524 its display or reload a resource; its semantics apply only to caching 525 mechanisms, and such mechanisms need only check a resource's 526 expiration status when a new request for that resource is initiated. 527 See Section 15 for an explanation of the difference between caches 528 and history mechanisms. 530 4.2. Heuristic Expiration 532 Since origin servers do not always provide explicit expiration times, 533 HTTP caches typically assign heuristic expiration times, employing 534 algorithms that use other header values (such as the Last-Modified 535 time) to estimate a plausible expiration time. The HTTP/1.1 536 specification does not provide specific algorithms, but does impose 537 worst-case constraints on their results. Since heuristic expiration 538 times might compromise semantic transparency, they ought to be used 539 cautiously, and we encourage origin servers to provide explicit 540 expiration times as much as possible. 542 4.3. Age Calculations 544 In order to know if a cached entry is fresh, a cache needs to know if 545 its age exceeds its freshness lifetime. We discuss how to calculate 546 the latter in Section 4.4; this section describes how to calculate 547 the age of a response or cache entry. 549 In this discussion, we use the term "now" to mean "the current value 550 of the clock at the host performing the calculation." Hosts that use 551 HTTP, but especially hosts running origin servers and caches, SHOULD 552 use NTP [RFC1305] or some similar protocol to synchronize their 553 clocks to a globally accurate time standard. 555 HTTP/1.1 requires origin servers to send a Date header, if possible, 556 with every response, giving the time at which the response was 557 generated (see Section 8.3 of [Part1]). We use the term "date_value" 558 to denote the value of the Date header, in a form appropriate for 559 arithmetic operations. 561 HTTP/1.1 uses the Age response-header to convey the estimated age of 562 the response message when obtained from a cache. The Age field value 563 is the cache's estimate of the amount of time since the response was 564 generated or revalidated by the origin server. 566 In essence, the Age value is the sum of the time that the response 567 has been resident in each of the caches along the path from the 568 origin server, plus the amount of time it has been in transit along 569 network paths. 571 We use the term "age_value" to denote the value of the Age header, in 572 a form appropriate for arithmetic operations. 574 A response's age can be calculated in two entirely independent ways: 576 1. now minus date_value, if the local clock is reasonably well 577 synchronized to the origin server's clock. If the result is 578 negative, the result is replaced by zero. 580 2. age_value, if all of the caches along the response path implement 581 HTTP/1.1. 583 Given that we have two independent ways to compute the age of a 584 response when it is received, we can combine these as 586 corrected_received_age = max(now - date_value, age_value) 588 and as long as we have either nearly synchronized clocks or all- 589 HTTP/1.1 paths, one gets a reliable (conservative) result. 591 Because of network-imposed delays, some significant interval might 592 pass between the time that a server generates a response and the time 593 it is received at the next outbound cache or client. If uncorrected, 594 this delay could result in improperly low ages. 596 Because the request that resulted in the returned Age value must have 597 been initiated prior to that Age value's generation, we can correct 598 for delays imposed by the network by recording the time at which the 599 request was initiated. Then, when an Age value is received, it MUST 600 be interpreted relative to the time the request was initiated, not 601 the time that the response was received. This algorithm results in 602 conservative behavior no matter how much delay is experienced. So, 603 we compute: 605 corrected_initial_age = corrected_received_age 606 + (now - request_time) 608 where "request_time" is the time (according to the local clock) when 609 the request that elicited this response was sent. 611 Summary of age calculation algorithm, when a cache receives a 612 response: 614 /* 615 * age_value 616 * is the value of Age: header received by the cache with 617 * this response. 618 * date_value 619 * is the value of the origin server's Date: header 620 * request_time 621 * is the (local) time when the cache made the request 622 * that resulted in this cached response 623 * response_time 624 * is the (local) time when the cache received the 625 * response 626 * now 627 * is the current (local) time 628 */ 630 apparent_age = max(0, response_time - date_value); 631 corrected_received_age = max(apparent_age, age_value); 632 response_delay = response_time - request_time; 633 corrected_initial_age = corrected_received_age + response_delay; 634 resident_time = now - response_time; 635 current_age = corrected_initial_age + resident_time; 637 The current_age of a cache entry is calculated by adding the amount 638 of time (in seconds) since the cache entry was last validated by the 639 origin server to the corrected_initial_age. When a response is 640 generated from a cache entry, the cache MUST include a single Age 641 header field in the response with a value equal to the cache entry's 642 current_age. 644 The presence of an Age header field in a response implies that a 645 response is not first-hand. However, the converse is not true, since 646 the lack of an Age header field in a response does not imply that the 647 response is first-hand unless all caches along the request path are 648 compliant with HTTP/1.1 (i.e., older HTTP caches did not implement 649 the Age header field). 651 4.4. Expiration Calculations 653 In order to decide whether a response is fresh or stale, we need to 654 compare its freshness lifetime to its age. The age is calculated as 655 described in Section 4.3; this section describes how to calculate the 656 freshness lifetime, and to determine if a response has expired. In 657 the discussion below, the values can be represented in any form 658 appropriate for arithmetic operations. 660 We use the term "expires_value" to denote the value of the Expires 661 header. We use the term "max_age_value" to denote an appropriate 662 value of the number of seconds carried by the "max-age" directive of 663 the Cache-Control header in a response (see Section 16.2.3). 665 The max-age directive takes priority over Expires, so if max-age is 666 present in a response, the calculation is simply: 668 freshness_lifetime = max_age_value 670 Otherwise, if Expires is present in the response, the calculation is: 672 freshness_lifetime = expires_value - date_value 674 Note that neither of these calculations is vulnerable to clock skew, 675 since all of the information comes from the origin server. 677 If none of Expires, Cache-Control: max-age, or Cache-Control: 678 s-maxage (see Section 16.2.3) appears in the response, and the 679 response does not include other restrictions on caching, the cache 680 MAY compute a freshness lifetime using a heuristic. The cache MUST 681 attach Warning 113 to any response whose age is more than 24 hours if 682 such warning has not already been added. 684 Also, if the response does have a Last-Modified time, the heuristic 685 expiration value SHOULD be no more than some fraction of the interval 686 since that time. A typical setting of this fraction might be 10%. 688 The calculation to determine if a response has expired is quite 689 simple: 691 response_is_fresh = (freshness_lifetime > current_age) 693 4.5. Disambiguating Expiration Values 695 Because expiration values are assigned optimistically, it is possible 696 for two caches to contain fresh values for the same resource that are 697 different. 699 If a client performing a retrieval receives a non-first-hand response 700 for a request that was already fresh in its own cache, and the Date 701 header in its existing cache entry is newer than the Date on the new 702 response, then the client MAY ignore the response. If so, it MAY 703 retry the request with a "Cache-Control: max-age=0" directive (see 704 Section 16.2), to force a check with the origin server. 706 If a cache has two fresh responses for the same representation with 707 different validators, it MUST use the one with the more recent Date 708 header. This situation might arise because the cache is pooling 709 responses from other caches, or because a client has asked for a 710 reload or a revalidation of an apparently fresh cache entry. 712 4.6. Disambiguating Multiple Responses 714 Because a client might be receiving responses via multiple paths, so 715 that some responses flow through one set of caches and other 716 responses flow through a different set of caches, a client might 717 receive responses in an order different from that in which the origin 718 server sent them. We would like the client to use the most recently 719 generated response, even if older responses are still apparently 720 fresh. 722 Neither the entity tag nor the expiration value can impose an 723 ordering on responses, since it is possible that a later response 724 intentionally carries an earlier expiration time. The Date values 725 are ordered to a granularity of one second. 727 When a client tries to revalidate a cache entry, and the response it 728 receives contains a Date header that appears to be older than the one 729 for the existing entry, then the client SHOULD repeat the request 730 unconditionally, and include 732 Cache-Control: max-age=0 734 to force any intermediate caches to validate their copies directly 735 with the origin server, or 737 Cache-Control: no-cache 739 to force any intermediate caches to obtain a new copy from the origin 740 server. 742 If the Date values are equal, then the client MAY use either response 743 (or MAY, if it is being extremely prudent, request a new response). 744 Servers MUST NOT depend on clients being able to choose 745 deterministically between responses generated during the same second, 746 if their expiration times overlap. 748 5. Validation Model 750 When a cache has a stale entry that it would like to use as a 751 response to a client's request, it first has to check with the origin 752 server (or possibly an intermediate cache with a fresh response) to 753 see if its cached entry is still usable. We call this "validating" 754 the cache entry. 756 HTTP's conditional request mechanism, defined in [Part4], is used to 757 avoid retransmitting the response payload when the cached entry is 758 valid. When a cached response includes one or more "cache 759 validators," such as the field values of an ETag or Last-Modified 760 header field, then a validating GET request SHOULD be made 761 conditional to those field values. The server checks the conditional 762 request's validator against the current state of the requested 763 resource and, if they match, the server responds with a 304 (Not 764 Modified) status code to indicate that the cached response can be 765 refreshed and reused without retransmitting the response payload. If 766 the validator does not match the current state of the requested 767 resource, then the server returns a full response, including payload, 768 so that the request can be satisfied and the cache entry supplanted 769 without the need for an additional network round-trip. 771 6. Response Cacheability 773 Unless specifically constrained by a cache-control (Section 16.2) 774 directive, a caching system MAY always store a successful response 775 (see Section 10) as a cache entry, MAY return it without validation 776 if it is fresh, and MAY return it after successful validation. If 777 there is neither a cache validator nor an explicit expiration time 778 associated with a response, we do not expect it to be cached, but 779 certain caches MAY violate this expectation (for example, when little 780 or no network connectivity is available). A client can usually 781 detect that such a response was taken from a cache by comparing the 782 Date header to the current time. 784 Note: some HTTP/1.0 caches are known to violate this expectation 785 without providing any Warning. 787 However, in some cases it might be inappropriate for a cache to 788 retain an entity, or to return it in response to a subsequent 789 request. This might be because absolute semantic transparency is 790 deemed necessary by the service author, or because of security or 791 privacy considerations. Certain cache-control directives are 792 therefore provided so that the server can indicate that certain 793 resource entities, or portions thereof, are not to be cached 794 regardless of other considerations. 796 Note that Section 4.1 of [Part7] normally prevents a shared cache 797 from saving and returning a response to a previous request if that 798 request included an Authorization header. 800 A response received with a status code of 200, 203, 206, 300, 301 or 801 410 MAY be stored by a cache and used in reply to a subsequent 802 request, subject to the expiration mechanism, unless a cache-control 803 directive prohibits caching. However, a cache that does not support 804 the Range and Content-Range headers MUST NOT cache 206 (Partial 805 Content) responses. 807 A response received with any other status code (e.g. status codes 302 808 and 307) MUST NOT be returned in a reply to a subsequent request 809 unless there are cache-control directives or another header(s) that 810 explicitly allow it. For example, these include the following: an 811 Expires header (Section 16.3); a "max-age", "s-maxage", "must- 812 revalidate", "proxy-revalidate", "public" or "private" cache-control 813 directive (Section 16.2). 815 7. Constructing Responses From Caches 817 The purpose of an HTTP cache is to store information received in 818 response to requests for use in responding to future requests. In 819 many cases, a cache simply returns the appropriate parts of a 820 response to the requester. However, if the cache holds a cache entry 821 based on a previous response, it might have to combine parts of a new 822 response with what is held in the cache entry. 824 7.1. End-to-end and Hop-by-hop Headers 826 For the purpose of defining the behavior of caches and non-caching 827 proxies, we divide HTTP headers into two categories: 829 o End-to-end headers, which are transmitted to the ultimate 830 recipient of a request or response. End-to-end headers in 831 responses MUST be stored as part of a cache entry and MUST be 832 transmitted in any response formed from a cache entry. 834 o Hop-by-hop headers, which are meaningful only for a single 835 transport-level connection, and are not stored by caches or 836 forwarded by proxies. 838 The following HTTP/1.1 headers are hop-by-hop headers: 840 o Connection 842 o Keep-Alive 844 o Proxy-Authenticate 846 o Proxy-Authorization 848 o TE 849 o Trailer 851 o Transfer-Encoding 853 o Upgrade 855 All other headers defined by HTTP/1.1 are end-to-end headers. 857 Other hop-by-hop headers MUST be listed in a Connection header 858 (Section 8.1 of [Part1]). 860 7.2. Non-modifiable Headers 862 Some features of HTTP/1.1, such as Digest Authentication, depend on 863 the value of certain end-to-end headers. A transparent proxy SHOULD 864 NOT modify an end-to-end header unless the definition of that header 865 requires or specifically allows that. 867 A transparent proxy MUST NOT modify any of the following fields in a 868 request or response, and it MUST NOT add any of these fields if not 869 already present: 871 o Content-Location 873 o Content-MD5 875 o ETag 877 o Last-Modified 879 A transparent proxy MUST NOT modify any of the following fields in a 880 response: 882 o Expires 884 but it MAY add any of these fields if not already present. If an 885 Expires header is added, it MUST be given a field-value identical to 886 that of the Date header in that response. 888 A proxy MUST NOT modify or add any of the following fields in a 889 message that contains the no-transform cache-control directive, or in 890 any request: 892 o Content-Encoding 894 o Content-Range 895 o Content-Type 897 A non-transparent proxy MAY modify or add these fields to a message 898 that does not include no-transform, but if it does so, it MUST add a 899 Warning 214 (Transformation applied) if one does not already appear 900 in the message (see Section 16.6). 902 Warning: unnecessary modification of end-to-end headers might 903 cause authentication failures if stronger authentication 904 mechanisms are introduced in later versions of HTTP. Such 905 authentication mechanisms MAY rely on the values of header fields 906 not listed here. 908 The Content-Length field of a request or response is added or deleted 909 according to the rules in Section 4.4 of [Part1]. A transparent 910 proxy MUST preserve the entity-length (Section 4.2.2 of [Part3]) of 911 the entity-body, although it MAY change the transfer-length (Section 912 4.4 of [Part1]). 914 7.3. Combining Headers 916 When a cache makes a validating request to a server, and the server 917 provides a 304 (Not Modified) response or a 206 (Partial Content) 918 response, the cache then constructs a response to send to the 919 requesting client. 921 If the status code is 304 (Not Modified), the cache uses the entity- 922 body stored in the cache entry as the entity-body of this outgoing 923 response. If the status code is 206 (Partial Content) and the ETag 924 or Last-Modified headers match exactly, the cache MAY combine the 925 contents stored in the cache entry with the new contents received in 926 the response and use the result as the entity-body of this outgoing 927 response, (see Section 5 of [Part5]). 929 The end-to-end headers stored in the cache entry are used for the 930 constructed response, except that 932 o any stored Warning headers with warn-code 1xx (see Section 16.6) 933 MUST be deleted from the cache entry and the forwarded response. 935 o any stored Warning headers with warn-code 2xx MUST be retained in 936 the cache entry and the forwarded response. 938 o any end-to-end headers provided in the 304 or 206 response MUST 939 replace the corresponding headers from the cache entry. 941 Unless the cache decides to remove the cache entry, it MUST also 942 replace the end-to-end headers stored with the cache entry with 943 corresponding headers received in the incoming response, except for 944 Warning headers as described immediately above. If a header field- 945 name in the incoming response matches more than one header in the 946 cache entry, all such old headers MUST be replaced. 948 In other words, the set of end-to-end headers received in the 949 incoming response overrides all corresponding end-to-end headers 950 stored with the cache entry (except for stored Warning headers with 951 warn-code 1xx, which are deleted even if not overridden). 953 Note: this rule allows an origin server to use a 304 (Not 954 Modified) or a 206 (Partial Content) response to update any header 955 associated with a previous response for the same entity or sub- 956 ranges thereof, although it might not always be meaningful or 957 correct to do so. This rule does not allow an origin server to 958 use a 304 (Not Modified) or a 206 (Partial Content) response to 959 entirely delete a header that it had provided with a previous 960 response. 962 8. Caching Negotiated Responses 964 Use of server-driven content negotiation (Section 5.1 of [Part3]), as 965 indicated by the presence of a Vary header field in a response, 966 alters the conditions and procedure by which a cache can use the 967 response for subsequent requests. See Section 16.5 for use of the 968 Vary header field by servers. 970 A server SHOULD use the Vary header field to inform a cache of what 971 request-header fields were used to select among multiple 972 representations of a cacheable response subject to server-driven 973 negotiation. The set of header fields named by the Vary field value 974 is known as the "selecting" request-headers. 976 When the cache receives a subsequent request whose Request-URI 977 specifies one or more cache entries including a Vary header field, 978 the cache MUST NOT use such a cache entry to construct a response to 979 the new request unless all of the selecting request-headers present 980 in the new request match the corresponding stored request-headers in 981 the original request. 983 The selecting request-headers from two requests are defined to match 984 if and only if the selecting request-headers in the first request can 985 be transformed to the selecting request-headers in the second request 986 by adding or removing linear white space (LWS) at places where this 987 is allowed by the corresponding BNF, and/or combining multiple 988 message-header fields with the same field name following the rules 989 about message headers in Section 4.2 of [Part1]. 991 A Vary header field-value of "*" always fails to match and subsequent 992 requests on that resource can only be properly interpreted by the 993 origin server. 995 If the selecting request header fields for the cached entry do not 996 match the selecting request header fields of the new request, then 997 the cache MUST NOT use a cached entry to satisfy the request unless 998 it first relays the new request to the origin server in a conditional 999 request and the server responds with 304 (Not Modified), including an 1000 entity tag or Content-Location that indicates the entity to be used. 1002 If an entity tag was assigned to a cached representation, the 1003 forwarded request SHOULD be conditional and include the entity tags 1004 in an If-None-Match header field from all its cache entries for the 1005 resource. This conveys to the server the set of entities currently 1006 held by the cache, so that if any one of these entities matches the 1007 requested entity, the server can use the ETag header field in its 304 1008 (Not Modified) response to tell the cache which entry is appropriate. 1009 If the entity-tag of the new response matches that of an existing 1010 entry, the new response SHOULD be used to update the header fields of 1011 the existing entry, and the result MUST be returned to the client. 1013 If any of the existing cache entries contains only partial content 1014 for the associated entity, its entity-tag SHOULD NOT be included in 1015 the If-None-Match header field unless the request is for a range that 1016 would be fully satisfied by that entry. 1018 If a cache receives a successful response whose Content-Location 1019 field matches that of an existing cache entry for the same Request- 1020 URI, whose entity-tag differs from that of the existing entry, and 1021 whose Date is more recent than that of the existing entry, the 1022 existing entry SHOULD NOT be returned in response to future requests 1023 and SHOULD be deleted from the cache. 1025 9. Shared and Non-Shared Caches 1027 For reasons of security and privacy, it is necessary to make a 1028 distinction between "shared" and "non-shared" caches. A non-shared 1029 cache is one that is accessible only to a single user. Accessibility 1030 in this case SHOULD be enforced by appropriate security mechanisms. 1031 All other caches are considered to be "shared." Other sections of 1032 this specification place certain constraints on the operation of 1033 shared caches in order to prevent loss of privacy or failure of 1034 access controls. 1036 10. Errors or Incomplete Response Cache Behavior 1038 A cache that receives an incomplete response (for example, with fewer 1039 bytes of data than specified in a Content-Length header) MAY store 1040 the response. However, the cache MUST treat this as a partial 1041 response. Partial responses MAY be combined as described in Section 1042 5 of [Part5]; the result might be a full response or might still be 1043 partial. A cache MUST NOT return a partial response to a client 1044 without explicitly marking it as such, using the 206 (Partial 1045 Content) status code. A cache MUST NOT return a partial response 1046 using a status code of 200 (OK). 1048 If a cache receives a 5xx response while attempting to revalidate an 1049 entry, it MAY either forward this response to the requesting client, 1050 or act as if the server failed to respond. In the latter case, it 1051 MAY return a previously received response unless the cached entry 1052 includes the "must-revalidate" cache-control directive (see 1053 Section 16.2). 1055 11. Side Effects of GET and HEAD 1057 Unless the origin server explicitly prohibits the caching of their 1058 responses, the application of GET and HEAD methods to any resources 1059 SHOULD NOT have side effects that would lead to erroneous behavior if 1060 these responses are taken from a cache. They MAY still have side 1061 effects, but a cache is not required to consider such side effects in 1062 its caching decisions. Caches are always expected to observe an 1063 origin server's explicit restrictions on caching. 1065 We note one exception to this rule: since some applications have 1066 traditionally used GET and HEAD requests with URLs containing a query 1067 part to perform operations with significant side effects, caches MUST 1068 NOT treat responses to such URIs as fresh unless the server provides 1069 an explicit expiration time. This specifically means that responses 1070 from HTTP/1.0 servers for such URIs SHOULD NOT be taken from a cache. 1071 See Section 8.1.1 of [Part2] for related information. 1073 12. Invalidation After Updates or Deletions 1075 The effect of certain methods performed on a resource at the origin 1076 server might cause one or more existing cache entries to become non- 1077 transparently invalid. That is, although they might continue to be 1078 "fresh," they do not accurately reflect what the origin server would 1079 return for a new request on that resource. 1081 There is no way for HTTP to guarantee that all such cache entries are 1082 marked invalid. For example, the request that caused the change at 1083 the origin server might not have gone through the proxy where a cache 1084 entry is stored. However, several rules help reduce the likelihood 1085 of erroneous behavior. 1087 In this section, the phrase "invalidate an entity" means that the 1088 cache will either remove all instances of that entity from its 1089 storage, or will mark these as "invalid" and in need of a mandatory 1090 revalidation before they can be returned in response to a subsequent 1091 request. 1093 Some HTTP methods MUST cause a cache to invalidate an entity. This 1094 is either the entity referred to by the Request-URI, or by the 1095 Location or Content-Location headers (if present). These methods 1096 are: 1098 o PUT 1100 o DELETE 1102 o POST 1104 An invalidation based on the URI in a Location or Content-Location 1105 header MUST NOT be performed if the host part of that URI differs 1106 from the host part in the Request-URI. This helps prevent denial of 1107 service attacks. 1109 A cache that passes through requests for methods it does not 1110 understand SHOULD invalidate any entities referred to by the Request- 1111 URI. 1113 13. Write-Through Mandatory 1115 All methods that might be expected to cause modifications to the 1116 origin server's resources MUST be written through to the origin 1117 server. This currently includes all methods except for GET and HEAD. 1118 A cache MUST NOT reply to such a request from a client before having 1119 transmitted the request to the inbound server, and having received a 1120 corresponding response from the inbound server. This does not 1121 prevent a proxy cache from sending a 100 (Continue) response before 1122 the inbound server has sent its final reply. 1124 The alternative (known as "write-back" or "copy-back" caching) is not 1125 allowed in HTTP/1.1, due to the difficulty of providing consistent 1126 updates and the problems arising from server, cache, or network 1127 failure prior to write-back. 1129 14. Cache Replacement 1131 If a new cacheable (see Sections 16.2.2, 4.5, 4.6 and 10) response is 1132 received from a resource while any existing responses for the same 1133 resource are cached, the cache SHOULD use the new response to reply 1134 to the current request. It MAY insert it into cache storage and MAY, 1135 if it meets all other requirements, use it to respond to any future 1136 requests that would previously have caused the old response to be 1137 returned. If it inserts the new response into cache storage the 1138 rules in Section 7.3 apply. 1140 Note: a new response that has an older Date header value than 1141 existing cached responses is not cacheable. 1143 15. History Lists 1145 User agents often have history mechanisms, such as "Back" buttons and 1146 history lists, which can be used to redisplay an entity retrieved 1147 earlier in a session. 1149 History mechanisms and caches are different. In particular history 1150 mechanisms SHOULD NOT try to show a semantically transparent view of 1151 the current state of a resource. Rather, a history mechanism is 1152 meant to show exactly what the user saw at the time when the resource 1153 was retrieved. 1155 By default, an expiration time does not apply to history mechanisms. 1156 If the entity is still in storage, a history mechanism SHOULD display 1157 it even if the entity has expired, unless the user has specifically 1158 configured the agent to refresh expired history documents. 1160 This is not to be construed to prohibit the history mechanism from 1161 telling the user that a view might be stale. 1163 Note: if history list mechanisms unnecessarily prevent users from 1164 viewing stale resources, this will tend to force service authors 1165 to avoid using HTTP expiration controls and cache controls when 1166 they would otherwise like to. Service authors may consider it 1167 important that users not be presented with error messages or 1168 warning messages when they use navigation controls (such as BACK) 1169 to view previously fetched resources. Even though sometimes such 1170 resources ought not be cached, or ought to expire quickly, user 1171 interface considerations may force service authors to resort to 1172 other means of preventing caching (e.g. "once-only" URLs) in order 1173 not to suffer the effects of improperly functioning history 1174 mechanisms. 1176 16. Header Field Definitions 1178 This section defines the syntax and semantics of HTTP/1.1 header 1179 fields related to caching. 1181 For entity-header fields, both sender and recipient refer to either 1182 the client or the server, depending on who sends and who receives the 1183 entity. 1185 16.1. Age 1187 The Age response-header field conveys the sender's estimate of the 1188 amount of time since the response (or its revalidation) was generated 1189 at the origin server. A cached response is "fresh" if its age does 1190 not exceed its freshness lifetime. Age values are calculated as 1191 specified in Section 4.3. 1193 Age = "Age" ":" age-value 1194 age-value = delta-seconds 1196 Age values are non-negative decimal integers, representing time in 1197 seconds. 1199 delta-seconds = 1*DIGIT 1201 If a cache receives a value larger than the largest positive integer 1202 it can represent, or if any of its age calculations overflows, it 1203 MUST transmit an Age header with a value of 2147483648 (2^31). An 1204 HTTP/1.1 server that includes a cache MUST include an Age header 1205 field in every response generated from its own cache. Caches SHOULD 1206 use an arithmetic type of at least 31 bits of range. 1208 16.2. Cache-Control 1210 The Cache-Control general-header field is used to specify directives 1211 that MUST be obeyed by all caching mechanisms along the request/ 1212 response chain. The directives specify behavior intended to prevent 1213 caches from adversely interfering with the request or response. 1214 These directives typically override the default caching algorithms. 1215 Cache directives are unidirectional in that the presence of a 1216 directive in a request does not imply that the same directive is to 1217 be given in the response. 1219 Note that HTTP/1.0 caches might not implement Cache-Control and 1220 might only implement Pragma: no-cache (see Section 16.4). 1222 Cache directives MUST be passed through by a proxy or gateway 1223 application, regardless of their significance to that application, 1224 since the directives might be applicable to all recipients along the 1225 request/response chain. It is not possible to specify a cache- 1226 directive for a specific cache. 1228 Cache-Control = "Cache-Control" ":" 1#cache-directive 1230 cache-directive = cache-request-directive 1231 | cache-response-directive 1233 cache-request-directive = 1234 "no-cache" ; Section 16.2.1 1235 | "no-store" ; Section 16.2.2 1236 | "max-age" "=" delta-seconds ; Section 16.2.3, 16.2.4 1237 | "max-stale" [ "=" delta-seconds ] ; Section 16.2.3 1238 | "min-fresh" "=" delta-seconds ; Section 16.2.3 1239 | "no-transform" ; Section 16.2.5 1240 | "only-if-cached" ; Section 16.2.4 1241 | cache-extension ; Section 16.2.6 1243 cache-response-directive = 1244 "public" ; Section 16.2.1 1245 | "private" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1246 | "no-cache" [ "=" DQUOTE 1#field-name DQUOTE ] ; Section 16.2.1 1247 | "no-store" ; Section 16.2.2 1248 | "no-transform" ; Section 16.2.5 1249 | "must-revalidate" ; Section 16.2.4 1250 | "proxy-revalidate" ; Section 16.2.4 1251 | "max-age" "=" delta-seconds ; Section 16.2.3 1252 | "s-maxage" "=" delta-seconds ; Section 16.2.3 1253 | cache-extension ; Section 16.2.6 1255 cache-extension = token [ "=" ( token | quoted-string ) ] 1257 When a directive appears without any 1#field-name parameter, the 1258 directive applies to the entire request or response. When such a 1259 directive appears with a 1#field-name parameter, it applies only to 1260 the named field or fields, and not to the rest of the request or 1261 response. This mechanism supports extensibility; implementations of 1262 future versions of HTTP might apply these directives to header fields 1263 not defined in HTTP/1.1. 1265 The cache-control directives can be broken down into these general 1266 categories: 1268 o Restrictions on what are cacheable; these may only be imposed by 1269 the origin server. 1271 o Restrictions on what may be stored by a cache; these may be 1272 imposed by either the origin server or the user agent. 1274 o Modifications of the basic expiration mechanism; these may be 1275 imposed by either the origin server or the user agent. 1277 o Controls over cache revalidation and reload; these may only be 1278 imposed by a user agent. 1280 o Control over transformation of entities. 1282 o Extensions to the caching system. 1284 16.2.1. What is Cacheable 1286 By default, a response is cacheable if the requirements of the 1287 request method, request header fields, and the response status 1288 indicate that it is cacheable. Section 6 summarizes these defaults 1289 for cacheability. The following Cache-Control response directives 1290 allow an origin server to override the default cacheability of a 1291 response: 1293 public 1295 Indicates that the response MAY be cached by any cache, even if it 1296 would normally be non-cacheable or cacheable only within a non- 1297 shared cache. (See also Authorization, Section 4.1 of [Part7], 1298 for additional details.) 1300 private 1302 Indicates that all or part of the response message is intended for 1303 a single user and MUST NOT be cached by a shared cache. This 1304 allows an origin server to state that the specified parts of the 1305 response are intended for only one user and are not a valid 1306 response for requests by other users. A private (non-shared) 1307 cache MAY cache the response. 1309 Note: This usage of the word private only controls where the 1310 response may be cached, and cannot ensure the privacy of the 1311 message content. 1313 no-cache 1315 If the no-cache directive does not specify a field-name, then a 1316 cache MUST NOT use the response to satisfy a subsequent request 1317 without successful revalidation with the origin server. This 1318 allows an origin server to prevent caching even by caches that 1319 have been configured to return stale responses to client requests. 1321 If the no-cache directive does specify one or more field-names, 1322 then a cache MAY use the response to satisfy a subsequent request, 1323 subject to any other restrictions on caching. However, the 1324 specified field-name(s) MUST NOT be sent in the response to a 1325 subsequent request without successful revalidation with the origin 1326 server. This allows an origin server to prevent the re-use of 1327 certain header fields in a response, while still allowing caching 1328 of the rest of the response. 1330 Note: Most HTTP/1.0 caches will not recognize or obey this 1331 directive. 1333 16.2.2. What May be Stored by Caches 1335 no-store 1337 The purpose of the no-store directive is to prevent the 1338 inadvertent release or retention of sensitive information (for 1339 example, on backup tapes). The no-store directive applies to the 1340 entire message, and MAY be sent either in a response or in a 1341 request. If sent in a request, a cache MUST NOT store any part of 1342 either this request or any response to it. If sent in a response, 1343 a cache MUST NOT store any part of either this response or the 1344 request that elicited it. This directive applies to both non- 1345 shared and shared caches. "MUST NOT store" in this context means 1346 that the cache MUST NOT intentionally store the information in 1347 non-volatile storage, and MUST make a best-effort attempt to 1348 remove the information from volatile storage as promptly as 1349 possible after forwarding it. 1351 Even when this directive is associated with a response, users 1352 might explicitly store such a response outside of the caching 1353 system (e.g., with a "Save As" dialog). History buffers MAY store 1354 such responses as part of their normal operation. 1356 The purpose of this directive is to meet the stated requirements 1357 of certain users and service authors who are concerned about 1358 accidental releases of information via unanticipated accesses to 1359 cache data structures. While the use of this directive might 1360 improve privacy in some cases, we caution that it is NOT in any 1361 way a reliable or sufficient mechanism for ensuring privacy. In 1362 particular, malicious or compromised caches might not recognize or 1363 obey this directive, and communications networks might be 1364 vulnerable to eavesdropping. 1366 16.2.3. Modifications of the Basic Expiration Mechanism 1368 The expiration time of an entity MAY be specified by the origin 1369 server using the Expires header (see Section 16.3). Alternatively, 1370 it MAY be specified using the max-age directive in a response. When 1371 the max-age cache-control directive is present in a cached response, 1372 the response is stale if its current age is greater than the age 1373 value given (in seconds) at the time of a new request for that 1374 resource. The max-age directive on a response implies that the 1375 response is cacheable (i.e., "public") unless some other, more 1376 restrictive cache directive is also present. 1378 If a response includes both an Expires header and a max-age 1379 directive, the max-age directive overrides the Expires header, even 1380 if the Expires header is more restrictive. This rule allows an 1381 origin server to provide, for a given response, a longer expiration 1382 time to an HTTP/1.1 (or later) cache than to an HTTP/1.0 cache. This 1383 might be useful if certain HTTP/1.0 caches improperly calculate ages 1384 or expiration times, perhaps due to desynchronized clocks. 1386 Many HTTP/1.0 cache implementations will treat an Expires value that 1387 is less than or equal to the response Date value as being equivalent 1388 to the Cache-Control response directive "no-cache". If an HTTP/1.1 1389 cache receives such a response, and the response does not include a 1390 Cache-Control header field, it SHOULD consider the response to be 1391 non-cacheable in order to retain compatibility with HTTP/1.0 servers. 1393 Note: An origin server might wish to use a relatively new HTTP 1394 cache control feature, such as the "private" directive, on a 1395 network including older caches that do not understand that 1396 feature. The origin server will need to combine the new feature 1397 with an Expires field whose value is less than or equal to the 1398 Date value. This will prevent older caches from improperly 1399 caching the response. 1401 s-maxage 1403 If a response includes an s-maxage directive, then for a shared 1404 cache (but not for a private cache), the maximum age specified by 1405 this directive overrides the maximum age specified by either the 1406 max-age directive or the Expires header. The s-maxage directive 1407 also implies the semantics of the proxy-revalidate directive (see 1408 Section 16.2.4), i.e., that the shared cache must not use the 1409 entry after it becomes stale to respond to a subsequent request 1410 without first revalidating it with the origin server. The 1411 s-maxage directive is always ignored by a private cache. 1413 Note that most older caches, not compliant with this specification, 1414 do not implement any cache-control directives. An origin server 1415 wishing to use a cache-control directive that restricts, but does not 1416 prevent, caching by an HTTP/1.1-compliant cache MAY exploit the 1417 requirement that the max-age directive overrides the Expires header, 1418 and the fact that pre-HTTP/1.1-compliant caches do not observe the 1419 max-age directive. 1421 Other directives allow a user agent to modify the basic expiration 1422 mechanism. These directives MAY be specified on a request: 1424 max-age 1426 Indicates that the client is willing to accept a response whose 1427 age is no greater than the specified time in seconds. Unless max- 1428 stale directive is also included, the client is not willing to 1429 accept a stale response. 1431 min-fresh 1433 Indicates that the client is willing to accept a response whose 1434 freshness lifetime is no less than its current age plus the 1435 specified time in seconds. That is, the client wants a response 1436 that will still be fresh for at least the specified number of 1437 seconds. 1439 max-stale 1441 Indicates that the client is willing to accept a response that has 1442 exceeded its expiration time. If max-stale is assigned a value, 1443 then the client is willing to accept a response that has exceeded 1444 its expiration time by no more than the specified number of 1445 seconds. If no value is assigned to max-stale, then the client is 1446 willing to accept a stale response of any age. 1448 If a cache returns a stale response, either because of a max-stale 1449 directive on a request, or because the cache is configured to 1450 override the expiration time of a response, the cache MUST attach a 1451 Warning header to the stale response, using Warning 110 (Response is 1452 stale). 1454 A cache MAY be configured to return stale responses without 1455 validation, but only if this does not conflict with any "MUST"-level 1456 requirements concerning cache validation (e.g., a "must-revalidate" 1457 cache-control directive). 1459 If both the new request and the cached entry include "max-age" 1460 directives, then the lesser of the two values is used for determining 1461 the freshness of the cached entry for that request. 1463 16.2.4. Cache Revalidation and Reload Controls 1465 Sometimes a user agent might want or need to insist that a cache 1466 revalidate its cache entry with the origin server (and not just with 1467 the next cache along the path to the origin server), or to reload its 1468 cache entry from the origin server. End-to-end revalidation might be 1469 necessary if either the cache or the origin server has overestimated 1470 the expiration time of the cached response. End-to-end reload may be 1471 necessary if the cache entry has become corrupted for some reason. 1473 End-to-end revalidation may be requested either when the client does 1474 not have its own local cached copy, in which case we call it 1475 "unspecified end-to-end revalidation", or when the client does have a 1476 local cached copy, in which case we call it "specific end-to-end 1477 revalidation." 1479 The client can specify these three kinds of action using Cache- 1480 Control request directives: 1482 End-to-end reload 1484 The request includes a "no-cache" cache-control directive or, for 1485 compatibility with HTTP/1.0 clients, "Pragma: no-cache". Field 1486 names MUST NOT be included with the no-cache directive in a 1487 request. The server MUST NOT use a cached copy when responding to 1488 such a request. 1490 Specific end-to-end revalidation 1492 The request includes a "max-age=0" cache-control directive, which 1493 forces each cache along the path to the origin server to 1494 revalidate its own entry, if any, with the next cache or server. 1495 The initial request includes a cache-validating conditional with 1496 the client's current validator. 1498 Unspecified end-to-end revalidation 1500 The request includes "max-age=0" cache-control directive, which 1501 forces each cache along the path to the origin server to 1502 revalidate its own entry, if any, with the next cache or server. 1503 The initial request does not include a cache-validating 1504 conditional; the first cache along the path (if any) that holds a 1505 cache entry for this resource includes a cache-validating 1506 conditional with its current validator. 1508 max-age 1509 When an intermediate cache is forced, by means of a max-age=0 1510 directive, to revalidate its own cache entry, and the client has 1511 supplied its own validator in the request, the supplied validator 1512 might differ from the validator currently stored with the cache 1513 entry. In this case, the cache MAY use either validator in making 1514 its own request without affecting semantic transparency. 1516 However, the choice of validator might affect performance. The 1517 best approach is for the intermediate cache to use its own 1518 validator when making its request. If the server replies with 304 1519 (Not Modified), then the cache can return its now validated copy 1520 to the client with a 200 (OK) response. If the server replies 1521 with a new entity and cache validator, however, the intermediate 1522 cache can compare the returned validator with the one provided in 1523 the client's request, using the strong comparison function. If 1524 the client's validator is equal to the origin server's, then the 1525 intermediate cache simply returns 304 (Not Modified). Otherwise, 1526 it returns the new entity with a 200 (OK) response. 1528 If a request includes the no-cache directive, it SHOULD NOT 1529 include min-fresh, max-stale, or max-age. 1531 only-if-cached 1533 In some cases, such as times of extremely poor network 1534 connectivity, a client may want a cache to return only those 1535 responses that it currently has stored, and not to reload or 1536 revalidate with the origin server. To do this, the client may 1537 include the only-if-cached directive in a request. If it receives 1538 this directive, a cache SHOULD either respond using a cached entry 1539 that is consistent with the other constraints of the request, or 1540 respond with a 504 (Gateway Timeout) status. However, if a group 1541 of caches is being operated as a unified system with good internal 1542 connectivity, such a request MAY be forwarded within that group of 1543 caches. 1545 must-revalidate 1547 Because a cache MAY be configured to ignore a server's specified 1548 expiration time, and because a client request MAY include a max- 1549 stale directive (which has a similar effect), the protocol also 1550 includes a mechanism for the origin server to require revalidation 1551 of a cache entry on any subsequent use. When the must-revalidate 1552 directive is present in a response received by a cache, that cache 1553 MUST NOT use the entry after it becomes stale to respond to a 1554 subsequent request without first revalidating it with the origin 1555 server. (I.e., the cache MUST do an end-to-end revalidation every 1556 time, if, based solely on the origin server's Expires or max-age 1557 value, the cached response is stale.) 1559 The must-revalidate directive is necessary to support reliable 1560 operation for certain protocol features. In all circumstances an 1561 HTTP/1.1 cache MUST obey the must-revalidate directive; in 1562 particular, if the cache cannot reach the origin server for any 1563 reason, it MUST generate a 504 (Gateway Timeout) response. 1565 Servers SHOULD send the must-revalidate directive if and only if 1566 failure to revalidate a request on the entity could result in 1567 incorrect operation, such as a silently unexecuted financial 1568 transaction. Recipients MUST NOT take any automated action that 1569 violates this directive, and MUST NOT automatically provide an 1570 unvalidated copy of the entity if revalidation fails. 1572 Although this is not recommended, user agents operating under 1573 severe connectivity constraints MAY violate this directive but, if 1574 so, MUST explicitly warn the user that an unvalidated response has 1575 been provided. The warning MUST be provided on each unvalidated 1576 access, and SHOULD require explicit user confirmation. 1578 proxy-revalidate 1580 The proxy-revalidate directive has the same meaning as the must- 1581 revalidate directive, except that it does not apply to non-shared 1582 user agent caches. It can be used on a response to an 1583 authenticated request to permit the user's cache to store and 1584 later return the response without needing to revalidate it (since 1585 it has already been authenticated once by that user), while still 1586 requiring proxies that service many users to revalidate each time 1587 (in order to make sure that each user has been authenticated). 1588 Note that such authenticated responses also need the public cache 1589 control directive in order to allow them to be cached at all. 1591 16.2.5. No-Transform Directive 1593 no-transform 1595 Implementors of intermediate caches (proxies) have found it useful 1596 to convert the media type of certain entity bodies. A non- 1597 transparent proxy might, for example, convert between image 1598 formats in order to save cache space or to reduce the amount of 1599 traffic on a slow link. 1601 Serious operational problems occur, however, when these 1602 transformations are applied to entity bodies intended for certain 1603 kinds of applications. For example, applications for medical 1604 imaging, scientific data analysis and those using end-to-end 1605 authentication, all depend on receiving an entity body that is bit 1606 for bit identical to the original entity-body. 1608 Therefore, if a message includes the no-transform directive, an 1609 intermediate cache or proxy MUST NOT change those headers that are 1610 listed in Section 7.2 as being subject to the no-transform 1611 directive. This implies that the cache or proxy MUST NOT change 1612 any aspect of the entity-body that is specified by these headers, 1613 including the value of the entity-body itself. 1615 16.2.6. Cache Control Extensions 1617 The Cache-Control header field can be extended through the use of one 1618 or more cache-extension tokens, each with an optional assigned value. 1619 Informational extensions (those which do not require a change in 1620 cache behavior) MAY be added without changing the semantics of other 1621 directives. Behavioral extensions are designed to work by acting as 1622 modifiers to the existing base of cache directives. Both the new 1623 directive and the standard directive are supplied, such that 1624 applications which do not understand the new directive will default 1625 to the behavior specified by the standard directive, and those that 1626 understand the new directive will recognize it as modifying the 1627 requirements associated with the standard directive. In this way, 1628 extensions to the cache-control directives can be made without 1629 requiring changes to the base protocol. 1631 This extension mechanism depends on an HTTP cache obeying all of the 1632 cache-control directives defined for its native HTTP-version, obeying 1633 certain extensions, and ignoring all directives that it does not 1634 understand. 1636 For example, consider a hypothetical new response directive called 1637 community which acts as a modifier to the private directive. We 1638 define this new directive to mean that, in addition to any non-shared 1639 cache, any cache which is shared only by members of the community 1640 named within its value may cache the response. An origin server 1641 wishing to allow the UCI community to use an otherwise private 1642 response in their shared cache(s) could do so by including 1644 Cache-Control: private, community="UCI" 1646 A cache seeing this header field will act correctly even if the cache 1647 does not understand the community cache-extension, since it will also 1648 see and understand the private directive and thus default to the safe 1649 behavior. 1651 Unrecognized cache-directives MUST be ignored; it is assumed that any 1652 cache-directive likely to be unrecognized by an HTTP/1.1 cache will 1653 be combined with standard directives (or the response's default 1654 cacheability) such that the cache behavior will remain minimally 1655 correct even if the cache does not understand the extension(s). 1657 16.3. Expires 1659 The Expires entity-header field gives the date/time after which the 1660 response is considered stale. A stale cache entry may not normally 1661 be returned by a cache (either a proxy cache or a user agent cache) 1662 unless it is first validated with the origin server (or with an 1663 intermediate cache that has a fresh copy of the entity). See 1664 Section 4 for further discussion of the expiration model. 1666 The presence of an Expires field does not imply that the original 1667 resource will change or cease to exist at, before, or after that 1668 time. 1670 The format is an absolute date and time as defined by HTTP-date in 1671 Section 3.3.1 of [Part1]; it MUST be sent in rfc1123-date format. 1673 Expires = "Expires" ":" HTTP-date 1675 An example of its use is 1677 Expires: Thu, 01 Dec 1994 16:00:00 GMT 1679 Note: if a response includes a Cache-Control field with the max- 1680 age directive (see Section 16.2.3), that directive overrides the 1681 Expires field. 1683 HTTP/1.1 clients and caches MUST treat other invalid date formats, 1684 especially including the value "0", as in the past (i.e., "already 1685 expired"). 1687 To mark a response as "already expired," an origin server sends an 1688 Expires date that is equal to the Date header value. (See the rules 1689 for expiration calculations in Section 4.4.) 1691 To mark a response as "never expires," an origin server sends an 1692 Expires date approximately one year from the time the response is 1693 sent. HTTP/1.1 servers SHOULD NOT send Expires dates more than one 1694 year in the future. 1696 The presence of an Expires header field with a date value of some 1697 time in the future on a response that otherwise would by default be 1698 non-cacheable indicates that the response is cacheable, unless 1699 indicated otherwise by a Cache-Control header field (Section 16.2). 1701 16.4. Pragma 1703 The Pragma general-header field is used to include implementation- 1704 specific directives that might apply to any recipient along the 1705 request/response chain. All pragma directives specify optional 1706 behavior from the viewpoint of the protocol; however, some systems 1707 MAY require that behavior be consistent with the directives. 1709 Pragma = "Pragma" ":" 1#pragma-directive 1710 pragma-directive = "no-cache" | extension-pragma 1711 extension-pragma = token [ "=" ( token | quoted-string ) ] 1713 When the no-cache directive is present in a request message, an 1714 application SHOULD forward the request toward the origin server even 1715 if it has a cached copy of what is being requested. This pragma 1716 directive has the same semantics as the no-cache cache-directive (see 1717 Section 16.2) and is defined here for backward compatibility with 1718 HTTP/1.0. Clients SHOULD include both header fields when a no-cache 1719 request is sent to a server not known to be HTTP/1.1 compliant. 1721 Pragma directives MUST be passed through by a proxy or gateway 1722 application, regardless of their significance to that application, 1723 since the directives might be applicable to all recipients along the 1724 request/response chain. It is not possible to specify a pragma for a 1725 specific recipient; however, any pragma directive not relevant to a 1726 recipient SHOULD be ignored by that recipient. 1728 HTTP/1.1 caches SHOULD treat "Pragma: no-cache" as if the client had 1729 sent "Cache-Control: no-cache". No new Pragma directives will be 1730 defined in HTTP. 1732 Note: because the meaning of "Pragma: no-cache" as a response- 1733 header field is not actually specified, it does not provide a 1734 reliable replacement for "Cache-Control: no-cache" in a response. 1736 16.5. Vary 1738 The Vary field value indicates the set of request-header fields that 1739 fully determines, while the response is fresh, whether a cache is 1740 permitted to use the response to reply to a subsequent request 1741 without revalidation. For uncacheable or stale responses, the Vary 1742 field value advises the user agent about the criteria that were used 1743 to select the representation. A Vary field value of "*" implies that 1744 a cache cannot determine from the request headers of a subsequent 1745 request whether this response is the appropriate representation. See 1746 Section 8 for use of the Vary header field by caches. 1748 Vary = "Vary" ":" ( "*" | 1#field-name ) 1750 An HTTP/1.1 server SHOULD include a Vary header field with any 1751 cacheable response that is subject to server-driven negotiation. 1752 Doing so allows a cache to properly interpret future requests on that 1753 resource and informs the user agent about the presence of negotiation 1754 on that resource. A server MAY include a Vary header field with a 1755 non-cacheable response that is subject to server-driven negotiation, 1756 since this might provide the user agent with useful information about 1757 the dimensions over which the response varies at the time of the 1758 response. 1760 A Vary field value consisting of a list of field-names signals that 1761 the representation selected for the response is based on a selection 1762 algorithm which considers ONLY the listed request-header field values 1763 in selecting the most appropriate representation. A cache MAY assume 1764 that the same selection will be made for future requests with the 1765 same values for the listed field names, for the duration of time for 1766 which the response is fresh. 1768 The field-names given are not limited to the set of standard request- 1769 header fields defined by this specification. Field names are case- 1770 insensitive. 1772 A Vary field value of "*" signals that unspecified parameters not 1773 limited to the request-headers (e.g., the network address of the 1774 client), play a role in the selection of the response representation. 1775 The "*" value MUST NOT be generated by a proxy server; it may only be 1776 generated by an origin server. 1778 16.6. Warning 1780 The Warning general-header field is used to carry additional 1781 information about the status or transformation of a message which 1782 might not be reflected in the message. This information is typically 1783 used to warn about a possible lack of semantic transparency from 1784 caching operations or transformations applied to the entity body of 1785 the message. 1787 Warning headers are sent with responses using: 1789 Warning = "Warning" ":" 1#warning-value 1791 warning-value = warn-code SP warn-agent SP warn-text 1792 [SP warn-date] 1794 warn-code = 3DIGIT 1795 warn-agent = ( uri-host [ ":" port ] ) | pseudonym 1796 ; the name or pseudonym of the server adding 1797 ; the Warning header, for use in debugging 1798 warn-text = quoted-string 1799 warn-date = DQUOTE HTTP-date DQUOTE 1801 A response MAY carry more than one Warning header. 1803 The warn-text SHOULD be in a natural language and character set that 1804 is most likely to be intelligible to the human user receiving the 1805 response. This decision MAY be based on any available knowledge, 1806 such as the location of the cache or user, the Accept-Language field 1807 in a request, the Content-Language field in a response, etc. The 1808 default language is English and the default character set is ISO- 1809 8859-1 ([ISO-8859-1]). 1811 If a character set other than ISO-8859-1 is used, it MUST be encoded 1812 in the warn-text using the method described in [RFC2047]. 1814 Warning headers can in general be applied to any message, however 1815 some specific warn-codes are specific to caches and can only be 1816 applied to response messages. New Warning headers SHOULD be added 1817 after any existing Warning headers. A cache MUST NOT delete any 1818 Warning header that it received with a message. However, if a cache 1819 successfully validates a cache entry, it SHOULD remove any Warning 1820 headers previously attached to that entry except as specified for 1821 specific Warning codes. It MUST then add any Warning headers 1822 received in the validating response. In other words, Warning headers 1823 are those that would be attached to the most recent relevant 1824 response. 1826 When multiple Warning headers are attached to a response, the user 1827 agent ought to inform the user of as many of them as possible, in the 1828 order that they appear in the response. If it is not possible to 1829 inform the user of all of the warnings, the user agent SHOULD follow 1830 these heuristics: 1832 o Warnings that appear early in the response take priority over 1833 those appearing later in the response. 1835 o Warnings in the user's preferred character set take priority over 1836 warnings in other character sets but with identical warn-codes and 1837 warn-agents. 1839 Systems that generate multiple Warning headers SHOULD order them with 1840 this user agent behavior in mind. 1842 Requirements for the behavior of caches with respect to Warnings are 1843 stated in Section 3.2. 1845 This is a list of the currently-defined warn-codes, each with a 1846 recommended warn-text in English, and a description of its meaning. 1848 110 Response is stale 1850 MUST be included whenever the returned response is stale. 1852 111 Revalidation failed 1854 MUST be included if a cache returns a stale response because an 1855 attempt to revalidate the response failed, due to an inability to 1856 reach the server. 1858 112 Disconnected operation 1860 SHOULD be included if the cache is intentionally disconnected from 1861 the rest of the network for a period of time. 1863 113 Heuristic expiration 1865 MUST be included if the cache heuristically chose a freshness 1866 lifetime greater than 24 hours and the response's age is greater 1867 than 24 hours. 1869 199 Miscellaneous warning 1871 The warning text MAY include arbitrary information to be presented 1872 to a human user, or logged. A system receiving this warning MUST 1873 NOT take any automated action, besides presenting the warning to 1874 the user. 1876 214 Transformation applied 1878 MUST be added by an intermediate cache or proxy if it applies any 1879 transformation changing the content-coding (as specified in the 1880 Content-Encoding header) or media-type (as specified in the 1881 Content-Type header) of the response, or the entity-body of the 1882 response, unless this Warning code already appears in the 1883 response. 1885 299 Miscellaneous persistent warning 1887 The warning text MAY include arbitrary information to be presented 1888 to a human user, or logged. A system receiving this warning MUST 1889 NOT take any automated action. 1891 If an implementation sends a message with one or more Warning headers 1892 whose version is HTTP/1.0 or lower, then the sender MUST include in 1893 each warning-value a warn-date that matches the date in the response. 1895 If an implementation receives a message with a warning-value that 1896 includes a warn-date, and that warn-date is different from the Date 1897 value in the response, then that warning-value MUST be deleted from 1898 the message before storing, forwarding, or using it. (This prevents 1899 bad consequences of naive caching of Warning header fields.) If all 1900 of the warning-values are deleted for this reason, the Warning header 1901 MUST be deleted as well. 1903 17. IANA Considerations 1905 17.1. Message Header Registration 1907 The Message Header Registry located at should be 1909 updated with the permanent registrations below (see [RFC3864]): 1911 +-------------------+----------+----------+--------------+ 1912 | Header Field Name | Protocol | Status | Reference | 1913 +-------------------+----------+----------+--------------+ 1914 | Age | http | standard | Section 16.1 | 1915 | Cache-Control | http | standard | Section 16.2 | 1916 | Expires | http | standard | Section 16.3 | 1917 | Pragma | http | standard | Section 16.4 | 1918 | Vary | http | standard | Section 16.5 | 1919 | Warning | http | standard | Section 16.6 | 1920 +-------------------+----------+----------+--------------+ 1922 The change controller is: "IETF (iesg@ietf.org) - Internet 1923 Engineering Task Force". 1925 18. Security Considerations 1927 Caching proxies provide additional potential vulnerabilities, since 1928 the contents of the cache represent an attractive target for 1929 malicious exploitation. Because cache contents persist after an HTTP 1930 request is complete, an attack on the cache can reveal information 1931 long after a user believes that the information has been removed from 1932 the network. Therefore, cache contents should be protected as 1933 sensitive information. 1935 19. Acknowledgments 1937 Much of the content and presentation of the caching design is due to 1938 suggestions and comments from individuals including: Shel Kaphan, 1939 Paul Leach, Koen Holtman, David Morris, and Larry Masinter. 1941 20. References 1943 20.1. Normative References 1945 [ISO-8859-1] 1946 International Organization for Standardization, 1947 "Information technology -- 8-bit single-byte coded graphic 1948 character sets -- Part 1: Latin alphabet No. 1", ISO/ 1949 IEC 8859-1:1998, 1998. 1951 [Part1] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1952 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1953 and J. Reschke, Ed., "HTTP/1.1, part 1: URIs, Connections, 1954 and Message Parsing", draft-ietf-httpbis-p1-messaging-03 1955 (work in progress), June 2008. 1957 [Part2] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1958 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1959 and J. Reschke, Ed., "HTTP/1.1, part 2: Message 1960 Semantics", draft-ietf-httpbis-p2-semantics-03 (work in 1961 progress), June 2008. 1963 [Part3] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1964 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1965 and J. Reschke, Ed., "HTTP/1.1, part 3: Message Payload 1966 and Content Negotiation", draft-ietf-httpbis-p3-payload-03 1967 (work in progress), June 2008. 1969 [Part4] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1970 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1971 and J. Reschke, Ed., "HTTP/1.1, part 4: Conditional 1972 Requests", draft-ietf-httpbis-p4-conditional-03 (work in 1973 progress), June 2008. 1975 [Part5] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1976 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1977 and J. Reschke, Ed., "HTTP/1.1, part 5: Range Requests and 1978 Partial Responses", draft-ietf-httpbis-p5-range-03 (work 1979 in progress), June 2008. 1981 [Part7] Fielding, R., Ed., Gettys, J., Mogul, J., Frystyk, H., 1982 Masinter, L., Leach, P., Berners-Lee, T., Lafon, Y., Ed., 1983 and J. Reschke, Ed., "HTTP/1.1, part 7: Authentication", 1984 draft-ietf-httpbis-p7-auth-03 (work in progress), 1985 June 2008. 1987 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 1988 Part Three: Message Header Extensions for Non-ASCII Text", 1989 RFC 2047, November 1996. 1991 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1992 Requirement Levels", BCP 14, RFC 2119, March 1997. 1994 20.2. Informative References 1996 [RFC1305] Mills, D., "Network Time Protocol (Version 3) 1997 Specification, Implementation", RFC 1305, March 1992. 1999 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 2000 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 2001 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 2003 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 2004 Procedures for Message Header Fields", BCP 90, RFC 3864, 2005 September 2004. 2007 Appendix A. Compatibility with Previous Versions 2009 A.1. Changes from RFC 2068 2011 A case was missed in the Cache-Control model of HTTP/1.1; s-maxage 2012 was introduced to add this missing case. (Sections 6, 16.2, 16.2.3) 2014 Transfer-coding and message lengths all interact in ways that 2015 required fixing exactly when chunked encoding is used (to allow for 2016 transfer encoding that may not be self delimiting); it was important 2017 to straighten out exactly how message lengths are computed. 2018 (Section 7.2, see also [Part1], [Part3] and [Part5]) 2020 Proxies should be able to add Content-Length when appropriate. 2021 (Section 7.2) 2023 Range request responses would become very verbose if all meta-data 2024 were always returned; by allowing the server to only send needed 2025 headers in a 206 response, this problem can be avoided. 2026 (Section 7.3) 2028 The Cache-Control: max-age directive was not properly defined for 2029 responses. (Section 16.2.3) 2031 Warnings could be cached incorrectly, or not updated appropriately. 2032 (Section 3.2, 4.4, 7.2, 7.3, 16.2.3, and 16.6) Warning also needed to 2033 be a general header, as PUT or other methods may have need for it in 2034 requests. 2036 A.2. Changes from RFC 2616 2038 Clarify denial of service attack avoidance requirement. (Section 12) 2040 Appendix B. Change Log (to be removed by RFC Editor before publication) 2042 B.1. Since RFC2616 2044 Extracted relevant partitions from [RFC2616]. 2046 B.2. Since draft-ietf-httpbis-p6-cache-00 2048 Closed issues: 2050 o : "Trailer" 2051 () 2053 o : 2054 "Invalidation after Update or Delete" 2055 () 2057 o : "Normative 2058 and Informative references" 2060 o : "Date 2061 reference typo" 2063 o : 2064 "Connection header text" 2066 o : 2067 "Informative references" 2069 o : 2070 "ISO-8859-1 Reference" 2072 o : "Normative 2073 up-to-date references" 2075 o : "typo in 2076 13.2.2" 2078 Other changes: 2080 o Use names of RFC4234 core rules DQUOTE and HTAB (work in progress 2081 on ) 2083 B.3. Since draft-ietf-httpbis-p6-cache-01 2085 Closed issues: 2087 o : "rel_path 2088 not used" 2090 Other changes: 2092 o Get rid of duplicate BNF rule names ("host" -> "uri-host") (work 2093 in progress on 2094 ) 2096 o Add explicit references to BNF syntax and rules imported from 2097 other parts of the specification. 2099 B.4. Since draft-ietf-httpbis-p6-cache-02 2101 Ongoing work on IANA Message Header Registration 2102 (): 2104 o Reference RFC 3984, and update header registrations for headers 2105 defined in this document. 2107 Index 2109 A 2110 age 7 2111 Age header 27 2113 C 2114 cache 5 2115 Cache Directives 2116 max-age 32-33 2117 max-stale 32 2118 min-fresh 32 2119 must-revalidate 34 2120 no-cache 29 2121 no-store 30 2122 no-transform 35 2123 only-if-cached 34 2124 private 29 2125 proxy-revalidate 35 2126 public 29 2127 s-maxage 31 2128 Cache-Control header 27 2129 cacheable 6 2131 E 2132 Expires header 37 2133 explicit expiration time 7 2135 F 2136 first-hand 6 2137 fresh 7 2138 freshness lifetime 7 2140 G 2141 Grammar 2142 Age 27 2143 age-value 27 2144 Cache-Control 28 2145 cache-directive 28 2146 cache-extension 28 2147 cache-request-directive 28 2148 cache-response-directive 28 2149 delta-seconds 27 2150 Expires 37 2151 extension-pragma 38 2152 Pragma 38 2153 pragma-directive 38 2154 Vary 38 2155 warn-agent 40 2156 warn-code 40 2157 warn-date 40 2158 warn-text 40 2159 Warning 40 2160 warning-value 40 2162 H 2163 Headers 2164 Age 27 2165 Cache-Control 27 2166 Expires 37 2167 Pragma 38 2168 Vary 38 2169 Warning 39 2170 heuristic expiration time 7 2172 M 2173 max-age 2174 Cache Directive 32-33 2175 max-stale 2176 Cache Directive 32 2177 min-fresh 2178 Cache Directive 32 2179 must-revalidate 2180 Cache Directive 34 2182 N 2183 no-cache 2184 Cache Directive 29 2185 no-store 2186 Cache Directive 30 2187 no-transform 2188 Cache Directive 35 2190 O 2191 only-if-cached 2192 Cache Directive 34 2194 P 2195 Pragma header 38 2196 private 2197 Cache Directive 29 2198 proxy-revalidate 2199 Cache Directive 35 2200 public 2201 Cache Directive 29 2203 S 2204 s-maxage 2205 Cache Directive 31 2206 semantically transparent 5 2207 stale 7 2209 V 2210 validator 7 2211 Vary header 38 2213 W 2214 Warning header 39 2216 Authors' Addresses 2218 Roy T. Fielding (editor) 2219 Day Software 2220 23 Corporate Plaza DR, Suite 280 2221 Newport Beach, CA 92660 2222 USA 2224 Phone: +1-949-706-5300 2225 Fax: +1-949-706-5305 2226 Email: fielding@gbiv.com 2227 URI: http://roy.gbiv.com/ 2229 Jim Gettys 2230 One Laptop per Child 2231 21 Oak Knoll Road 2232 Carlisle, MA 01741 2233 USA 2235 Email: jg@laptop.org 2236 URI: http://www.laptop.org/ 2238 Jeffrey C. Mogul 2239 Hewlett-Packard Company 2240 HP Labs, Large Scale Systems Group 2241 1501 Page Mill Road, MS 1177 2242 Palo Alto, CA 94304 2243 USA 2245 Email: JeffMogul@acm.org 2247 Henrik Frystyk Nielsen 2248 Microsoft Corporation 2249 1 Microsoft Way 2250 Redmond, WA 98052 2251 USA 2253 Email: henrikn@microsoft.com 2254 Larry Masinter 2255 Adobe Systems, Incorporated 2256 345 Park Ave 2257 San Jose, CA 95110 2258 USA 2260 Email: LMM@acm.org 2261 URI: http://larry.masinter.net/ 2263 Paul J. Leach 2264 Microsoft Corporation 2265 1 Microsoft Way 2266 Redmond, WA 98052 2268 Email: paulle@microsoft.com 2270 Tim Berners-Lee 2271 World Wide Web Consortium 2272 MIT Computer Science and Artificial Intelligence Laboratory 2273 The Stata Center, Building 32 2274 32 Vassar Street 2275 Cambridge, MA 02139 2276 USA 2278 Email: timbl@w3.org 2279 URI: http://www.w3.org/People/Berners-Lee/ 2281 Yves Lafon (editor) 2282 World Wide Web Consortium 2283 W3C / ERCIM 2284 2004, rte des Lucioles 2285 Sophia-Antipolis, AM 06902 2286 France 2288 Email: ylafon@w3.org 2289 URI: http://www.raubacapeu.net/people/yves/ 2290 Julian F. Reschke (editor) 2291 greenbytes GmbH 2292 Hafenweg 16 2293 Muenster, NW 48155 2294 Germany 2296 Phone: +49 251 2807760 2297 Fax: +49 251 2807761 2298 Email: julian.reschke@greenbytes.de 2299 URI: http://greenbytes.de/tech/webdav/ 2301 Full Copyright Statement 2303 Copyright (C) The IETF Trust (2008). 2305 This document is subject to the rights, licenses and restrictions 2306 contained in BCP 78, and except as set forth therein, the authors 2307 retain all their rights. 2309 This document and the information contained herein are provided on an 2310 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2311 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 2312 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 2313 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 2314 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2315 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2317 Intellectual Property 2319 The IETF takes no position regarding the validity or scope of any 2320 Intellectual Property Rights or other rights that might be claimed to 2321 pertain to the implementation or use of the technology described in 2322 this document or the extent to which any license under such rights 2323 might or might not be available; nor does it represent that it has 2324 made any independent effort to identify any such rights. Information 2325 on the procedures with respect to rights in RFC documents can be 2326 found in BCP 78 and BCP 79. 2328 Copies of IPR disclosures made to the IETF Secretariat and any 2329 assurances of licenses to be made available, or the result of an 2330 attempt made to obtain a general license or permission for the use of 2331 such proprietary rights by implementers or users of this 2332 specification can be obtained from the IETF on-line IPR repository at 2333 http://www.ietf.org/ipr. 2335 The IETF invites any interested party to bring to its attention any 2336 copyrights, patents or patent applications, or other proprietary 2337 rights that may cover technology that may be required to implement 2338 this standard. Please address the information to the IETF at 2339 ietf-ipr@ietf.org.