Changeset 949
- Timestamp:
- 27/07/10 15:24:54 (12 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p6-cache.xml
r944 r949 202 202 <abstract> 203 203 <t> 204 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for distributed, 205 collaborative, hypermedia information systems. This document is Part 6 of the seven-part 206 specification that defines the protocol referred to as "HTTP/1.1" and, taken together, 207 obsoletes RFC 2616. Part 6 defines requirements on HTTP caches and the associated header 208 fields that control cache behavior or indicate cacheable response messages. 204 The Hypertext Transfer Protocol (HTTP) is an application-level protocol for 205 distributed, collaborative, hypermedia information systems. This document 206 is Part 6 of the seven-part specification that defines the protocol 207 referred to as "HTTP/1.1" and, taken together, obsoletes RFC 2616. Part 6 208 defines requirements on HTTP caches and the associated header fields that 209 control cache behavior or indicate cacheable response messages. 209 210 </t> 210 211 </abstract> 211 212 212 213 <note title="Editorial Note (To be removed by RFC Editor)"> 213 <t> 214 Discussion of this draft should take place on the HTTPBIS working group 215 mailing list (ietf-http-wg@w3.org). The current issues list is 216 at <eref target="http://tools.ietf.org/wg/httpbis/trac/report/3"/> 217 and related documents (including fancy diffs) can be found at 218 <eref target="http://tools.ietf.org/wg/httpbis/"/>. 219 </t> 220 <t> 221 The changes in this draft are summarized in <xref target="changes.since.10"/>. 222 </t> 214 <t> 215 Discussion of this draft should take place on the HTTPBIS working group 216 mailing list (ietf-http-wg@w3.org). The current issues list is at <eref 217 target="http://tools.ietf.org/wg/httpbis/trac/report/3"/> and related 218 documents (including fancy diffs) can be found at <eref 219 target="http://tools.ietf.org/wg/httpbis/"/>. 220 </t> 221 <t> 222 The changes in this draft are summarized in <xref 223 target="changes.since.10"/>. 224 </t> 223 225 </note> 224 226 225 </front>226 <middle>227 </front> 228 <middle> 227 229 228 230 <section anchor="caching" title="Introduction"> 229 231 <t> 230 HTTP is typically used for distributed information systems, where performance can be 231 improved by the use of response caches. This document defines aspects of HTTP/1.1 related to 232 caching and reusing response messages. 232 HTTP is typically used for distributed information systems, where 233 performance can be improved by the use of response caches. This document 234 defines aspects of HTTP/1.1 related to caching and reusing response 235 messages. 233 236 </t> 234 237 … … 236 239 <iref item="cache" /> 237 240 <t> 238 An HTTP <x:dfn>cache</x:dfn> is a local store of response messages and the subsystem that 239 controls its message storage, retrieval, and deletion. A cache stores cacheable responses 240 in order to reduce the response time and network bandwidth consumption on future, 241 equivalent requests. Any client or server &MAY; employ a cache, though a cache cannot be 242 used by a server that is acting as a tunnel. 243 </t> 244 <t> 245 Caching would be useless if it did not significantly improve performance. The goal of 246 caching in HTTP/1.1 is to reuse a prior response message to satisfy a current request. In 247 some cases, a stored response can be reused without the need for a network request, 248 reducing latency and network round-trips; a "freshness" mechanism is used for this purpose 249 (see <xref target="expiration.model" />). Even when a new request is required, it is often 250 possible to reuse all or parts of the payload of a prior response to satisfy the request, 251 thereby reducing network bandwidth usage; a "validation" mechanism is used for this 252 purpose (see <xref target="validation.model" />). 241 An HTTP <x:dfn>cache</x:dfn> is a local store of response messages and the 242 subsystem that controls its message storage, retrieval, and deletion. A 243 cache stores cacheable responses in order to reduce the response time and 244 network bandwidth consumption on future, equivalent requests. Any client or 245 server &MAY; employ a cache, though a cache cannot be used by a server that 246 is acting as a tunnel. 247 </t> 248 <t> 249 Caching would be useless if it did not significantly improve performance. 250 The goal of caching in HTTP/1.1 is to reuse a prior response message to 251 satisfy a current request. In some cases, a stored response can be reused 252 without the need for a network request, reducing latency and network 253 round-trips; a "freshness" mechanism is used for this purpose (see <xref 254 target="expiration.model" />). Even when a new request is required, it is 255 often possible to reuse all or parts of the payload of a prior response to 256 satisfy the request, thereby reducing network bandwidth usage; a 257 "validation" mechanism is used for this purpose (see <xref 258 target="validation.model" />). 253 259 </t> 254 260 </section> … … 256 262 <section anchor="intro.terminology" title="Terminology"> 257 263 <t> 258 This specification uses a number of terms to refer to the roles played by participants 259 in, and objects of, HTTP caching. 260 </t> 261 <t> 262 <iref item="cacheable" /> 263 <x:dfn>cacheable</x:dfn> 264 <list> 265 <t>A response is cacheable if a cache is allowed to store a copy of the response message 266 for use in answering subsequent requests. Even when a response is cacheable, there might 267 be additional constraints on whether a cache can use the cached copy to satisfy a 268 particular request.</t> 269 </list> 270 </t> 271 <t> 272 <iref item="explicit expiration time" /> 273 <x:dfn>explicit expiration time</x:dfn> 274 <list> 275 <t>The time at which the origin server intends that a representation should no longer be 276 returned by a cache without further validation.</t> 277 </list> 278 </t> 279 <t> 280 <iref item="heuristic expiration time" /> 281 <x:dfn>heuristic expiration time</x:dfn> 282 <list> 283 <t>An expiration time assigned by a cache when no explicit expiration time is 284 available.</t> 285 </list> 286 </t> 287 <t> 288 <iref item="age" /> 289 <x:dfn>age</x:dfn> 290 <list> 291 <t>The age of a response is the time since it was sent by, or successfully validated 292 with, the origin server.</t> 293 </list> 294 </t> 295 <t> 296 <iref item="first-hand" /> 297 <x:dfn>first-hand</x:dfn> 298 <list> 299 <t>A response is first-hand if the freshness model is not in use; i.e., its age is 300 0.</t> 301 </list> 302 </t> 303 <t> 304 <iref item="freshness lifetime" /> 305 <x:dfn>freshness lifetime</x:dfn> 306 <list> 307 <t>The length of time between the generation of a response and its expiration time. </t> 308 </list> 309 </t> 310 <t> 311 <iref item="fresh" /> 312 <x:dfn>fresh</x:dfn> 313 <list> 314 <t>A response is fresh if its age has not yet exceeded its freshness lifetime.</t> 315 </list> 316 </t> 317 <t> 318 <iref item="stale" /> 319 <x:dfn>stale</x:dfn> 320 <list> 321 <t>A response is stale if its age has passed its freshness lifetime (either explicit or heuristic).</t> 322 </list> 323 </t> 324 <t> 325 <iref item="validator" /> 326 <x:dfn>validator</x:dfn> 327 <list> 328 <t>A protocol element (e.g., an entity-tag or a Last-Modified time) that is used to find 329 out whether a stored response has an equivalent copy of a representation.</t> 330 </list> 264 This specification uses a number of terms to refer to the roles played by 265 participants in, and objects of, HTTP caching. 266 </t> 267 <t> 268 <iref item="cacheable" /> 269 <x:dfn>cacheable</x:dfn> 270 <list> 271 <t>A response is cacheable if a cache is allowed to store a copy of the 272 response message for use in answering subsequent requests. Even when a 273 response is cacheable, there might be additional constraints on whether 274 a cache can use the cached copy to satisfy a particular request.</t> 275 </list> 276 </t> 277 <t> 278 <iref item="explicit expiration time" /> 279 <x:dfn>explicit expiration time</x:dfn> 280 <list> 281 <t>The time at which the origin server intends that a representation 282 should no longer be returned by a cache without further validation.</t> 283 </list> 284 </t> 285 <t> 286 <iref item="heuristic expiration time" /> 287 <x:dfn>heuristic expiration time</x:dfn> 288 <list> 289 <t>An expiration time assigned by a cache when no explicit expiration 290 time is available.</t> 291 </list> 292 </t> 293 <t> 294 <iref item="age" /> 295 <x:dfn>age</x:dfn> 296 <list> 297 <t>The age of a response is the time since it was sent by, or 298 successfully validated with, the origin server.</t> 299 </list> 300 </t> 301 <t> 302 <iref item="first-hand" /> 303 <x:dfn>first-hand</x:dfn> 304 <list> 305 <t>A response is first-hand if the freshness model is not in use; i.e., 306 its age is 0.</t> 307 </list> 308 </t> 309 <t> 310 <iref item="freshness lifetime" /> 311 <x:dfn>freshness lifetime</x:dfn> 312 <list> 313 <t>The length of time between the generation of a response and its 314 expiration time.</t> 315 </list> 316 </t> 317 <t> 318 <iref item="fresh" /> 319 <x:dfn>fresh</x:dfn> 320 <list> 321 <t>A response is fresh if its age has not yet exceeded its freshness 322 lifetime.</t> 323 </list> 324 </t> 325 <t> 326 <iref item="stale" /> 327 <x:dfn>stale</x:dfn> 328 <list> 329 <t>A response is stale if its age has passed its freshness lifetime 330 (either explicit or heuristic).</t> 331 </list> 332 </t> 333 <t> 334 <iref item="validator" /> 335 <x:dfn>validator</x:dfn> 336 <list> 337 <t>A protocol element (e.g., an entity-tag or a Last-Modified time) that 338 is used to find out whether a stored response has an equivalent copy of 339 a representation.</t> 340 </list> 331 341 </t> 332 342 <t anchor="shared.and.non-shared.caches"> 333 <iref item="validator" />334 <x:dfn>shared cache</x:dfn>335 <list>336 <t>A cache that is accessible to more than one user. A non-shared cache is337 dedicated to a single user.</t>338 </list>343 <iref item="validator" /> 344 <x:dfn>shared cache</x:dfn> 345 <list> 346 <t>A cache that is accessible to more than one user. A non-shared cache 347 is dedicated to a single user.</t> 348 </list> 339 349 </t> 340 350 </section> … … 347 357 </t> 348 358 <t> 349 An implementation is not compliant if it fails to satisfy one or more 350 ofthe "MUST" or "REQUIRED" level requirements for the protocols it359 An implementation is not compliant if it fails to satisfy one or more of 360 the "MUST" or "REQUIRED" level requirements for the protocols it 351 361 implements. An implementation that satisfies all the "MUST" or "REQUIRED" 352 level and all the "SHOULD" level requirements for its protocols is said 353 to be "unconditionally compliant"; one that satisfies all the "MUST"354 level requirements but not all the "SHOULD" level requirements for its355 protocolsis said to be "conditionally compliant".362 level and all the "SHOULD" level requirements for its protocols is said to 363 be "unconditionally compliant"; one that satisfies all the "MUST" level 364 requirements but not all the "SHOULD" level requirements for its protocols 365 is said to be "conditionally compliant". 356 366 </t> 357 367 </section> 358 368 359 369 <section title="Syntax Notation" anchor="notation"> 360 <x:anchor-alias value="ALPHA"/> 361 <x:anchor-alias value="CR"/> 362 <x:anchor-alias value="DIGIT"/> 363 <x:anchor-alias value="DQUOTE"/> 364 <x:anchor-alias value="LF"/> 365 <x:anchor-alias value="OCTET"/> 366 <x:anchor-alias value="SP"/> 367 <x:anchor-alias value="VCHAR"/> 368 <x:anchor-alias value="WSP"/> 369 <t> 370 This specification uses the ABNF syntax defined in ¬ation; (which 371 extends the syntax defined in <xref target="RFC5234"/> with a list rule). 372 <xref target="collected.abnf"/> shows the collected ABNF, with the list 373 rule expanded. 374 </t> 375 <t> 376 The following core rules are included by 377 reference, as defined in <xref target="RFC5234" x:fmt="," x:sec="B.1"/>: 378 ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), 379 DIGIT (decimal 0-9), DQUOTE (double quote), 380 HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), 381 OCTET (any 8-bit sequence of data), SP (space), 382 VCHAR (any visible USASCII character), 383 and WSP (whitespace). 370 <x:anchor-alias value="ALPHA"/> 371 <x:anchor-alias value="CR"/> 372 <x:anchor-alias value="DIGIT"/> 373 <x:anchor-alias value="DQUOTE"/> 374 <x:anchor-alias value="LF"/> 375 <x:anchor-alias value="OCTET"/> 376 <x:anchor-alias value="SP"/> 377 <x:anchor-alias value="VCHAR"/> 378 <x:anchor-alias value="WSP"/> 379 <t> 380 This specification uses the ABNF syntax defined in ¬ation; (which 381 extends the syntax defined in <xref target="RFC5234"/> with a list rule). 382 <xref target="collected.abnf"/> shows the collected ABNF, with the list 383 rule expanded. 384 </t> 385 <t> 386 The following core rules are included by reference, as defined in <xref 387 target="RFC5234" x:fmt="," x:sec="B.1"/>: ALPHA (letters), CR (carriage 388 return), CRLF (CR LF), CTL (controls), DIGIT (decimal 0-9), DQUOTE (double 389 quote), HEXDIG (hexadecimal 0-9/A-F/a-f), LF (line feed), OCTET (any 8-bit 390 sequence of data), SP (space), VCHAR (any visible USASCII character), and 391 WSP (whitespace). 384 392 </t> 385 393 386 394 <section title="Core Rules" anchor="core.rules"> 387 <x:anchor-alias value="quoted-string"/>388 <x:anchor-alias value="token"/>389 <x:anchor-alias value="OWS"/>390 <t> 391 The core rules below are defined in &basic-rules;:395 <x:anchor-alias value="quoted-string"/> 396 <x:anchor-alias value="token"/> 397 <x:anchor-alias value="OWS"/> 398 <t> 399 The core rules below are defined in &basic-rules;: 392 400 </t> 393 401 <figure><artwork type="abnf2616"> … … 398 406 </section> 399 407 400 <section title="ABNF Rules defined in other Parts of the Specification" anchor="abnf.dependencies"> 401 <x:anchor-alias value="field-name"/> 402 <x:anchor-alias value="HTTP-date"/> 403 <x:anchor-alias value="port"/> 404 <x:anchor-alias value="pseudonym"/> 405 <x:anchor-alias value="uri-host"/> 406 <t> 407 The ABNF rules below are defined in other parts: 408 <section title="ABNF Rules defined in other Parts of the Specification" 409 anchor="abnf.dependencies"> 410 <x:anchor-alias value="field-name"/> 411 <x:anchor-alias value="HTTP-date"/> 412 <x:anchor-alias value="port"/> 413 <x:anchor-alias value="pseudonym"/> 414 <x:anchor-alias value="uri-host"/> 415 <t> 416 The ABNF rules below are defined in other parts: 408 417 </t> 409 418 <figure><!--Part1--><artwork type="abnf2616"> … … 423 432 <section anchor="response.cacheability" title="Response Cacheability"> 424 433 <t> 425 A cache &MUST-NOT; store a response to any request, unless: 426 <list style="symbols"> 427 <t>The request method is understood by the cache and defined as being cacheable, and</t> 428 <t>the response status code is understood by the cache, and</t> 429 <t>the "no-store" cache directive (see <xref target="header.cache-control" />) does not 430 appear in request or response headers, and</t> 431 <t>the "private" cache response directive (see <xref target="cache-response-directive" /> 432 does not appear in the response, if the cache is shared, and</t> 433 <t>the "Authorization" header (see &header-authorization;) does not appear in the request, if 434 the cache is shared, unless the response explicitly allows it (see <xref 435 target="caching.authenticated.responses" />), and</t> 436 <t>the response either: 437 <list style="symbols"> 438 <t>contains an Expires header (see <xref target="header.expires" />), or</t> 439 <t>contains a max-age response cache directive (see <xref target="cache-response-directive" />), or</t> 440 <t>contains a s-maxage response cache directive and the cache is shared, or</t> 441 <t>contains a Cache Control Extension (see <xref target="cache.control.extensions" />) that allows it to be cached, or</t> 442 <t>has a status code that can be served with heuristic freshness (see <xref 443 target="heuristic.freshness" />).</t> 444 </list> 445 </t> 434 A cache &MUST-NOT; store a response to any request, unless: 435 <list style="symbols"> 436 <t>The request method is understood by the cache and defined as being 437 cacheable, and</t> 438 <t>the response status code is understood by the cache, and</t> 439 <t>the "no-store" cache directive (see <xref 440 target="header.cache-control" />) does not appear in request or response 441 headers, and</t> 442 <t>the "private" cache response directive (see <xref 443 target="cache-response-directive" /> does not appear in the response, if 444 the cache is shared, and</t> 445 <t>the "Authorization" header (see &header-authorization;) does not 446 appear in the request, if the cache is shared, unless the response 447 explicitly allows it (see <xref target="caching.authenticated.responses" 448 />), and</t> 449 <t>the response either: 450 <list style="symbols"> 451 <t>contains an Expires header (see <xref target="header.expires" 452 />), or</t> 453 <t>contains a max-age response cache directive (see <xref 454 target="cache-response-directive" />), or</t> 455 <t>contains a s-maxage response cache directive and the cache is 456 shared, or</t> 457 <t>contains a Cache Control Extension (see <xref 458 target="cache.control.extensions" />) that allows it to be cached, 459 or</t> 460 <t>has a status code that can be served with heuristic freshness 461 (see <xref target="heuristic.freshness" />).</t> 462 </list> 463 </t> 464 </list> 465 </t> 466 <t> 467 In this context, a cache has "understood" a request method or a response 468 status code if it recognises it and implements any cache-specific 469 behaviour. In particular, 206 Partial Content responses cannot be cached by 470 an implementation that does not handle partial content (see <xref 471 target="errors.or.incomplete.response.cache.behavior" />). 472 </t> 473 <t> 474 Note that in normal operation, most caches will not store a response that 475 has neither a cache validator nor an explicit expiration time, as such 476 responses are not usually useful to store. However, caches are not 477 prohibited from storing such responses. 478 </t> 479 480 <section anchor="errors.or.incomplete.response.cache.behavior" 481 title="Storing Partial and Incomplete Responses"> 482 <t> 483 A cache that receives an incomplete response (for example, with fewer bytes 484 of data than specified in a Content-Length header) can store the response, 485 but &MUST; treat it as a partial response &partial;. Partial responses can 486 be combined as described in &combining-byte-ranges;; the result might be a 487 full response or might still be partial. A cache &MUST-NOT; return a 488 partial response to a client without explicitly marking it as such using 489 the 206 (Partial Content) status code. 490 </t> 491 <t> 492 A cache that does not support the Range and Content-Range headers 493 &MUST-NOT; store incomplete or partial responses. 494 </t> 495 </section> 496 497 </section> 498 499 500 <section anchor="constructing.responses.from.caches" 501 title="Constructing Responses from Caches"> 502 <t> 503 For a presented request, a cache &MUST-NOT; return a stored response, 504 unless: 505 <list style="symbols"> 506 <t>The presented Effective Request URI (&effective-request-uri;) and 507 that of the stored response match, and</t> 508 <t>the request method associated with the stored response allows it to 509 be used for the presented request, and</t> 510 <t>selecting request-headers nominated by the stored response (if any) 511 match those presented (see <xref target="caching.negotiated.responses" 512 />), and</t> 513 <t>the presented request and stored response are free from directives 514 that would prevent its use (see <xref target="header.cache-control" /> 515 and <xref target="header.pragma"/>), and</t> 516 <t>the stored response is either: 517 <list style="symbols"> 518 <t>fresh (see <xref target="expiration.model" />), or</t> 519 <t>allowed to be served stale (see <xref 520 target="serving.stale.responses" />), or</t> 521 <t>successfully validated (see <xref target="validation.model" 522 />).</t> 523 </list> 524 </t> 446 525 </list> 447 526 </t> 448 527 <t> 449 In this context, a cache has "understood" a request method or a response status 450 code if it recognises it and implements any cache-specific behaviour. In 451 particular, 206 Partial Content responses cannot be cached by an 452 implementation that does not handle partial content 453 (see <xref target="errors.or.incomplete.response.cache.behavior" />). 454 </t> 455 <t> 456 Note that in normal operation, most caches will not store a response that has neither a 457 cache validator nor an explicit expiration time, as such responses are not usually 458 useful to store. However, caches are not prohibited from storing such responses. 459 </t> 460 461 <section anchor="errors.or.incomplete.response.cache.behavior" title="Storing Partial and Incomplete Responses"> 462 <t> 463 A cache that receives an incomplete response (for example, with fewer bytes of data 464 than specified in a Content-Length header) can store the response, but &MUST; 465 treat it as a partial response &partial;. Partial responses 466 can be combined as described in &combining-byte-ranges;; the result might be a 467 full response or might still be partial. A cache &MUST-NOT; return a partial 468 response to a client without explicitly marking it as such using the 206 (Partial 469 Content) status code. 470 </t> 471 <t> 472 A cache that does not support the Range and Content-Range headers &MUST-NOT; store 473 incomplete or partial responses. 474 </t> 475 </section> 476 477 </section> 478 479 480 <section anchor="constructing.responses.from.caches" title="Constructing Responses from Caches"> 481 <t> 482 For a presented request, a cache &MUST-NOT; return a stored response, unless: 483 <list style="symbols"> 484 <t>The presented Effective Request URI (&effective-request-uri;) and that of the stored response match, and</t> 485 <t>the request method associated with the stored response allows it to be 486 used for the presented request, and</t> 487 <t>selecting request-headers nominated by the stored response (if any) match those presented (see <xref 488 target="caching.negotiated.responses" />), and</t> 489 <t>the presented request and stored response are free from directives that would prevent 490 its use (see <xref target="header.cache-control" /> and <xref target="header.pragma"/>), 491 and</t> 492 <t>the stored response is either: 493 <list style="symbols"> 494 <t>fresh (see <xref target="expiration.model" />), or</t> 495 <t>allowed to be served stale (see <xref target="serving.stale.responses" />), or</t> 496 <t>successfully validated (see <xref target="validation.model" />).</t> 497 </list> 498 </t> 499 </list> 500 </t> 501 <t> 502 When a stored response is used to satisfy a request without validation, caches &MUST; include a 503 single Age header field (<xref target="header.age" />) in the response with a value equal to the stored response's 504 current_age; see <xref target="age.calculations" />. 505 </t> 506 <t> 507 Requests with methods that are unsafe (&safe-methods;) &MUST; be written through the cache to 508 the origin server; i.e., a cache must not reply to such a request before having forwarded the request and having received a 509 corresponding response. 510 </t> 511 <t> 512 Also, note that unsafe requests might invalidate already stored responses; see 513 <xref target="invalidation.after.updates.or.deletions" />. 514 </t> 515 <t> 516 Caches &MUST; use the most recent response (as determined by the Date header) when 517 more than one suitable response is stored. They can also forward a request with 518 "Cache-Control: max-age=0" or "Cache-Control: no-cache" to disambiguate which response to 519 use. 528 When a stored response is used to satisfy a request without validation, 529 caches &MUST; include a single Age header field (<xref target="header.age" 530 />) in the response with a value equal to the stored response's 531 current_age; see <xref target="age.calculations" />. 532 </t> 533 <t> 534 Requests with methods that are unsafe (&safe-methods;) &MUST; be written 535 through the cache to the origin server; i.e., a cache must not reply to 536 such a request before having forwarded the request and having received a 537 corresponding response. 538 </t> 539 <t> 540 Also, note that unsafe requests might invalidate already stored responses; 541 see <xref target="invalidation.after.updates.or.deletions" />. 542 </t> 543 <t> 544 Caches &MUST; use the most recent response (as determined by the Date 545 header) when more than one suitable response is stored. They can also 546 forward a request with "Cache-Control: max-age=0" or "Cache-Control: 547 no-cache" to disambiguate which response to use. 520 548 </t> 521 549 </section> … … 523 551 <section anchor="expiration.model" title="Freshness Model"> 524 552 <t> 525 When a response is "fresh" in the cache, it can be used to satisfy subsequent 526 requests without contacting the origin server, thereby improving efficiency. 527 </t> 528 <t> 529 The primary mechanism for determining freshness is for an origin server to provide an 530 explicit expiration time in the future, using either the Expires header (<xref 531 target="header.expires" />) or the max-age response cache directive (<xref 532 target="cache-response-directive" />). Generally, origin servers will assign future 533 explicit expiration times to responses in the belief that the representation is not likely to 534 change in a semantically significant way before the expiration time is reached. 535 </t> 536 <t> 537 If an origin server wishes to force a cache to validate every request, it can 538 assign an explicit expiration time in the past. This means that the response is always 539 stale, so that caches should validate it before using it for subsequent requests. 540 <cref anchor="TODO-response-stale">This wording might cause confusion, because the response might still be served stale.</cref> 541 </t> 542 <t> 543 Since origin servers do not always provide explicit expiration times, HTTP caches &MAY; 544 assign heuristic expiration times when explicit times are not specified, employing algorithms that 545 use other header values (such as the Last-Modified time) to estimate a plausible 546 expiration time. The HTTP/1.1 specification does not provide specific algorithms, but does 547 impose worst-case constraints on their results. 553 When a response is "fresh" in the cache, it can be used to satisfy 554 subsequent requests without contacting the origin server, thereby improving 555 efficiency. 556 </t> 557 <t> 558 The primary mechanism for determining freshness is for an origin server to 559 provide an explicit expiration time in the future, using either the Expires 560 header (<xref target="header.expires" />) or the max-age response cache 561 directive (<xref target="cache-response-directive" />). Generally, origin 562 servers will assign future explicit expiration times to responses in the 563 belief that the representation is not likely to change in a semantically 564 significant way before the expiration time is reached. 565 </t> 566 <t> 567 If an origin server wishes to force a cache to validate every request, it 568 can assign an explicit expiration time in the past. This means that the 569 response is always stale, so that caches should validate it before using it 570 for subsequent requests. <cref anchor="TODO-response-stale">This wording 571 might cause confusion, because the response might still be served 572 stale.</cref> 573 </t> 574 <t> 575 Since origin servers do not always provide explicit expiration times, HTTP 576 caches &MAY; assign heuristic expiration times when explicit times are not 577 specified, employing algorithms that use other header values (such as the 578 Last-Modified time) to estimate a plausible expiration time. The HTTP/1.1 579 specification does not provide specific algorithms, but does impose 580 worst-case constraints on their results. 548 581 </t> 549 582 <figure> … … 556 589 </figure> 557 590 <t> 558 The freshness_lifetime is defined in <xref target="calculating.freshness.lifetime" />; 559 the current_age is defined in <xref target="age.calculations" />. 560 </t> 561 <t> 562 Additionally, clients might need to influence freshness calculation. They can do this using 563 several request cache directives, with the effect of either increasing or loosening 564 constraints on freshness. See <xref target="cache-request-directive" />. 565 </t> 566 <t> 567 <cref anchor="ISSUE-no-req-for-directives">there are not requirements directly applying to cache-request-directives and 568 freshness.</cref> 569 </t> 570 <t> 571 Note that freshness applies only to cache operation; it cannot be used to force a user agent 572 to refresh its display or reload a resource. See <xref target="history.lists" /> for an explanation of 573 the difference between caches and history mechanisms. 574 </t> 575 576 <section anchor="calculating.freshness.lifetime" title="Calculating Freshness Lifetime"> 577 <t> 578 A cache can calculate the freshness lifetime (denoted as freshness_lifetime) of a 579 response by using the first match of: 580 <list style="symbols"> 581 <t>If the cache is shared and the s-maxage response cache directive (<xref 591 The freshness_lifetime is defined in <xref 592 target="calculating.freshness.lifetime" />; the current_age is defined in 593 <xref target="age.calculations" />. 594 </t> 595 <t> 596 Additionally, clients might need to influence freshness calculation. They 597 can do this using several request cache directives, with the effect of 598 either increasing or loosening constraints on freshness. See <xref 599 target="cache-request-directive" />. 600 </t> 601 <t> 602 <cref anchor="ISSUE-no-req-for-directives">there are not requirements 603 directly applying to cache-request-directives and freshness.</cref> 604 </t> 605 <t> 606 Note that freshness applies only to cache operation; it cannot be used to 607 force a user agent to refresh its display or reload a resource. See <xref 608 target="history.lists" /> for an explanation of the difference between 609 caches and history mechanisms. 610 </t> 611 612 <section anchor="calculating.freshness.lifetime" 613 title="Calculating Freshness Lifetime"> 614 <t> 615 A cache can calculate the freshness lifetime (denoted as 616 freshness_lifetime) of a response by using the first match of: 617 <list style="symbols"> 618 <t>If the cache is shared and the s-maxage response cache directive 619 (<xref target="cache-response-directive" />) is present, use its value, 620 or</t> 621 <t>If the max-age response cache directive (<xref 582 622 target="cache-response-directive" />) is present, use its value, or</t> 583 <t>If the max-age response cache directive (<xref target="cache-response-directive"584 />) is present, use its value, or</t>585 <t>If the Expires response header (<xref target="header.expires" />) is present, use586 its value minus the value of the Date response header, or</t>587 <t>Otherwise, no explicit expiration time is present in the response. A heuristic588 freshness lifetime might be applicable; see <xreftarget="heuristic.freshness" />.</t>589 </list>590 </t> 591 <t> 592 Note that this calculation is not vulnerable to clock skew, since all of the593 information comes from the origin server.623 <t>If the Expires response header (<xref target="header.expires" />) is 624 present, use its value minus the value of the Date response header, 625 or</t> 626 <t>Otherwise, no explicit expiration time is present in the response. A 627 heuristic freshness lifetime might be applicable; see <xref 628 target="heuristic.freshness" />.</t> 629 </list> 630 </t> 631 <t> 632 Note that this calculation is not vulnerable to clock skew, since all of 633 the information comes from the origin server. 594 634 </t> 595 635 596 636 <section anchor="heuristic.freshness" title="Calculating Heuristic Freshness"> 597 637 <t> 598 If no explicit expiration time is present in a stored response that has a status code 599 whose definition allows heuristic freshness to be used (including the following 600 in &status-codes;: 200, 203, 206, 300, 301 and 410), a heuristic expiration time &MAY; be 601 calculated. Heuristics &MUST-NOT; be used for response status codes that do not explicitly 602 allow it. 603 </t> 604 <t> 605 When a heuristic is used to calculate freshness lifetime, the cache &SHOULD; 606 attach a Warning header with a 113 warn-code to the response if its current_age is 607 more than 24 hours and such a warning is not already present. 608 </t> 609 <t> 610 Also, if the response has a Last-Modified header (&header-last-modified;), the 611 heuristic expiration value &SHOULD; be no more than some fraction of the interval 612 since that time. A typical setting of this fraction might be 10%. 638 If no explicit expiration time is present in a stored response that has a 639 status code whose definition allows heuristic freshness to be used 640 (including the following in &status-codes;: 200, 203, 206, 300, 301 and 641 410), a heuristic expiration time &MAY; be calculated. Heuristics 642 &MUST-NOT; be used for response status codes that do not explicitly allow 643 it. 644 </t> 645 <t> 646 When a heuristic is used to calculate freshness lifetime, the cache 647 &SHOULD; attach a Warning header with a 113 warn-code to the response if 648 its current_age is more than 24 hours and such a warning is not already 649 present. 650 </t> 651 <t> 652 Also, if the response has a Last-Modified header (&header-last-modified;), 653 the heuristic expiration value &SHOULD; be no more than some fraction of 654 the interval since that time. A typical setting of this fraction might be 655 10%. 613 656 </t> 614 657 <x:note> 615 <t>616 <x:h>Note:</x:h> RFC 2616 (<xref target="RFC2616" x:fmt="," x:sec="13.9"/>)617 required that caches do not calculate heuristic freshness for URLs with618 query components (i.e., those containing '?'). In practice, this has not619 been widely implemented. Therefore, servers are encouraged to send explicit620 directives (e.g., Cache-Control: no-cache) if they wish to preclude621 caching.622 </t>658 <t> 659 <x:h>Note:</x:h> RFC 2616 (<xref target="RFC2616" x:fmt="," 660 x:sec="13.9"/>) required that caches do not calculate heuristic 661 freshness for URLs with query components (i.e., those containing '?'). 662 In practice, this has not been widely implemented. Therefore, servers 663 are encouraged to send explicit directives (e.g., Cache-Control: 664 no-cache) if they wish to preclude caching. 665 </t> 623 666 </x:note> 624 667 </section> … … 627 670 <section anchor="age.calculations" title="Calculating Age"> 628 671 <t> 629 HTTP/1.1 uses the Age response-header to convey the estimated age of the response 630 message when obtained from a cache. The Age field value is the cache's estimate of the 631 amount of time since the response was generated or validated by the origin server. In 632 essence, the Age value is the sum of the time that the response has been resident in 633 each of the caches along the path from the origin server, plus the amount of time it has 634 been in transit along network paths. 635 </t> 636 <t> 637 The following data is used for the age calculation: 638 </t> 639 <t> 640 <x:dfn>age_value</x:dfn> 641 <list> 642 <t> 643 The term "age_value" denotes the value of the Age header (<xref target="header.age"/>), 644 in a form appropriate for arithmetic operation; or 0, if not available. 645 </t> 646 </list> 647 </t> 648 <t> 649 <x:dfn>date_value</x:dfn> 650 <list> 651 <t> 652 HTTP/1.1 requires origin servers to send a Date header, if possible, 653 with every response, giving the time at which the response was generated. 654 The term "date_value" denotes the value of the Date header, in a form 655 appropriate for arithmetic operations. See &header-date; for the definition 656 of the Date header, and for requirements regarding responses without a 657 Date response header. 658 </t> 659 </list> 660 </t> 661 <t> 662 <x:dfn>now</x:dfn> 663 <list> 664 <t> 665 The term "now" means "the current value of the clock at the host 666 performing the calculation". Hosts that use HTTP, but especially hosts 667 running origin servers and caches, &SHOULD; use NTP 668 (<xref target="RFC1305"/>) or some similar protocol to synchronize their 669 clocks to a globally accurate time standard. 670 </t> 671 </list> 672 </t> 673 <t> 674 <x:dfn>request_time</x:dfn> 675 <list> 676 <t> 677 The current value of the clock at the host at the time the request 678 resulting in the stored response was made. 679 </t> 680 </list> 681 </t> 682 <t> 683 <x:dfn>response_time</x:dfn> 684 <list> 685 <t> 686 The current value of the clock at the host at the time the response was 687 received. 688 </t> 689 </list> 690 </t> 691 <t> 692 A response's age can be calculated in two entirely independent ways: 693 <list style="numbers"> 694 <t>the "apparent_age": response_time minus date_value, if the local clock is reasonably well synchronized to the 695 origin server's clock. If the result is negative, the result is replaced by zero.</t> 696 <t>the "corrected_age_value", if all of the caches along the response path implement HTTP/1.1; 697 note this value &MUST; be interpreted relative to the time the 698 request was initiated, not the time that the response was received.</t> 699 </list> 672 HTTP/1.1 uses the Age response-header to convey the estimated age of the 673 response message when obtained from a cache. The Age field value is the 674 cache's estimate of the amount of time since the response was generated or 675 validated by the origin server. In essence, the Age value is the sum of the 676 time that the response has been resident in each of the caches along the 677 path from the origin server, plus the amount of time it has been in transit 678 along network paths. 679 </t> 680 <t> 681 The following data is used for the age calculation: 682 </t> 683 <t> 684 <x:dfn>age_value</x:dfn> 685 <list> 686 <t> 687 The term "age_value" denotes the value of the Age header (<xref 688 target="header.age"/>), in a form appropriate for arithmetic 689 operation; or 0, if not available. 690 </t> 691 </list> 692 </t> 693 <t> 694 <x:dfn>date_value</x:dfn> 695 <list> 696 <t> 697 HTTP/1.1 requires origin servers to send a Date header, if possible, 698 with every response, giving the time at which the response was 699 generated. The term "date_value" denotes the value of the Date 700 header, in a form appropriate for arithmetic operations. See 701 &header-date; for the definition of the Date header, and for 702 requirements regarding responses without a Date response header. 703 </t> 704 </list> 705 </t> 706 <t> 707 <x:dfn>now</x:dfn> 708 <list> 709 <t> 710 The term "now" means "the current value of the clock at the host 711 performing the calculation". Hosts that use HTTP, but especially 712 hosts running origin servers and caches, &SHOULD; use NTP (<xref 713 target="RFC1305"/>) or some similar protocol to synchronize their 714 clocks to a globally accurate time standard. 715 </t> 716 </list> 717 </t> 718 <t> 719 <x:dfn>request_time</x:dfn> 720 <list> 721 <t> 722 The current value of the clock at the host at the time the request 723 resulting in the stored response was made. 724 </t> 725 </list> 726 </t> 727 <t> 728 <x:dfn>response_time</x:dfn> 729 <list> 730 <t> 731 The current value of the clock at the host at the time the response 732 was received. 733 </t> 734 </list> 735 </t> 736 <t> 737 A response's age can be calculated in two entirely independent ways: 738 <list style="numbers"> 739 <t>the "apparent_age": response_time minus date_value, if the local 740 clock is reasonably well synchronized to the origin server's clock. If 741 the result is negative, the result is replaced by zero.</t> 742 <t>the "corrected_age_value", if all of the caches along the response 743 path implement HTTP/1.1; note this value &MUST; be interpreted relative 744 to the time the request was initiated, not the time that the response 745 was received.</t> 746 </list> 700 747 </t> 701 748 <figure> … … 713 760 </artwork></figure> 714 761 <t> 715 The current_age of a stored response can then be calculated by adding the amount of716 time (in seconds) since the stored response was last validated by the origin server to717 the corrected_initial_age.762 The current_age of a stored response can then be calculated by adding the 763 amount of time (in seconds) since the stored response was last validated by 764 the origin server to the corrected_initial_age. 718 765 </t> 719 766 <figure><artwork type="code"> … … 725 772 <section anchor="serving.stale.responses" title="Serving Stale Responses"> 726 773 <t> 727 A "stale" response is one that either has explicit expiry information or is allowed to 728 have heuristic expiry calculated, but is not fresh according to the calculations in 729 <xref target="expiration.model" />. 730 </t> 731 <t> 732 Caches &MUST-NOT; return a stale response if it is prohibited by an explicit 733 in-protocol directive (e.g., by a "no-store" or "no-cache" cache directive, a 734 "must-revalidate" cache-response-directive, or an applicable "s-maxage" or 735 "proxy-revalidate" cache-response-directive; see <xref target="cache-response-directive"/>). 736 </t> 737 <t> 738 Caches &SHOULD-NOT; return stale responses unless they are 739 disconnected (i.e., it cannot contact the origin server or otherwise find a forward path) 740 or otherwise explicitly allowed (e.g., the max-stale request directive; see <xref target="cache-request-directive" />). 741 </t> 742 <t> 743 Stale responses &SHOULD; have a Warning header with the 110 warn-code (see <xref 744 target="header.warning" />). Likewise, the 112 warn-code &SHOULD; be sent on stale responses if 745 the cache is disconnected. 746 </t> 747 <t> 748 If a cache receives a first-hand response (either an entire response, or a 304 (Not 749 Modified) response) that it would normally forward to the requesting client, and the 750 received response is no longer fresh, the cache &SHOULD; forward it to the 751 requesting client without adding a new Warning (but without removing any existing 752 Warning headers). A cache &SHOULD-NOT; attempt to validate a response simply because 753 that response became stale in transit. 774 A "stale" response is one that either has explicit expiry information or is 775 allowed to have heuristic expiry calculated, but is not fresh according to 776 the calculations in <xref target="expiration.model" />. 777 </t> 778 <t> 779 Caches &MUST-NOT; return a stale response if it is prohibited by an 780 explicit in-protocol directive (e.g., by a "no-store" or "no-cache" cache 781 directive, a "must-revalidate" cache-response-directive, or an applicable 782 "s-maxage" or "proxy-revalidate" cache-response-directive; see <xref 783 target="cache-response-directive"/>). 784 </t> 785 <t> 786 Caches &SHOULD-NOT; return stale responses unless they are disconnected 787 (i.e., it cannot contact the origin server or otherwise find a forward 788 path) or otherwise explicitly allowed (e.g., the max-stale request 789 directive; see <xref target="cache-request-directive" />). 790 </t> 791 <t> 792 Stale responses &SHOULD; have a Warning header with the 110 warn-code (see 793 <xref target="header.warning" />). Likewise, the 112 warn-code &SHOULD; be 794 sent on stale responses if the cache is disconnected. 795 </t> 796 <t> 797 If a cache receives a first-hand response (either an entire response, or a 798 304 (Not Modified) response) that it would normally forward to the 799 requesting client, and the received response is no longer fresh, the cache 800 &SHOULD; forward it to the requesting client without adding a new Warning 801 (but without removing any existing Warning headers). A cache &SHOULD-NOT; 802 attempt to validate a response simply because that response became stale in 803 transit. 754 804 </t> 755 805 </section> … … 758 808 <section anchor="validation.model" title="Validation Model"> 759 809 <t> 760 When a cache has one or more stored responses for a requested URI, but cannot 761 serve any of them (e.g., because they are not fresh, or one cannot be selected; 762 see <xref target="caching.negotiated.responses"/>), 763 it can use the conditional request mechanism &conditional; in the forwarded 764 request to give the origin server an opportunity to both select a valid stored 765 response to be used, and to update it. This process is known as "validating" 766 or "revalidating" the stored response. 767 </t> 768 <t> 769 When sending such a conditional request, the cache &SHOULD; add an If-Modified-Since 770 header whose value is that of the Last-Modified header from the selected 771 (see <xref target="caching.negotiated.responses"/>) stored response, if available. 772 </t> 773 <t> 774 Additionally, the cache &SHOULD; add an If-None-Match header whose value 775 is that of the ETag header(s) from all responses stored for the requested URI, 776 if present. However, if any of the stored responses contains only partial 777 content, its entity-tag &SHOULD-NOT; be included in the If-None-Match header 778 field unless the request is for a range that would be fully satisfied by 779 that stored response. 780 </t> 781 <t> 782 A 304 (Not Modified) response status code indicates that the stored 783 response can be updated and reused; see <xref target="combining.headers"/>. 784 </t> 785 <t> 786 A full response (i.e., one with a response body) indicates that none 787 of the stored responses nominated in the conditional request is 788 suitable. Instead, the full response &SHOULD; be used to satisfy the 789 request and &MAY; replace the stored response. 790 </t> 791 <t> 792 If a cache receives a 5xx response while attempting to validate a response, it &MAY; 793 either forward this response to the requesting client, or act as if the server failed to 794 respond. In the latter case, it &MAY; return a previously stored response (see <xref 795 target="serving.stale.responses" />). 796 </t> 797 </section> 798 799 <section anchor="invalidation.after.updates.or.deletions" title="Request Methods that Invalidate"> 800 <t> 801 Because unsafe methods (&safe-methods;) have the potential for changing state on the 802 origin server, intervening caches can use them to keep their contents 803 up-to-date. 804 </t> 805 <t> 810 When a cache has one or more stored responses for a requested URI, but 811 cannot serve any of them (e.g., because they are not fresh, or one cannot 812 be selected; see <xref target="caching.negotiated.responses"/>), it can use 813 the conditional request mechanism &conditional; in the forwarded request to 814 give the origin server an opportunity to both select a valid stored 815 response to be used, and to update it. This process is known as 816 "validating" or "revalidating" the stored response. 817 </t> 818 <t> 819 When sending such a conditional request, the cache &SHOULD; add an 820 If-Modified-Since header whose value is that of the Last-Modified header 821 from the selected (see <xref target="caching.negotiated.responses"/>) 822 stored response, if available. 823 </t> 824 <t> 825 Additionally, the cache &SHOULD; add an If-None-Match header whose value is 826 that of the ETag header(s) from all responses stored for the requested URI, 827 if present. However, if any of the stored responses contains only partial 828 content, its entity-tag &SHOULD-NOT; be included in the If-None-Match 829 header field unless the request is for a range that would be fully 830 satisfied by that stored response. 831 </t> 832 <t> 833 A 304 (Not Modified) response status code indicates that the stored 834 response can be updated and reused; see <xref target="combining.headers"/>. 835 </t> 836 <t> 837 A full response (i.e., one with a response body) indicates that none of the 838 stored responses nominated in the conditional request is suitable. Instead, 839 the full response &SHOULD; be used to satisfy the request and &MAY; replace 840 the stored response. 841 </t> 842 <t> 843 If a cache receives a 5xx response while attempting to validate a response, 844 it &MAY; either forward this response to the requesting client, or act as 845 if the server failed to respond. In the latter case, it &MAY; return a 846 previously stored response (see <xref target="serving.stale.responses" />). 847 </t> 848 </section> 849 850 <section anchor="invalidation.after.updates.or.deletions" 851 title="Request Methods that Invalidate"> 852 <t> 853 Because unsafe methods (&safe-methods;) have the potential for changing 854 state on the origin server, intervening caches can use them to keep their 855 contents up-to-date. 856 </t> 857 <t> 858 <<<<<<< .mine 859 The following HTTP methods &MUST; cause a cache to invalidate the Effective 860 Request URI (&effective-request-uri;) as well as the URI(s) in the Location 861 and Content-Location headers (if present): 862 <list style="symbols"> 863 <t>PUT</t> 864 <t>DELETE</t> 865 <t>POST</t> 866 </list> 867 ======= 806 868 In a succesful exchange (&status.2xx;), the following HTTP methods &MUST; cause a cache 807 869 to invalidate the Effective Request URI (&effective-request-uri;) as well … … 812 874 <t>POST</t> 813 875 </list> 814 </t> 815 <t> 816 An invalidation based on a URI from a Location or Content-Location header &MUST-NOT; 817 be performed if the host part of that URI differs from the host part in the Effective Request URI (&effective-request-uri;). 818 This helps prevent denial of service attacks. 819 </t> 820 <t> 821 A cache that passes through requests for methods it does not understand &SHOULD; 822 invalidate the Effective Request URI (&effective-request-uri;). 823 </t> 824 <t> 825 Here, "invalidate" means that the cache will either remove all stored responses related 826 to the Effective Request URI, or will mark these as "invalid" and in need of a mandatory validation 827 before they can be returned in response to a subsequent request. 828 </t> 829 <t> 830 Note that this does not guarantee that all appropriate responses are invalidated. For 831 example, the request that caused the change at the origin server might not have gone 832 through the cache where a response is stored. 833 </t> 834 </section> 835 836 <section anchor="caching.authenticated.responses" title="Shared Caching of Authenticated Responses"> 837 838 <t>Shared caches &MUST-NOT; use a cached response to a request with an Authorization header (&header-authorization;) to satisfy any subsequent request unless a cache directive that allows such responses to be stored is present in the response.</t> 839 840 <t>In this specification, the following Cache-Control response directives (<xref target="cache-response-directive"/>) have such an effect: must-revalidate, public, s-maxage.</t> 841 842 <t>Note that cached responses that contain the "must-revalidate" and/or "s-maxage" response directives are not allowed to be served stale (<xref target="serving.stale.responses"/>) by shared caches. In particular, a response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be used to satisfy a subsequent request without revalidating it on the origin server.</t> 843 </section> 844 845 <section anchor="caching.negotiated.responses" title="Caching Negotiated Responses"> 846 <t> 847 When a cache receives a request that can be satisfied by a stored response 848 that has a Vary header field (<xref target="header.vary"/>), it &MUST-NOT; use that 849 response unless all of the selecting request-headers nominated by the Vary header match 850 in both the original request (i.e., that associated with the stored response), 851 and the presented request. 852 </t> 853 <t> 854 The selecting request-headers from two requests are defined to match 855 if and only if those in the first request can be transformed to those in the 856 second request by applying any of the following: 857 <list style="symbols"> 858 <t> 859 adding or removing whitespace, where allowed in the header's syntax 860 </t> 861 <t> 862 combining multiple message-header fields with the same field name (see 863 &header-fields;) 864 </t> 865 <t> 866 normalizing both header values in a way that is known to have identical 867 semantics, according to the header's specification (e.g., re-ordering field values 868 when order is not significant; case-normalization, where values are defined to be 869 case-insensitive) 870 </t> 876 >>>>>>> .r948 877 </t> 878 <t> 879 An invalidation based on a URI from a Location or Content-Location header 880 &MUST-NOT; be performed if the host part of that URI differs from the host 881 part in the Effective Request URI (&effective-request-uri;). This helps 882 prevent denial of service attacks. 883 </t> 884 <t> 885 A cache that passes through requests for methods it does not understand 886 &SHOULD; invalidate the Effective Request URI (&effective-request-uri;). 887 </t> 888 <t> 889 Here, "invalidate" means that the cache will either remove all stored 890 responses related to the Effective Request URI, or will mark these as 891 "invalid" and in need of a mandatory validation before they can be returned 892 in response to a subsequent request. 893 </t> 894 <t> 895 Note that this does not guarantee that all appropriate responses are 896 invalidated. For example, the request that caused the change at the origin 897 server might not have gone through the cache where a response is stored. 898 </t> 899 </section> 900 901 <section anchor="caching.authenticated.responses" 902 title="Shared Caching of Authenticated Responses"> 903 904 <t> 905 Shared caches &MUST-NOT; use a cached response to a request with an 906 Authorization header (&header-authorization;) to satisfy any subsequent 907 request unless a cache directive that allows such responses to be stored is 908 present in the response. 909 </t> 910 911 <t> 912 In this specification, the following Cache-Control response directives 913 (<xref target="cache-response-directive"/>) have such an effect: 914 must-revalidate, public, s-maxage. 915 </t> 916 917 <t> 918 Note that cached responses that contain the "must-revalidate" and/or 919 "s-maxage" response directives are not allowed to be served stale (<xref 920 target="serving.stale.responses"/>) by shared caches. In particular, a 921 response with either "max-age=0, must-revalidate" or "s-maxage=0" cannot be 922 used to satisfy a subsequent request without revalidating it on the origin 923 server. 924 </t> 925 </section> 926 927 <section anchor="caching.negotiated.responses" 928 title="Caching Negotiated Responses"> 929 <t> 930 When a cache receives a request that can be satisfied by a stored response 931 that has a Vary header field (<xref target="header.vary"/>), it &MUST-NOT; 932 use that response unless all of the selecting request-headers nominated by 933 the Vary header match in both the original request (i.e., that associated 934 with the stored response), and the presented request. 935 </t> 936 <t> 937 The selecting request-headers from two requests are defined to match if and 938 only if those in the first request can be transformed to those in the 939 second request by applying any of the following: 940 <list style="symbols"> 941 <t> 942 adding or removing whitespace, where allowed in the header's syntax 943 </t> 944 <t> 945 combining multiple message-header fields with the same field name 946 (see &header-fields;) 947 </t> 948 <t> 949 normalizing both header values in a way that is known to have 950 identical semantics, according to the header's specification (e.g., 951 re-ordering field values when order is not significant; 952 case-normalization, where values are defined to be case-insensitive) 953 </t> 871 954 </list> 872 955 </t> 873 956 <t> 874 If (after any normalization that might take place) a header field is absent 875 from a request, it can only match another request if it is also absent there. 876 </t> 877 <t> 878 A Vary header field-value of "*" always fails to match, and subsequent requests to that 879 resource can only be properly interpreted by the origin server. 880 </t> 881 <t> 882 The stored response with matching selecting request-headers is known as the 883 selected response. 884 </t> 885 <t> 886 If no selected response is available, the cache &MAY; forward the presented 887 request to the origin server in a conditional request; see <xref target="validation.model"/>. 957 If (after any normalization that might take place) a header field is absent 958 from a request, it can only match another request if it is also absent 959 there. 960 </t> 961 <t> 962 A Vary header field-value of "*" always fails to match, and subsequent 963 requests to that resource can only be properly interpreted by the origin 964 server. 965 </t> 966 <t> 967 The stored response with matching selecting request-headers is known as the 968 selected response. 969 </t> 970 <t> 971 If no selected response is available, the cache &MAY; forward the presented 972 request to the origin server in a conditional request; see <xref 973 target="validation.model"/>. 888 974 </t> 889 975 </section> … … 891 977 <section anchor="combining.headers" title="Combining Responses"> 892 978 <t> 893 When a cache receives a 304 (Not Modified) response or a 206 (Partial Content) response 894 (in this section, the "new" response"), it needs to created an updated response by combining 895 the stored response with the new one, so that the updated response can be used to satisfy 896 the request, and potentially update the cached response. 897 </t> 898 <t> 899 If the new response contains an ETag, it identifies the stored 900 response to use. <cref anchor="TODO-mention-CL">might need language about Content-Location 901 here</cref><cref anchor="TODO-select-for-combine">Shouldn't this be the selected response?</cref> 902 </t> 903 <t> 904 If the new response's status code is 206 (partial content), both the stored and new 905 responses &MUST; have validators, and those validators &MUST; match using the strong 906 comparison function (see &weak-and-strong;). Otherwise, the 907 responses &MUST-NOT; be combined. 908 </t> 909 <t> 910 The stored response headers are used as those of the updated response, except that 911 <list style="symbols"> 912 <t>any stored Warning headers with warn-code 1xx (see <xref target="header.warning" />) 913 &MUST; be deleted.</t> 914 <t>any stored Warning headers with warn-code 2xx &MUST; be retained.</t> 915 <t>any other headers provided in the new response &MUST; replace all instances of 916 the corresponding headers from the stored response.</t> 917 </list> 918 </t> 919 <t> 920 The updated response headers &MUST; be used to replace those of the 921 stored response in cache (unless the stored response is removed from cache). In the 922 case of a 206 response, the combined representation &MAY; be stored. 979 When a cache receives a 304 (Not Modified) response or a 206 (Partial 980 Content) response (in this section, the "new" response"), it needs to 981 created an updated response by combining the stored response with the new 982 one, so that the updated response can be used to satisfy the request, and 983 potentially update the cached response. 984 </t> 985 <t> 986 If the new response contains an ETag, it identifies the stored response to 987 use. <cref anchor="TODO-mention-CL">might need language about 988 Content-Location here</cref><cref 989 anchor="TODO-select-for-combine">Shouldn't this be the selected 990 response?</cref> 991 </t> 992 <t> 993 If the new response's status code is 206 (partial content), both the stored 994 and new responses &MUST; have validators, and those validators &MUST; match 995 using the strong comparison function (see &weak-and-strong;). Otherwise, 996 the responses &MUST-NOT; be combined. 997 </t> 998 <t> 999 The stored response headers are used as those of the updated response, 1000 except that 1001 <list style="symbols"> 1002 <t>any stored Warning headers with warn-code 1xx (see <xref 1003 target="header.warning" />) &MUST; be deleted.</t> 1004 <t>any stored Warning headers with warn-code 2xx &MUST; be retained.</t> 1005 <t>any other headers provided in the new response &MUST; replace all 1006 instances of the corresponding headers from the stored response.</t> 1007 </list> 1008 </t> 1009 <t> 1010 The updated response headers &MUST; be used to replace those of the stored 1011 response in cache (unless the stored response is removed from cache). In 1012 the case of a 206 response, the combined representation &MAY; be stored. 923 1013 </t> 924 1014 </section> … … 928 1018 <section anchor="header.fields" title="Header Field Definitions"> 929 1019 <t> 930 This section defines the syntax and semantics of HTTP/1.1 header fields931 related to caching.932 </t> 933 <t> 934 For entity-header fields, both sender and recipient refer to either the client or the935 server, depending on who sends and who receives the message.1020 This section defines the syntax and semantics of HTTP/1.1 header fields 1021 related to caching. 1022 </t> 1023 <t> 1024 For entity-header fields, both sender and recipient refer to either the 1025 client or the server, depending on who sends and who receives the message. 936 1026 </t> 937 1027 938 1028 <section anchor="header.age" title="Age"> 939 <iref item="Age header" primary="true" x:for-anchor="" />940 <iref item="Headers" primary="true" subitem="Age" x:for-anchor="" />941 <x:anchor-alias value="Age"/>942 <x:anchor-alias value="Age-v"/>943 <x:anchor-alias value="age-value"/>944 <t> 945 The "Age" response-header field conveys the sender's estimate of the amount946 of time since the response was generated or successfully validated at the947 origin server. Age values are calculated as specified in948 <xreftarget="age.calculations" />.1029 <iref item="Age header" primary="true" x:for-anchor="" /> 1030 <iref item="Headers" primary="true" subitem="Age" x:for-anchor="" /> 1031 <x:anchor-alias value="Age"/> 1032 <x:anchor-alias value="Age-v"/> 1033 <x:anchor-alias value="age-value"/> 1034 <t> 1035 The "Age" response-header field conveys the sender's estimate of the amount 1036 of time since the response was generated or successfully validated at the 1037 origin server. Age values are calculated as specified in <xref 1038 target="age.calculations" />. 949 1039 </t> 950 1040 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Age"/><iref primary="true" item="Grammar" subitem="Age-v"/> … … 960 1050 </artwork></figure> 961 1051 <t> 962 If a cache receives a value larger than the largest positive integer it can represent, or963 if any of its age calculations overflows, it &MUST; transmit an Age header with a964 field-value of 2147483648 (2<x:sup>31</x:sup>). Caches &SHOULD; use an arithmetic type965 of at least 31 bits of range.966 </t> 967 <t> 968 The presence of an Age header field in a response implies that a response is not969 first-hand. However, the converse is not true, since HTTP/1.0 caches might not implement the970 Age header field.1052 If a cache receives a value larger than the largest positive integer it can 1053 represent, or if any of its age calculations overflows, it &MUST; transmit 1054 an Age header with a field-value of 2147483648 (2<x:sup>31</x:sup>). Caches 1055 &SHOULD; use an arithmetic type of at least 31 bits of range. 1056 </t> 1057 <t> 1058 The presence of an Age header field in a response implies that a response 1059 is not first-hand. However, the converse is not true, since HTTP/1.0 caches 1060 might not implement the Age header field. 971 1061 </t> 972 1062 </section> 973 1063 974 1064 <section anchor="header.cache-control" title="Cache-Control"> 975 <iref item="Cache-Control header" primary="true" x:for-anchor="" /> 976 <iref item="Headers" primary="true" subitem="Cache-Control" x:for-anchor="" /> 977 <x:anchor-alias value="Cache-Control"/> 978 <x:anchor-alias value="Cache-Control-v"/> 979 <x:anchor-alias value="cache-directive"/> 980 <x:anchor-alias value="cache-extension"/> 981 <x:anchor-alias value="cache-request-directive"/> 982 <x:anchor-alias value="cache-response-directive"/> 983 <t> 984 The "Cache-Control" general-header field is used to specify directives for 985 caches along the request/response chain. Such cache directives are 986 unidirectional in that the presence of a directive in a request does not 987 imply that the same directive is to be given in the response. 988 </t> 989 <t> 990 HTTP/1.1 caches &MUST; obey the requirements of the Cache-Control directives 991 defined in this section. See <xref target="cache.control.extensions"/> for 992 information about how Cache-Control directives defined elsewhere are handled. 1065 <iref item="Cache-Control header" primary="true" x:for-anchor="" /> 1066 <iref item="Headers" primary="true" subitem="Cache-Control" 1067 x:for-anchor="" /> 1068 <x:anchor-alias value="Cache-Control"/> 1069 <x:anchor-alias value="Cache-Control-v"/> 1070 <x:anchor-alias value="cache-directive"/> 1071 <x:anchor-alias value="cache-extension"/> 1072 <x:anchor-alias value="cache-request-directive"/> 1073 <x:anchor-alias value="cache-response-directive"/> 1074 <t> 1075 The "Cache-Control" general-header field is used to specify directives for 1076 caches along the request/response chain. Such cache directives are 1077 unidirectional in that the presence of a directive in a request does not 1078 imply that the same directive is to be given in the response. 1079 </t> 1080 <t> 1081 HTTP/1.1 caches &MUST; obey the requirements of the Cache-Control 1082 directives defined in this section. See <xref 1083 target="cache.control.extensions"/> for information about how Cache-Control 1084 directives defined elsewhere are handled. 993 1085 </t> 994 1086 <x:note> 995 <t> 996 <x:h>Note:</x:h> HTTP/1.0 caches might not implement Cache-Control and 997 might only implement Pragma: no-cache (see <xref target="header.pragma" />). 998 </t> 1087 <t> 1088 <x:h>Note:</x:h> HTTP/1.0 caches might not implement Cache-Control and 1089 might only implement Pragma: no-cache (see <xref target="header.pragma" 1090 />). 1091 </t> 999 1092 </x:note> 1000 1093 <t> 1001 Cache directives &MUST; be passed through by a proxy or gateway application, 1002 regardless of their significance to that application, since the directives might be 1003 applicable to all recipients along the request/response chain. It is not possible to 1004 target a directive to a specific cache. 1094 Cache directives &MUST; be passed through by a proxy or gateway 1095 application, regardless of their significance to that application, since 1096 the directives might be applicable to all recipients along the 1097 request/response chain. It is not possible to target a directive to a 1098 specific cache. 1005 1099 </t> 1006 1100 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Cache-Control"/><iref primary="true" item="Grammar" subitem="Cache-Control-v"/><iref primary="true" item="Grammar" subitem="cache-extension"/> … … 1014 1108 </artwork></figure> 1015 1109 1016 <section anchor="cache-request-directive" title="Request Cache-Control Directives"> 1017 <x:anchor-alias value="cache-request-directive" /> 1018 1019 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" subitem="cache-request-directive" /> 1110 <section anchor="cache-request-directive" 1111 title="Request Cache-Control Directives"> 1112 <x:anchor-alias value="cache-request-directive" /> 1113 1114 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 1115 subitem="cache-request-directive" /> 1020 1116 <x:ref>cache-request-directive</x:ref> = 1021 1117 "no-cache" … … 1030 1126 1031 1127 <t> 1032 <x:dfn>no-cache</x:dfn> 1033 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1034 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1035 <list> 1036 <t>The no-cache request directive indicates that a stored response &MUST-NOT; be 1037 used to satisfy the request without successful validation on the origin server.</t> 1038 </list> 1039 </t> 1040 <t> 1041 <x:dfn>no-store</x:dfn> 1042 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1043 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1044 <list> 1045 <t>The no-store request directive indicates that a cache &MUST-NOT; store any part 1046 of either this request or any response to it. This directive applies to both 1047 non-shared and shared caches. "&MUST-NOT; store" in this context means that the 1048 cache &MUST-NOT; intentionally store the information in non-volatile storage, 1049 and &MUST; make a best-effort attempt to remove the information from volatile 1050 storage as promptly as possible after forwarding it.</t> 1051 <t>This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In 1052 particular, malicious or compromised caches might not recognize or obey this 1053 directive, and communications networks might be vulnerable to eavesdropping.</t> 1054 </list> 1055 </t> 1056 <t> 1057 <x:dfn>max-age</x:dfn> 1058 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1059 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1060 <list> 1061 <t>The max-age request directive indicates that the client is willing to accept a 1062 response whose age is no greater than the specified time in seconds. Unless 1063 the max-stale request directive is also present, the client is not willing to accept a stale 1064 response.</t> 1065 </list> 1066 </t> 1067 <t> 1068 <x:dfn>max-stale</x:dfn> 1069 <iref item="Cache Directives" primary="true" subitem="max-stale" /> 1070 <iref item="max-stale" primary="true" subitem="Cache Directive" /> 1071 <list> 1072 <t>The max-stale request directive indicates that the client is willing to accept a 1073 response that has exceeded its expiration time. If max-stale is assigned a value, 1074 then the client is willing to accept a response that has exceeded its expiration 1075 time by no more than the specified number of seconds. If no value is assigned to 1076 max-stale, then the client is willing to accept a stale response of any age.</t> 1077 </list> 1078 </t> 1079 <t> 1080 <x:dfn>min-fresh</x:dfn> 1081 <iref item="Cache Directives" primary="true" subitem="min-fresh" /> 1082 <iref item="min-fresh" primary="true" subitem="Cache Directive" /> 1083 <list> 1084 <t>The min-fresh request directive indicates that the client is willing to accept a 1085 response whose freshness lifetime is no less than its current age plus the specified 1086 time in seconds. That is, the client wants a response that will still be fresh for 1087 at least the specified number of seconds.</t> 1088 </list> 1089 </t> 1090 <t> 1091 <x:dfn>no-transform</x:dfn> 1092 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1093 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1094 <list> 1095 <t>The no-transform request directive indicates that an intermediate cache or proxy 1096 &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type request 1097 headers, nor the request representation.</t> 1098 </list> 1099 </t> 1100 <t> 1101 <x:dfn>only-if-cached</x:dfn> 1102 <iref item="Cache Directives" primary="true" subitem="only-if-cached" /> 1103 <iref item="only-if-cached" primary="true" subitem="Cache Directive" /> 1104 <list> 1105 <t>The only-if-cached request directive indicates that the client only wishes to 1106 return a stored response. If it receives this directive, a cache &SHOULD; either 1107 respond using a stored response that is consistent with the other constraints of the 1108 request, or respond with a 504 (Gateway Timeout) status code. If a group of caches is 1109 being operated as a unified system with good internal connectivity, such a request 1110 &MAY; be forwarded within that group of caches.</t> 1111 </list> 1112 </t> 1113 </section> 1114 1115 <section anchor="cache-response-directive" title="Response Cache-Control Directives"> 1116 <x:anchor-alias value="cache-response-directive" /> 1117 1118 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" subitem="cache-response-directive" /> 1128 <x:dfn>no-cache</x:dfn> 1129 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1130 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1131 <list> 1132 <t>The no-cache request directive indicates that a stored response 1133 &MUST-NOT; be used to satisfy the request without successful validation 1134 on the origin server.</t> 1135 </list> 1136 </t> 1137 <t> 1138 <x:dfn>no-store</x:dfn> 1139 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1140 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1141 <list> 1142 <t>The no-store request directive indicates that a cache &MUST-NOT; 1143 store any part of either this request or any response to it. This 1144 directive applies to both non-shared and shared caches. "&MUST-NOT; 1145 store" in this context means that the cache &MUST-NOT; intentionally 1146 store the information in non-volatile storage, and &MUST; make a 1147 best-effort attempt to remove the information from volatile storage as 1148 promptly as possible after forwarding it.</t> 1149 <t>This directive is NOT a reliable or sufficient mechanism for ensuring 1150 privacy. In particular, malicious or compromised caches might not 1151 recognize or obey this directive, and communications networks might be 1152 vulnerable to eavesdropping.</t> 1153 </list> 1154 </t> 1155 <t> 1156 <x:dfn>max-age</x:dfn> 1157 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1158 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1159 <list> 1160 <t>The max-age request directive indicates that the client is willing to 1161 accept a response whose age is no greater than the specified time in 1162 seconds. Unless the max-stale request directive is also present, the 1163 client is not willing to accept a stale response.</t> 1164 </list> 1165 </t> 1166 <t> 1167 <x:dfn>max-stale</x:dfn> 1168 <iref item="Cache Directives" primary="true" subitem="max-stale" /> 1169 <iref item="max-stale" primary="true" subitem="Cache Directive" /> 1170 <list> 1171 <t>The max-stale request directive indicates that the client is willing 1172 to accept a response that has exceeded its expiration time. If max-stale 1173 is assigned a value, then the client is willing to accept a response 1174 that has exceeded its expiration time by no more than the specified 1175 number of seconds. If no value is assigned to max-stale, then the client 1176 is willing to accept a stale response of any age.</t> 1177 </list> 1178 </t> 1179 <t> 1180 <x:dfn>min-fresh</x:dfn> 1181 <iref item="Cache Directives" primary="true" subitem="min-fresh" /> 1182 <iref item="min-fresh" primary="true" subitem="Cache Directive" /> 1183 <list> 1184 <t>The min-fresh request directive indicates that the client is willing 1185 to accept a response whose freshness lifetime is no less than its 1186 current age plus the specified time in seconds. That is, the client 1187 wants a response that will still be fresh for at least the specified 1188 number of seconds.</t> 1189 </list> 1190 </t> 1191 <t> 1192 <x:dfn>no-transform</x:dfn> 1193 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1194 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1195 <list> 1196 <t>The no-transform request directive indicates that an intermediate 1197 cache or proxy &MUST-NOT; change the Content-Encoding, Content-Range or 1198 Content-Type request headers, nor the request representation.</t> 1199 </list> 1200 </t> 1201 <t> 1202 <x:dfn>only-if-cached</x:dfn> 1203 <iref item="Cache Directives" primary="true" subitem="only-if-cached" /> 1204 <iref item="only-if-cached" primary="true" subitem="Cache Directive" /> 1205 <list> 1206 <t>The only-if-cached request directive indicates that the client only 1207 wishes to return a stored response. If it receives this directive, a 1208 cache &SHOULD; either respond using a stored response that is consistent 1209 with the other constraints of the request, or respond with a 504 1210 (Gateway Timeout) status code. If a group of caches is being operated as 1211 a unified system with good internal connectivity, such a request &MAY; 1212 be forwarded within that group of caches.</t> 1213 </list> 1214 </t> 1215 </section> 1216 1217 <section anchor="cache-response-directive" 1218 title="Response Cache-Control Directives"> 1219 <x:anchor-alias value="cache-response-directive" /> 1220 1221 <figure><artwork type="abnf2616"><iref item="Grammar" primary="true" 1222 subitem="cache-response-directive" /> 1119 1223 <x:ref>cache-response-directive</x:ref> = 1120 1224 "public" … … 1131 1235 1132 1236 <t> 1133 <x:dfn>public</x:dfn> 1134 <iref item="Cache Directives" primary="true" subitem="public" /> 1135 <iref item="public" primary="true" subitem="Cache Directive" /> 1136 <list> 1137 <t>The public response directive indicates that the response &MAY; be cached, even 1138 if it would normally be non-cacheable or cacheable only within a non-shared cache. 1139 (See also Authorization, &header-authorization;, for additional details.) </t> 1237 <x:dfn>public</x:dfn> 1238 <iref item="Cache Directives" primary="true" subitem="public" /> 1239 <iref item="public" primary="true" subitem="Cache Directive" /> 1240 <list> 1241 <t>The public response directive indicates that the response &MAY; be 1242 cached, even if it would normally be non-cacheable or cacheable only 1243 within a non-shared cache. (See also Authorization, 1244 &header-authorization;, for additional details.) </t> 1140 1245 </list> 1141 1246 </t> 1142 1247 <t> 1143 <x:dfn>private</x:dfn> 1144 <iref item="Cache Directives" primary="true" subitem="private" /> 1145 <iref item="private" primary="true" subitem="Cache Directive" /> 1146 <list> 1147 <t>The private response directive indicates that the response message is intended for 1148 a single user and &MUST-NOT; be stored by a shared cache. A private (non-shared) 1149 cache &MAY; store the response.</t> 1150 <t>If the private response directive specifies one or more field-names, this 1151 requirement is limited to the field-values associated with the listed response 1152 headers. That is, the specified field-names(s) &MUST-NOT; be stored by a shared 1153 cache, whereas the remainder of the response message &MAY; be.</t> 1154 <t> 1155 <x:h>Note:</x:h> This usage of the word private only controls where the response can 1156 be stored; it cannot ensure the privacy of the message content. 1157 Also, private response directives with field-names are often handled by 1158 implementations as if an unqualified private directive was received; i.e., 1159 the special handling for the qualified form is not widely implemented.</t> 1160 </list> 1161 </t> 1162 <t> 1163 <x:dfn>no-cache</x:dfn> 1164 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1165 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1166 <list> 1167 <t>The no-cache response directive indicates that the response MUST NOT be used 1168 to satisfy a subsequent request without successful validation on the origin 1169 server. This allows an origin server to prevent a cache from using it to satisfy 1170 a request without contacting it, even by caches that have been configured to 1171 return stale responses.</t> 1172 <t>If the no-cache response directive specifies one or more field-names, this 1173 requirement is limited to the field-values associated with the listed response 1174 headers. That is, the specified field-name(s) &MUST-NOT; be sent in the response 1175 to a subsequent request without successful validation on the origin server. This 1176 allows an origin server to prevent the re-use of certain header fields in a 1177 response, while still allowing caching of the rest of the response.</t> 1178 <t> 1179 <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey this directive. 1180 Also, no-cache response directives with field-names are often handled by 1181 implementations as if an unqualified no-cache directive was received; i.e., 1182 the special handling for the qualified form is not widely implemented. 1183 </t> 1184 </list> 1185 </t> 1186 <t> 1187 <x:dfn>no-store</x:dfn> 1188 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1189 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1190 <list> 1191 <t>The no-store response directive indicates that a cache &MUST-NOT; store any 1192 part of either the immediate request or response. This directive applies to both 1193 non-shared and shared caches. "&MUST-NOT; store" in this context means that the 1194 cache &MUST-NOT; intentionally store the information in non-volatile storage, 1195 and &MUST; make a best-effort attempt to remove the information from volatile 1196 storage as promptly as possible after forwarding it.</t> 1197 <t>This directive is NOT a reliable or sufficient mechanism for ensuring privacy. In 1198 particular, malicious or compromised caches might not recognize or obey this 1199 directive, and communications networks might be vulnerable to eavesdropping.</t> 1200 </list> 1201 </t> 1202 <t> 1203 <x:dfn>must-revalidate</x:dfn> 1204 <iref item="Cache Directives" primary="true" subitem="must-revalidate" /> 1205 <iref item="must-revalidate" primary="true" subitem="Cache Directive" /> 1206 <list> 1207 <t>The must-revalidate response directive indicates that once it has become stale, the response &MUST-NOT; be 1208 used to satisfy subsequent requests without successful validation on the origin server.</t> 1209 <t>The must-revalidate directive is necessary to support reliable operation for 1210 certain protocol features. In all circumstances an HTTP/1.1 cache &MUST; obey 1211 the must-revalidate directive; in particular, if the cache cannot reach the origin 1212 server for any reason, it &MUST; generate a 504 (Gateway Timeout) response.</t> 1213 <t>Servers &SHOULD; send the must-revalidate directive if and only if failure to 1214 validate a request on the representation could result in incorrect operation, such as a 1215 silently unexecuted financial transaction.</t> 1216 </list> 1217 </t> 1218 <t> 1219 <x:dfn>proxy-revalidate</x:dfn> 1220 <iref item="Cache Directives" primary="true" subitem="proxy-revalidate" /> 1221 <iref item="proxy-revalidate" primary="true" subitem="Cache Directive" /> 1222 <list> 1223 <t>The proxy-revalidate response directive has the same meaning as the must-revalidate 1224 response directive, except that it does not apply to non-shared caches.</t> 1225 </list> 1226 </t> 1227 <t> 1228 <x:dfn>max-age</x:dfn> 1229 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1230 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1231 <list> 1232 <t>The max-age response directive indicates that response is to be considered stale 1233 after its age is greater than the specified number of seconds.</t> 1234 </list> 1235 </t> 1236 <t> 1237 <x:dfn>s-maxage</x:dfn> 1238 <iref item="Cache Directives" primary="true" subitem="s-maxage" /> 1239 <iref item="s-maxage" primary="true" subitem="Cache Directive" /> 1240 <list> 1241 <t>The s-maxage response directive indicates that, in shared caches, the maximum age 1242 specified by this directive overrides the maximum age specified by either the 1243 max-age directive or the Expires header. The s-maxage directive also implies the 1244 semantics of the proxy-revalidate response directive.</t> 1245 </list> 1246 </t> 1247 <t> 1248 <x:dfn>no-transform</x:dfn> 1249 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1250 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1251 <list> 1252 <t>The no-transform response directive indicates that an intermediate cache or proxy 1253 &MUST-NOT; change the Content-Encoding, Content-Range or Content-Type response 1254 headers, nor the response representation.</t> 1255 </list> 1248 <x:dfn>private</x:dfn> 1249 <iref item="Cache Directives" primary="true" subitem="private" /> 1250 <iref item="private" primary="true" subitem="Cache Directive" /> 1251 <list> 1252 <t>The private response directive indicates that the response message is 1253 intended for a single user and &MUST-NOT; be stored by a shared cache. A 1254 private (non-shared) cache &MAY; store the response.</t> 1255 <t>If the private response directive specifies one or more field-names, 1256 this requirement is limited to the field-values associated with the 1257 listed response headers. That is, the specified field-names(s) 1258 &MUST-NOT; be stored by a shared cache, whereas the remainder of the 1259 response message &MAY; be.</t> 1260 <t> <x:h>Note:</x:h> This usage of the word private only controls where 1261 the response can be stored; it cannot ensure the privacy of the message 1262 content. Also, private response directives with field-names are often 1263 handled by implementations as if an unqualified private directive was 1264 received; i.e., the special handling for the qualified form is not 1265 widely implemented.</t> 1266 </list> 1267 </t> 1268 <t> 1269 <x:dfn>no-cache</x:dfn> 1270 <iref item="Cache Directives" primary="true" subitem="no-cache" /> 1271 <iref item="no-cache" primary="true" subitem="Cache Directive" /> 1272 <list> 1273 <t>The no-cache response directive indicates that the response MUST NOT 1274 be used to satisfy a subsequent request without successful validation on 1275 the origin server. This allows an origin server to prevent a cache from 1276 using it to satisfy a request without contacting it, even by caches that 1277 have been configured to return stale responses.</t> 1278 <t>If the no-cache response directive specifies one or more field-names, 1279 this requirement is limited to the field-values associated with the 1280 listed response headers. That is, the specified field-name(s) &MUST-NOT; 1281 be sent in the response to a subsequent request without successful 1282 validation on the origin server. This allows an origin server to prevent 1283 the re-use of certain header fields in a response, while still allowing 1284 caching of the rest of the response.</t> 1285 <t> <x:h>Note:</x:h> Most HTTP/1.0 caches will not recognize or obey 1286 this directive. Also, no-cache response directives with field-names are 1287 often handled by implementations as if an unqualified no-cache directive 1288 was received; i.e., the special handling for the qualified form is not 1289 widely implemented. </t> 1290 </list> 1291 </t> 1292 <t> 1293 <x:dfn>no-store</x:dfn> 1294 <iref item="Cache Directives" primary="true" subitem="no-store" /> 1295 <iref item="no-store" primary="true" subitem="Cache Directive" /> 1296 <list> 1297 <t>The no-store response directive indicates that a cache &MUST-NOT; 1298 store any part of either the immediate request or response. This 1299 directive applies to both non-shared and shared caches. "&MUST-NOT; 1300 store" in this context means that the cache &MUST-NOT; intentionally 1301 store the information in non-volatile storage, and &MUST; make a 1302 best-effort attempt to remove the information from volatile storage as 1303 promptly as possible after forwarding it.</t> 1304 <t>This directive is NOT a reliable or sufficient mechanism for ensuring 1305 privacy. In particular, malicious or compromised caches might not 1306 recognize or obey this directive, and communications networks might be 1307 vulnerable to eavesdropping.</t> 1308 </list> 1309 </t> 1310 <t> 1311 <x:dfn>must-revalidate</x:dfn> 1312 <iref item="Cache Directives" primary="true" subitem="must-revalidate" /> 1313 <iref item="must-revalidate" primary="true" subitem="Cache Directive" /> 1314 <list> 1315 <t>The must-revalidate response directive indicates that once it has 1316 become stale, the response &MUST-NOT; be used to satisfy subsequent 1317 requests without successful validation on the origin server.</t> 1318 <t>The must-revalidate directive is necessary to support reliable 1319 operation for certain protocol features. In all circumstances an 1320 HTTP/1.1 cache &MUST; obey the must-revalidate directive; in particular, 1321 if the cache cannot reach the origin server for any reason, it &MUST; 1322 generate a 504 (Gateway Timeout) response.</t> 1323 <t>Servers &SHOULD; send the must-revalidate directive if and only if 1324 failure to validate a request on the representation could result in 1325 incorrect operation, such as a silently unexecuted financial 1326 transaction.</t> 1327 </list> 1328 </t> 1329 <t> 1330 <x:dfn>proxy-revalidate</x:dfn> 1331 <iref item="Cache Directives" primary="true" subitem="proxy-revalidate" /> 1332 <iref item="proxy-revalidate" primary="true" subitem="Cache Directive" /> 1333 <list> 1334 <t>The proxy-revalidate response directive has the same meaning as the 1335 must-revalidate response directive, except that it does not apply to 1336 non-shared caches.</t> 1337 </list> 1338 </t> 1339 <t> 1340 <x:dfn>max-age</x:dfn> 1341 <iref item="Cache Directives" primary="true" subitem="max-age" /> 1342 <iref item="max-age" primary="true" subitem="Cache Directive" /> 1343 <list> 1344 <t>The max-age response directive indicates that response is to be 1345 considered stale after its age is greater than the specified number of 1346 seconds.</t> 1347 </list> 1348 </t> 1349 <t> 1350 <x:dfn>s-maxage</x:dfn> 1351 <iref item="Cache Directives" primary="true" subitem="s-maxage" /> 1352 <iref item="s-maxage" primary="true" subitem="Cache Directive" /> 1353 <list> 1354 <t>The s-maxage response directive indicates that, in shared caches, the 1355 maximum age specified by this directive overrides the maximum age 1356 specified by either the max-age directive or the Expires header. The 1357 s-maxage directive also implies the semantics of the proxy-revalidate 1358 response directive.</t> 1359 </list> 1360 </t> 1361 <t> 1362 <x:dfn>no-transform</x:dfn> 1363 <iref item="Cache Directives" primary="true" subitem="no-transform" /> 1364 <iref item="no-transform" primary="true" subitem="Cache Directive" /> 1365 <list> 1366 <t>The no-transform response directive indicates that an intermediate 1367 cache or proxy &MUST-NOT; change the Content-Encoding, Content-Range or 1368 Content-Type response headers, nor the response representation.</t> 1369 </list> 1256 1370 </t> 1257 1371 … … 1260 1374 <section anchor="cache.control.extensions" title="Cache Control Extensions"> 1261 1375 <t> 1262 The Cache-Control header field can be extended through the use of one or more 1263 cache-extension tokens, each with an optional value. Informational extensions (those 1264 that do not require a change in cache behavior) can be added without changing the 1265 semantics of other directives. Behavioral extensions are designed to work by acting as 1266 modifiers to the existing base of cache directives. Both the new directive and the 1267 standard directive are supplied, such that applications that do not understand the new 1268 directive will default to the behavior specified by the standard directive, and those 1269 that understand the new directive will recognize it as modifying the requirements 1270 associated with the standard directive. In this way, extensions to the cache-control 1271 directives can be made without requiring changes to the base protocol. 1272 </t> 1273 <t> 1274 This extension mechanism depends on an HTTP cache obeying all of the cache-control 1275 directives defined for its native HTTP-version, obeying certain extensions, and ignoring 1276 all directives that it does not understand. 1277 </t> 1278 <t> 1279 For example, consider a hypothetical new response directive called "community" that 1280 acts as a modifier to the private directive. We define this new directive to mean that, 1281 in addition to any non-shared cache, any cache that is shared only by members of the 1282 community named within its value may cache the response. An origin server wishing to 1283 allow the UCI community to use an otherwise private response in their shared cache(s) 1284 could do so by including 1376 The Cache-Control header field can be extended through the use of one or 1377 more cache-extension tokens, each with an optional value. Informational 1378 extensions (those that do not require a change in cache behavior) can be 1379 added without changing the semantics of other directives. Behavioral 1380 extensions are designed to work by acting as modifiers to the existing base 1381 of cache directives. Both the new directive and the standard directive are 1382 supplied, such that applications that do not understand the new directive 1383 will default to the behavior specified by the standard directive, and those 1384 that understand the new directive will recognize it as modifying the 1385 requirements associated with the standard directive. In this way, 1386 extensions to the cache-control directives can be made without requiring 1387 changes to the base protocol. 1388 </t> 1389 <t> 1390 This extension mechanism depends on an HTTP cache obeying all of the 1391 cache-control directives defined for its native HTTP-version, obeying 1392 certain extensions, and ignoring all directives that it does not 1393 understand. 1394 </t> 1395 <t> 1396 For example, consider a hypothetical new response directive called 1397 "community" that acts as a modifier to the private directive. We define 1398 this new directive to mean that, in addition to any non-shared cache, any 1399 cache that is shared only by members of the community named within its 1400 value may cache the response. An origin server wishing to allow the UCI 1401 community to use an otherwise private response in their shared cache(s) 1402 could do so by including 1285 1403 </t> 1286 1404 <figure><artwork type="example"> … … 1288 1406 </artwork></figure> 1289 1407 <t> 1290 A cache seeing this header field will act correctly even if the cache does not 1291 understand the community cache-extension, since it will also see and understand the 1292 private directive and thus default to the safe behavior. 1293 </t> 1294 <t> 1295 Unrecognized cache directives &MUST; be ignored; it is assumed that any cache 1296 directive likely to be unrecognized by an HTTP/1.1 cache will be combined with standard 1297 directives (or the response's default cacheability) such that the cache behavior will 1298 remain minimally correct even if the cache does not understand the extension(s). 1299 </t> 1300 <t> 1301 The HTTP Cache Directive Registry defines the name space for the cache 1302 directives. 1303 </t> 1304 <t> 1305 Registrations &MUST; include the following fields: 1306 <list style="symbols"> 1307 <t>Cache Directive Name</t> 1308 <t>Pointer to specification text</t> 1309 </list> 1310 </t> 1311 <t> 1312 Values to be added to this name space are subject to IETF review 1313 (<xref target="RFC5226" x:fmt="," x:sec="4.1"/>). 1314 </t> 1315 <t> 1316 The registry itself is maintained at <eref target="http://www.iana.org/assignments/http-cache-directives"/>. 1408 A cache seeing this header field will act correctly even if the cache does 1409 not understand the community cache-extension, since it will also see and 1410 understand the private directive and thus default to the safe behavior. 1411 </t> 1412 <t> 1413 Unrecognized cache directives &MUST; be ignored; it is assumed that any 1414 cache directive likely to be unrecognized by an HTTP/1.1 cache will be 1415 combined with standard directives (or the response's default cacheability) 1416 such that the cache behavior will remain minimally correct even if the 1417 cache does not understand the extension(s). 1418 </t> 1419 <t> 1420 The HTTP Cache Directive Registry defines the name space for the cache 1421 directives. 1422 </t> 1423 <t> 1424 Registrations &MUST; include the following fields: 1425 <list style="symbols"> 1426 <t>Cache Directive Name</t> 1427 <t>Pointer to specification text</t> 1428 </list> 1429 </t> 1430 <t> 1431 Values to be added to this name space are subject to IETF review (<xref 1432 target="RFC5226" x:fmt="," x:sec="4.1"/>). 1433 </t> 1434 <t> 1435 The registry itself is maintained at <eref 1436 target="http://www.iana.org/assignments/http-cache-directives"/>. 1317 1437 </t> 1318 1438 </section> … … 1321 1441 1322 1442 <section anchor="header.expires" title="Expires"> 1323 <iref item="Expires header" primary="true" x:for-anchor="" />1324 <iref item="Headers" primary="true" subitem="Expires" x:for-anchor="" />1325 <x:anchor-alias value="Expires"/>1326 <x:anchor-alias value="Expires-v"/>1327 <t> 1328 The "Expires" entity-header field gives the date/time after which the response is1329 considered stale. See <xref target="expiration.model" /> for further discussion of the1330 freshness model.1331 </t> 1332 <t> 1333 The presence of an Expires field does not imply that the original resource will change or1334 cease to exist at, before, or after that time.1335 </t> 1336 <t> 1337 The field-value is an absolute date and time as defined by HTTP-date in &full-date;;1338 it &MUST; be sent in rfc1123-date format.1443 <iref item="Expires header" primary="true" x:for-anchor="" /> 1444 <iref item="Headers" primary="true" subitem="Expires" x:for-anchor="" /> 1445 <x:anchor-alias value="Expires"/> 1446 <x:anchor-alias value="Expires-v"/> 1447 <t> 1448 The "Expires" entity-header field gives the date/time after which the 1449 response is considered stale. See <xref target="expiration.model" /> for 1450 further discussion of the freshness model. 1451 </t> 1452 <t> 1453 The presence of an Expires field does not imply that the original resource 1454 will change or cease to exist at, before, or after that time. 1455 </t> 1456 <t> 1457 The field-value is an absolute date and time as defined by HTTP-date in 1458 &full-date;; it &MUST; be sent in rfc1123-date format. 1339 1459 </t> 1340 1460 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Expires"/><iref primary="true" item="Grammar" subitem="Expires-v"/> … … 1348 1468 </artwork></figure> 1349 1469 <x:note> 1350 <t> 1351 <x:h>Note:</x:h> If a response includes a Cache-Control field with the max-age 1352 directive (see <xref target="cache-response-directive" />), that directive overrides 1353 the Expires field. Likewise, the s-maxage directive overrides Expires in shared caches. 1354 </t> 1470 <t> 1471 <x:h>Note:</x:h> If a response includes a Cache-Control field with the 1472 max-age directive (see <xref target="cache-response-directive" />), 1473 that directive overrides the Expires field. Likewise, the s-maxage 1474 directive overrides Expires in shared caches. 1475 </t> 1355 1476 </x:note> 1356 1477 <t> 1357 HTTP/1.1 servers &SHOULD-NOT; send Expires dates more than one year in the future. 1358 </t> 1359 <t> 1360 HTTP/1.1 clients and caches &MUST; treat other invalid date formats, especially 1361 including the value "0", as in the past (i.e., "already expired"). 1478 HTTP/1.1 servers &SHOULD-NOT; send Expires dates more than one year in the 1479 future. 1480 </t> 1481 <t> 1482 HTTP/1.1 clients and caches &MUST; treat other invalid date formats, 1483 especially including the value "0", as in the past (i.e., "already 1484 expired"). 1362 1485 </t> 1363 1486 </section> 1364 1487 1365 1488 <section anchor="header.pragma" title="Pragma"> 1366 <iref item="Pragma header" primary="true" x:for-anchor="" /> 1367 <iref item="Headers" primary="true" subitem="Pragma" x:for-anchor="" /> 1368 <x:anchor-alias value="extension-pragma"/> 1369 <x:anchor-alias value="Pragma"/> 1370 <x:anchor-alias value="Pragma-v"/> 1371 <x:anchor-alias value="pragma-directive"/> 1372 <t> 1373 The "Pragma" general-header field is used to include implementation-specific directives 1374 that might apply to any recipient along the request/response chain. All pragma directives 1375 specify optional behavior from the viewpoint of the protocol; however, some systems 1376 &MAY; require that behavior be consistent with the directives. 1489 <iref item="Pragma header" primary="true" x:for-anchor="" /> 1490 <iref item="Headers" primary="true" subitem="Pragma" x:for-anchor="" /> 1491 <x:anchor-alias value="extension-pragma"/> 1492 <x:anchor-alias value="Pragma"/> 1493 <x:anchor-alias value="Pragma-v"/> 1494 <x:anchor-alias value="pragma-directive"/> 1495 <t> 1496 The "Pragma" general-header field is used to include 1497 implementation-specific directives that might apply to any recipient along 1498 the request/response chain. All pragma directives specify optional behavior 1499 from the viewpoint of the protocol; however, some systems &MAY; require 1500 that behavior be consistent with the directives. 1377 1501 </t> 1378 1502 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Pragma"/><iref primary="true" item="Grammar" subitem="Pragma-v"/><iref primary="true" item="Grammar" subitem="pragma-directive"/><iref primary="true" item="Grammar" subitem="extension-pragma"/> … … 1383 1507 </artwork></figure> 1384 1508 <t> 1385 When the no-cache directive is present in a request message, an application &SHOULD; 1386 forward the request toward the origin server even if it has a cached copy of what is being 1387 requested. This pragma directive has the same semantics as the no-cache response directive 1388 (see <xref target="cache-response-directive" />) and is defined here for backward 1389 compatibility with HTTP/1.0. Clients &SHOULD; include both header fields when a 1390 no-cache request is sent to a server not known to be HTTP/1.1 compliant. HTTP/1.1 caches 1391 &SHOULD; treat "Pragma: no-cache" as if the client had sent "Cache-Control: no-cache". 1509 When the no-cache directive is present in a request message, an application 1510 &SHOULD; forward the request toward the origin server even if it has a 1511 cached copy of what is being requested. This pragma directive has the same 1512 semantics as the no-cache response directive (see <xref 1513 target="cache-response-directive" />) and is defined here for backward 1514 compatibility with HTTP/1.0. Clients &SHOULD; include both header fields 1515 when a no-cache request is sent to a server not known to be HTTP/1.1 1516 compliant. HTTP/1.1 caches &SHOULD; treat "Pragma: no-cache" as if the 1517 client had sent "Cache-Control: no-cache". 1392 1518 </t> 1393 1519 <x:note> 1394 <t>1395 <x:h>Note:</x:h> Because the meaning of "Pragma: no-cache" as a response-header field1396 is not actually specified, it does not provide a reliable replacement for1397 "Cache-Control: no-cache" in a response.1398 </t>1520 <t> 1521 <x:h>Note:</x:h> Because the meaning of "Pragma: no-cache" as a 1522 response-header field is not actually specified, it does not provide a 1523 reliable replacement for "Cache-Control: no-cache" in a response. 1524 </t> 1399 1525 </x:note> 1400 1526 <t> 1401 This mechanism is deprecated; no new Pragma directives will be defined in HTTP. 1527 This mechanism is deprecated; no new Pragma directives will be defined in 1528 HTTP. 1402 1529 </t> 1403 1530 </section> 1404 1531 1405 1532 <section anchor="header.vary" title="Vary"> 1406 <iref item="Vary header" primary="true" x:for-anchor="" />1407 <iref item="Headers" primary="true" subitem="Vary" x:for-anchor="" />1408 <x:anchor-alias value="Vary"/>1409 <x:anchor-alias value="Vary-v"/>1410 <t> 1411 The "Vary" response-header field conveys the set of request-header fields1412 that were used to select the representation.1413 </t> 1414 <t> 1415 Caches use this information, in part, to determine whether a stored response1416 can be used to satisfy a given request; see1417 <xref target="caching.negotiated.responses" />.1418 determines, while the response is fresh, whether a cache is permitted to use the1419 response to reply to a subsequent request without validation; see <xref1420 target="caching.negotiated.responses" />.1421 </t> 1422 <t> 1423 In uncacheable or stale responses, the Vary field value advises the user agent about1424 the criteria that were used to select the representation.1533 <iref item="Vary header" primary="true" x:for-anchor="" /> 1534 <iref item="Headers" primary="true" subitem="Vary" x:for-anchor="" /> 1535 <x:anchor-alias value="Vary"/> 1536 <x:anchor-alias value="Vary-v"/> 1537 <t> 1538 The "Vary" response-header field conveys the set of request-header fields 1539 that were used to select the representation. 1540 </t> 1541 <t> 1542 Caches use this information, in part, to determine whether a stored 1543 response can be used to satisfy a given request; see <xref 1544 target="caching.negotiated.responses" />. determines, while the response is 1545 fresh, whether a cache is permitted to use the response to reply to a 1546 subsequent request without validation; see <xref 1547 target="caching.negotiated.responses" />. 1548 </t> 1549 <t> 1550 In uncacheable or stale responses, the Vary field value advises the user 1551 agent about the criteria that were used to select the representation. 1425 1552 </t> 1426 1553 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Vary"/><iref primary="true" item="Grammar" subitem="Vary-v"/> … … 1429 1556 </artwork></figure> 1430 1557 <t> 1431 The set of header fields named by the Vary field value is known as the selecting 1432 request-headers. 1433 </t> 1434 <t> 1435 Servers &SHOULD; include a Vary header field with any cacheable response that is 1436 subject to server-driven negotiation. Doing so allows a cache to properly interpret future 1437 requests on that resource and informs the user agent about the presence of negotiation on 1438 that resource. A server &MAY; include a Vary header field with a non-cacheable 1439 response that is subject to server-driven negotiation, since this might provide the user 1440 agent with useful information about the dimensions over which the response varies at the 1441 time of the response. 1442 </t> 1443 <t> 1444 A Vary field value of "*" signals that unspecified parameters not limited to the 1445 request-headers (e.g., the network address of the client), play a role in the selection of 1446 the response representation; therefore, a cache cannot determine whether this response is 1447 appropriate. The "*" value &MUST-NOT; be generated by a proxy server. 1448 </t> 1449 <t> 1450 The field-names given are not limited to the set of standard request-header fields 1451 defined by this specification. Field names are case-insensitive. 1558 The set of header fields named by the Vary field value is known as the 1559 selecting request-headers. 1560 </t> 1561 <t> 1562 Servers &SHOULD; include a Vary header field with any cacheable response 1563 that is subject to server-driven negotiation. Doing so allows a cache to 1564 properly interpret future requests on that resource and informs the user 1565 agent about the presence of negotiation on that resource. A server &MAY; 1566 include a Vary header field with a non-cacheable response that is subject 1567 to server-driven negotiation, since this might provide the user agent with 1568 useful information about the dimensions over which the response varies at 1569 the time of the response. 1570 </t> 1571 <t> 1572 A Vary field value of "*" signals that unspecified parameters not limited 1573 to the request-headers (e.g., the network address of the client), play a 1574 role in the selection of the response representation; therefore, a cache 1575 cannot determine whether this response is appropriate. The "*" value 1576 &MUST-NOT; be generated by a proxy server. 1577 </t> 1578 <t> 1579 The field-names given are not limited to the set of standard request-header 1580 fields defined by this specification. Field names are case-insensitive. 1452 1581 </t> 1453 1582 </section> 1454 1583 1455 1584 <section anchor="header.warning" title="Warning"> 1456 <iref item="Warning header" primary="true" x:for-anchor="" /> 1457 <iref item="Headers" primary="true" subitem="Warning" x:for-anchor="" /> 1458 <x:anchor-alias value="Warning"/> 1459 <x:anchor-alias value="Warning-v"/> 1460 <x:anchor-alias value="warning-value"/> 1461 <x:anchor-alias value="warn-agent"/> 1462 <x:anchor-alias value="warn-code"/> 1463 <x:anchor-alias value="warn-date"/> 1464 <x:anchor-alias value="warn-text"/> 1465 <t> 1466 The "Warning" general-header field is used to carry additional information about the status 1467 or transformation of a message that might not be reflected in the message. This 1468 information is typically used to warn about possible incorrectness introduced by caching 1469 operations or transformations applied to the payload of the message. 1470 </t> 1471 <t> 1472 Warnings can be used for other purposes, both cache-related and otherwise. The use of a 1473 warning, rather than an error status code, distinguishes these responses from true failures. 1474 </t> 1475 <t> 1476 Warning headers can in general be applied to any message, however some warn-codes are 1477 specific to caches and can only be applied to response messages. 1585 <iref item="Warning header" primary="true" x:for-anchor="" /> 1586 <iref item="Headers" primary="true" subitem="Warning" x:for-anchor="" /> 1587 <x:anchor-alias value="Warning"/> 1588 <x:anchor-alias value="Warning-v"/> 1589 <x:anchor-alias value="warning-value"/> 1590 <x:anchor-alias value="warn-agent"/> 1591 <x:anchor-alias value="warn-code"/> 1592 <x:anchor-alias value="warn-date"/> 1593 <x:anchor-alias value="warn-text"/> 1594 <t> 1595 The "Warning" general-header field is used to carry additional information 1596 about the status or transformation of a message that might not be reflected 1597 in the message. This information is typically used to warn about possible 1598 incorrectness introduced by caching operations or transformations applied 1599 to the payload of the message. 1600 </t> 1601 <t> 1602 Warnings can be used for other purposes, both cache-related and otherwise. 1603 The use of a warning, rather than an error status code, distinguishes these 1604 responses from true failures. 1605 </t> 1606 <t> 1607 Warning headers can in general be applied to any message, however some 1608 warn-codes are specific to caches and can only be applied to response 1609 messages. 1478 1610 </t> 1479 1611 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Warning"/><iref primary="true" item="Grammar" subitem="Warning-v"/><iref primary="true" item="Grammar" subitem="warning-value"/><iref primary="true" item="Grammar" subitem="warn-code"/><iref primary="true" item="Grammar" subitem="warn-agent"/><iref primary="true" item="Grammar" subitem="warn-text"/><iref primary="true" item="Grammar" subitem="warn-date"/> … … 1492 1624 </artwork></figure> 1493 1625 <t> 1494 Multiple warnings can be attached to a response (either by the origin server or by 1495 a cache), including multiple warnings with the same code number, only differing 1496 in warn-text. 1497 </t> 1498 <t> 1499 When this occurs, the user agent &SHOULD; inform the user of as many of them as 1500 possible, in the order that they appear in the response. 1501 </t> 1502 <t> 1503 Systems that generate multiple Warning headers &SHOULD; order them with this user 1504 agent behavior in mind. New Warning headers &SHOULD; be added after any existing 1505 Warning headers. 1506 </t> 1507 <t> 1508 Warnings are assigned three digit warn-codes. The first digit indicates whether the 1509 Warning is required to be deleted from a stored response after validation: 1510 <list style="symbols"> 1511 <t>1xx Warnings describe the freshness or validation status of the response, and so 1512 &MUST; be deleted by caches after validation. They can only be generated by a cache 1513 when validating a cached entry, and &MUST-NOT; be generated in any other situation.</t> 1514 <t>2xx Warnings describe some aspect of the representation that is 1515 not rectified by a validation (for example, a lossy compression of the representation) 1516 and &MUST-NOT; be deleted by caches after validation, unless a full response is 1517 returned, in which case they &MUST; be.</t> 1518 </list> 1519 </t> 1520 <t> 1521 If an implementation sends a message with one or more Warning headers to a receiver whose 1522 version is HTTP/1.0 or lower, then the sender &MUST; include in each warning-value a 1523 warn-date that matches the Date header in the message. 1524 </t> 1525 <t> 1526 If an implementation receives a message with a warning-value that includes a warn-date, 1527 and that warn-date is different from the Date value in the response, then that 1528 warning-value &MUST; be deleted from the message before storing, forwarding, or using 1529 it. (preventing the consequences of naive caching of Warning header fields.) If all of the 1530 warning-values are deleted for this reason, the Warning header &MUST; be deleted as 1531 well. 1532 </t> 1533 <t> 1534 The following warn-codes are defined by this specification, each with a recommended 1535 warn-text in English, and a description of its meaning. 1626 Multiple warnings can be attached to a response (either by the origin 1627 server or by a cache), including multiple warnings with the same code 1628 number, only differing in warn-text. 1629 </t> 1630 <t> 1631 When this occurs, the user agent &SHOULD; inform the user of as many of 1632 them as possible, in the order that they appear in the response. 1633 </t> 1634 <t> 1635 Systems that generate multiple Warning headers &SHOULD; order them with 1636 this user agent behavior in mind. New Warning headers &SHOULD; be added 1637 after any existing Warning headers. 1638 </t> 1639 <t> 1640 Warnings are assigned three digit warn-codes. The first digit indicates 1641 whether the Warning is required to be deleted from a stored response after 1642 validation: 1643 <list style="symbols"> 1644 <t>1xx Warnings describe the freshness or validation status of the 1645 response, and so &MUST; be deleted by caches after validation. They can 1646 only be generated by a cache when validating a cached entry, and 1647 &MUST-NOT; be generated in any other situation.</t> 1648 <t>2xx Warnings describe some aspect of the representation that is not 1649 rectified by a validation (for example, a lossy compression of the 1650 representation) and &MUST-NOT; be deleted by caches after validation, 1651 unless a full response is returned, in which case they &MUST; be.</t> 1652 </list> 1653 </t> 1654 <t> 1655 If an implementation sends a message with one or more Warning headers to a 1656 receiver whose version is HTTP/1.0 or lower, then the sender &MUST; include 1657 in each warning-value a warn-date that matches the Date header in the 1658 message. 1659 </t> 1660 <t> 1661 If an implementation receives a message with a warning-value that includes 1662 a warn-date, and that warn-date is different from the Date value in the 1663 response, then that warning-value &MUST; be deleted from the message before 1664 storing, forwarding, or using it. (preventing the consequences of naive 1665 caching of Warning header fields.) If all of the warning-values are deleted 1666 for this reason, the Warning header &MUST; be deleted as well. 1667 </t> 1668 <t> 1669 The following warn-codes are defined by this specification, each with a 1670 recommended warn-text in English, and a description of its meaning. 1536 1671 </t> 1537 1672 <t><?rfc needLines="4"?> 1538 110 Response is stale1539 <list>1540 <t>&SHOULD; be included whenever the returned response is stale.</t>1541 </list>1673 110 Response is stale 1674 <list> 1675 <t>&SHOULD; be included whenever the returned response is stale.</t> 1676 </list> 1542 1677 </t> 1543 1678 <t><?rfc needLines="4"?> 1544 111 Revalidation failed 1545 <list> 1546 <t>&SHOULD; be included if a cache returns a stale response because an attempt to 1547 validate the response failed, due to an inability to reach the server.</t> 1548 </list> 1679 111 Revalidation failed 1680 <list> 1681 <t>&SHOULD; be included if a cache returns a stale response because an 1682 attempt to validate the response failed, due to an inability to reach 1683 the server.</t> 1684 </list> 1549 1685 </t> 1550 1686 <t><?rfc needLines="4"?> 1551 112 Disconnected operation1552 <list>1553 <t>&SHOULD; be included if the cache is intentionally disconnected from the rest of1554 the network for a period of time.</t>1555 </list>1687 112 Disconnected operation 1688 <list> 1689 <t>&SHOULD; be included if the cache is intentionally disconnected from 1690 the rest of the network for a period of time.</t> 1691 </list> 1556 1692 </t> 1557 1693 <t><?rfc needLines="4"?> 1558 113 Heuristic expiration 1559 <list> 1560 <t>&SHOULD; be included if the cache heuristically chose a freshness lifetime 1561 greater than 24 hours and the response's age is greater than 24 hours.</t> 1562 </list> 1694 113 Heuristic expiration 1695 <list> 1696 <t>&SHOULD; be included if the cache heuristically chose a freshness 1697 lifetime greater than 24 hours and the response's age is greater than 24 1698 hours.</t> 1699 </list> 1563 1700 </t> 1564 1701 <t><?rfc needLines="4"?> 1565 199 Miscellaneous warning1566 <list>1567 <t>The warning text can include arbitrary information to be presented to a human1568 user, or logged. A system receiving this warning &MUST-NOT; take any automated1569 a ction, besides presenting the warning to the user.</t>1570 </list>1702 199 Miscellaneous warning 1703 <list> 1704 <t>The warning text can include arbitrary information to be presented to 1705 a human user, or logged. A system receiving this warning &MUST-NOT; take 1706 any automated action, besides presenting the warning to the user.</t> 1707 </list> 1571 1708 </t> 1572 1709 <t><?rfc needLines="4"?> 1573 214 Transformation applied1574 <list>1575 <t>&MUST; be added by an intermediate proxy if it applies any1576 transformation to the representation, such as changing the content-coding,1577 media-type, or modifying the representation data, unless this Warning code1578 already appears in the response.</t>1579 </list>1710 214 Transformation applied 1711 <list> 1712 <t>&MUST; be added by an intermediate proxy if it applies any 1713 transformation to the representation, such as changing the 1714 content-coding, media-type, or modifying the representation data, unless 1715 this Warning code already appears in the response.</t> 1716 </list> 1580 1717 </t> 1581 1718 <t><?rfc needLines="4"?> 1582 299 Miscellaneous persistent warning1583 <list>1584 <t>The warning text can include arbitrary information to be presented to a human1585 user, or logged. A system receiving this warning &MUST-NOT; take any automated1586 a ction.</t>1587 </list>1719 299 Miscellaneous persistent warning 1720 <list> 1721 <t>The warning text can include arbitrary information to be presented to 1722 a human user, or logged. A system receiving this warning &MUST-NOT; take 1723 any automated action.</t> 1724 </list> 1588 1725 </t> 1589 1726 </section> … … 1593 1730 <section anchor="history.lists" title="History Lists"> 1594 1731 <t> 1595 User agents often have history mechanisms, such as "Back" buttons and history lists, that 1596 can be used to redisplay a representation retrieved earlier in a session. 1597 </t> 1598 <t> 1599 The freshness model (<xref target="expiration.model"/>) does not necessarily apply to history mechanisms. I.e., 1600 a history mechanism can display a previous representation even if it has expired. 1601 </t> 1602 <t> 1603 This does not prohibit the history mechanism from telling the user that a 1604 view might be stale, or from honoring cache directives (e.g., Cache-Control: no-store). 1605 </t> 1732 User agents often have history mechanisms, such as "Back" buttons and 1733 history lists, that can be used to redisplay a representation retrieved 1734 earlier in a session. 1735 </t> 1736 <t> 1737 The freshness model (<xref target="expiration.model"/>) does not 1738 necessarily apply to history mechanisms. I.e., a history mechanism can 1739 display a previous representation even if it has expired. 1740 </t> 1741 <t> 1742 This does not prohibit the history mechanism from telling the user that a 1743 view might be stale, or from honoring cache directives (e.g., 1744 Cache-Control: no-store). 1745 </t> 1606 1746 </section> 1607 1747 … … 1609 1749 <section anchor="IANA.considerations" title="IANA Considerations"> 1610 1750 1611 <section title="Cache Directive Registry" anchor="cache.directive.registration"> 1612 <t> 1613 The registration procedure for HTTP Cache Directives is defined by 1614 <xref target="cache.control.extensions"/> of this document. 1615 </t> 1616 <t> 1617 The HTTP Cache Directive Registry should be created at <eref target="http://www.iana.org/assignments/http-cache-directives"/> 1618 and be populated with the registrations below: 1751 <section title="Cache Directive Registry" 1752 anchor="cache.directive.registration"> 1753 <t> 1754 The registration procedure for HTTP Cache Directives is defined by <xref 1755 target="cache.control.extensions"/> of this document. 1756 </t> 1757 <t> 1758 The HTTP Cache Directive Registry should be created at <eref 1759 target="http://www.iana.org/assignments/http-cache-directives"/> and be 1760 populated with the registrations below: 1619 1761 </t> 1620 1762 <?BEGININC p6-cache.cache-directives ?> … … 1688 1830 <section title="Header Field Registration" anchor="header.field.registration"> 1689 1831 <t> 1690 The Message Header Field Registry located at <eref 1832 The Message Header Field Registry located at <eref 1691 1833 target="http://www.iana.org/assignments/message-headers/message-header-index.html" /> 1692 1834 should be updated with the permanent registrations below (see <xref target="RFC3864" />): … … 1740 1882 <?ENDINC p6-cache.iana-headers ?> 1741 1883 <t> 1742 The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task Force". 1884 The change controller is: "IETF (iesg@ietf.org) - Internet Engineering Task 1885 Force". 1743 1886 </t> 1744 1887 </section> … … 1748 1891 <section anchor="security.considerations" title="Security Considerations"> 1749 1892 <t> 1750 Caches expose additional potential vulnerabilities, since the contents of the cache 1751 represent an attractive target for malicious exploitation. Because cache contents persist 1752 after an HTTP request is complete, an attack on the cache can reveal information long after 1753 a user believes that the information has been removed from the network. Therefore, cache 1754 contents should be protected as sensitive information. 1893 Caches expose additional potential vulnerabilities, since the contents of 1894 the cache represent an attractive target for malicious exploitation. 1895 Because cache contents persist after an HTTP request is complete, an attack 1896 on the cache can reveal information long after a user believes that the 1897 information has been removed from the network. Therefore, cache contents 1898 should be protected as sensitive information. 1755 1899 </t> 1756 1900 </section> … … 1758 1902 <section anchor="ack" title="Acknowledgments"> 1759 1903 <t> 1760 Much of the content and presentation of the caching design is due to suggestions and1761 comments from individuals including: Shel Kaphan, Paul Leach, Koen Holtman, David Morris,1762 and Larry Masinter.1904 Much of the content and presentation of the caching design is due to 1905 suggestions and comments from individuals including: Shel Kaphan, Paul 1906 Leach, Koen Holtman, David Morris, and Larry Masinter. 1763 1907 </t> 1764 1908 </section>
Note: See TracChangeset
for help on using the changeset viewer.