Changeset 1379 for draft-ietf-httpbis/latest/p4-conditional.xml
- Timestamp:
- 06/08/11 00:59:19 (11 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
draft-ietf-httpbis/latest/p4-conditional.xml
r1373 r1379 324 324 </t> 325 325 326 <section title="Last-Modified" anchor="header.last-modified">327 <iref primary="true" item="Last-Modified header field" x:for-anchor=""/>328 <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/>329 <x:anchor-alias value="Last-Modified"/>330 <t>331 The "Last-Modified" header field indicates the date and time at332 which the origin server believes the selected representation was333 last modified.334 </t>335 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/>336 <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref>337 </artwork></figure>338 <t>339 An example of its use is340 </t>341 <figure><artwork type="example">342 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT343 </artwork></figure>344 345 <section title="Generation" anchor="lastmod.generation">346 <t>347 Origin servers &SHOULD; send Last-Modified for any selected348 representation for which a last modification date can be reasonably349 and consistently determined, since its use in conditional requests350 and evaluating cache freshness (&caching;) results in a substantial351 reduction of HTTP traffic on the Internet and can be a significant352 factor in improving service scalability and reliability.353 </t>354 <t>355 A representation is typically the sum of many parts behind the356 resource interface. The last-modified time would usually be357 the most recent time that any of those parts were changed.358 How that value is determined for any given resource is an359 implementation detail beyond the scope of this specification.360 What matters to HTTP is how recipients of the Last-Modified361 header field can use its value to make conditional requests362 and test the validity of locally cached responses.363 </t>364 <t>365 An origin server &SHOULD; obtain the Last-Modified value of the366 representation as close as possible to the time that it generates367 the Date field-value for its response. This allows a recipient to368 make an accurate assessment of the representation's modification time,369 especially if the representation changes near the time that the370 response is generated.371 </t>372 <t>373 An origin server with a clock &MUST-NOT; send a Last-Modified date374 that is later than the server's time of message origination (Date).375 If the last modification time is derived from implementation-specific376 metadata that evaluates to some time in the future, according to the377 origin server's clock, then the origin server &MUST; replace that378 value with the message origination date. This prevents a future379 modification date from having an adverse impact on cache validation.380 </t>381 </section>382 383 <section title="Comparison" anchor="lastmod.comparison">384 <t>385 A Last-Modified time, when used as a validator in a request, is386 implicitly weak unless it is possible to deduce that it is strong,387 using the following rules:388 <list style="symbols">389 <t>The validator is being compared by an origin server to the390 actual current validator for the representation and,</t>391 <t>That origin server reliably knows that the associated representation did392 not change twice during the second covered by the presented393 validator.</t>394 </list>395 </t>396 <t>397 or398 <list style="symbols">399 <t>The validator is about to be used by a client in an If-Modified-Since,400 If-Unmodified-Since header field, because the client has a cache entry,401 or If-Range for the associated representation, and</t>402 <t>That cache entry includes a Date value, which gives the time403 when the origin server sent the original response, and</t>404 <t>The presented Last-Modified time is at least 60 seconds before405 the Date value.</t>406 </list>407 </t>408 <t>409 or410 <list style="symbols">411 <t>The validator is being compared by an intermediate cache to the412 validator stored in its cache entry for the representation, and</t>413 <t>That cache entry includes a Date value, which gives the time414 when the origin server sent the original response, and</t>415 <t>The presented Last-Modified time is at least 60 seconds before416 the Date value.</t>417 </list>418 </t>419 <t>420 This method relies on the fact that if two different responses were421 sent by the origin server during the same second, but both had the422 same Last-Modified time, then at least one of those responses would423 have a Date value equal to its Last-Modified time. The arbitrary 60-second424 limit guards against the possibility that the Date and Last-Modified425 values are generated from different clocks, or at somewhat426 different times during the preparation of the response. An427 implementation &MAY; use a value larger than 60 seconds, if it is428 believed that 60 seconds is too short.429 </t>430 </section>431 </section>432 433 <section title="ETag" anchor="header.etag">434 <iref primary="true" item="ETag header field" x:for-anchor=""/>435 <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/>436 <x:anchor-alias value="ETag"/>437 <x:anchor-alias value="entity-tag"/>438 <x:anchor-alias value="entity.tags"/>439 <x:anchor-alias value="opaque-tag"/>440 <x:anchor-alias value="weak"/>441 <t>442 The ETag header field provides the current entity-tag for the443 selected representation.444 An entity-tag is an opaque validator for differentiating between445 multiple representations of the same resource, regardless of whether446 those multiple representations are due to resource state changes over447 time, content negotiation resulting in multiple representations being448 valid at the same time, or both. An entity-tag consists of an opaque449 quoted string, possibly prefixed by a weakness indicator.450 </t>451 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/><iref primary="true" item="Grammar" subitem="entity-tag"/><iref primary="true" item="Grammar" subitem="weak"/><iref primary="true" item="Grammar" subitem="opaque-tag"/>452 <x:ref>ETag</x:ref> = <x:ref>entity-tag</x:ref>453 454 <x:ref>entity-tag</x:ref> = [ <x:ref>weak</x:ref> ] <x:ref>opaque-tag</x:ref>455 <x:ref>weak</x:ref> = <x:abnf-char-sequence>"W/"</x:abnf-char-sequence> ; "W/", case-sensitive456 <x:ref>opaque-tag</x:ref> = <x:ref>quoted-string</x:ref>457 </artwork></figure>458 <t>459 An entity-tag can be more reliable for validation than a modification460 date in situations where it is inconvenient to store modification461 dates, where the one-second resolution of HTTP date values is not462 sufficient, or where modification dates are not consistently maintained.463 </t>464 <figure><preamble>465 Examples:466 </preamble>467 <artwork type="example">468 ETag: "xyzzy"469 ETag: W/"xyzzy"470 ETag: ""471 </artwork></figure>472 473 <section title="Generation" anchor="entity.tag.generation">474 <t>475 The principle behind entity-tags is that only the service author476 knows the implementation of a resource well enough to select the477 most accurate and efficient validation mechanism for that resource,478 and that any such mechanism can be mapped to a simple sequence of479 octets for easy comparison. Since the value is opaque, there is no480 need for the client to be aware of how each entity-tag is constructed.481 </t>482 <t>483 For example, a resource that has implementation-specific versioning484 applied to all changes might use an internal revision number, perhaps485 combined with a variance identifier for content negotiation, to486 accurately differentiate between representations.487 Other implementations might use a stored hash of representation content,488 a combination of various filesystem attributes, or a modification489 timestamp that has sub-second resolution.490 </t>491 <t>492 Origin servers &SHOULD; send ETag for any selected representation493 for which detection of changes can be reasonably and consistently494 determined, since the entity-tag's use in conditional requests and495 evaluating cache freshness (&caching;) can result in a substantial496 reduction of HTTP network traffic and can be a significant factor in497 improving service scalability and reliability.498 </t>499 </section>500 501 326 <section title="Weak versus Strong" anchor="weak.and.strong.validators"> 502 327 <t> … … 530 355 </t> 531 356 <t> 532 An entity-tag is normally a strong validator, but the protocol533 provides a mechanism to tag an entity-tag as "weak".534 <list><t>535 357 A representation's modification time, if defined with only one-second 536 358 resolution, could be a weak validator, since it is possible that 537 359 the representation might be modified twice during a single second. 538 360 </t><t> 539 361 Support for weak validators is optional. However, weak validators 540 362 allow for more efficient caching of equivalent objects; for … … 542 364 updated every few days or weeks, and any value during that period 543 365 is likely "good enough" to be equivalent. 544 </t></list>545 366 </t> 546 367 <t> … … 570 391 in use for representations of multiple resources at the same time 571 392 and does not imply that those representations are equivalent). 393 </t> 394 <t> 395 A "use" of a validator is either when a client generates a request 396 and includes the validator in a precondition, or when a server 397 compares two validators. 398 </t> 399 <t> 400 Strong validators are usable in any context. Weak validators are only 401 usable in contexts that do not depend on exact equality of a representation. 402 For example, either kind is usable for a normal conditional GET. 403 </t> 404 </section> 405 406 <section title="Last-Modified" anchor="header.last-modified"> 407 <iref primary="true" item="Last-Modified header field" x:for-anchor=""/> 408 <iref primary="true" item="Header Fields" subitem="Last-Modified" x:for-anchor=""/> 409 <x:anchor-alias value="Last-Modified"/> 410 <t> 411 The "Last-Modified" header field indicates the date and time at 412 which the origin server believes the selected representation was 413 last modified. 414 </t> 415 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="Last-Modified"/> 416 <x:ref>Last-Modified</x:ref> = <x:ref>HTTP-date</x:ref> 417 </artwork></figure> 418 <t> 419 An example of its use is 420 </t> 421 <figure><artwork type="example"> 422 Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT 423 </artwork></figure> 424 425 <section title="Generation" anchor="lastmod.generation"> 426 <t> 427 Origin servers &SHOULD; send Last-Modified for any selected 428 representation for which a last modification date can be reasonably 429 and consistently determined, since its use in conditional requests 430 and evaluating cache freshness (&caching;) results in a substantial 431 reduction of HTTP traffic on the Internet and can be a significant 432 factor in improving service scalability and reliability. 433 </t> 434 <t> 435 A representation is typically the sum of many parts behind the 436 resource interface. The last-modified time would usually be 437 the most recent time that any of those parts were changed. 438 How that value is determined for any given resource is an 439 implementation detail beyond the scope of this specification. 440 What matters to HTTP is how recipients of the Last-Modified 441 header field can use its value to make conditional requests 442 and test the validity of locally cached responses. 443 </t> 444 <t> 445 An origin server &SHOULD; obtain the Last-Modified value of the 446 representation as close as possible to the time that it generates 447 the Date field-value for its response. This allows a recipient to 448 make an accurate assessment of the representation's modification time, 449 especially if the representation changes near the time that the 450 response is generated. 451 </t> 452 <t> 453 An origin server with a clock &MUST-NOT; send a Last-Modified date 454 that is later than the server's time of message origination (Date). 455 If the last modification time is derived from implementation-specific 456 metadata that evaluates to some time in the future, according to the 457 origin server's clock, then the origin server &MUST; replace that 458 value with the message origination date. This prevents a future 459 modification date from having an adverse impact on cache validation. 460 </t> 461 </section> 462 463 <section title="Comparison" anchor="lastmod.comparison"> 464 <t> 465 A Last-Modified time, when used as a validator in a request, is 466 implicitly weak unless it is possible to deduce that it is strong, 467 using the following rules: 468 <list style="symbols"> 469 <t>The validator is being compared by an origin server to the 470 actual current validator for the representation and,</t> 471 <t>That origin server reliably knows that the associated representation did 472 not change twice during the second covered by the presented 473 validator.</t> 474 </list> 475 </t> 476 <t> 477 or 478 <list style="symbols"> 479 <t>The validator is about to be used by a client in an If-Modified-Since, 480 If-Unmodified-Since header field, because the client has a cache entry, 481 or If-Range for the associated representation, and</t> 482 <t>That cache entry includes a Date value, which gives the time 483 when the origin server sent the original response, and</t> 484 <t>The presented Last-Modified time is at least 60 seconds before 485 the Date value.</t> 486 </list> 487 </t> 488 <t> 489 or 490 <list style="symbols"> 491 <t>The validator is being compared by an intermediate cache to the 492 validator stored in its cache entry for the representation, and</t> 493 <t>That cache entry includes a Date value, which gives the time 494 when the origin server sent the original response, and</t> 495 <t>The presented Last-Modified time is at least 60 seconds before 496 the Date value.</t> 497 </list> 498 </t> 499 <t> 500 This method relies on the fact that if two different responses were 501 sent by the origin server during the same second, but both had the 502 same Last-Modified time, then at least one of those responses would 503 have a Date value equal to its Last-Modified time. The arbitrary 60-second 504 limit guards against the possibility that the Date and Last-Modified 505 values are generated from different clocks, or at somewhat 506 different times during the preparation of the response. An 507 implementation &MAY; use a value larger than 60 seconds, if it is 508 believed that 60 seconds is too short. 509 </t> 510 </section> 511 </section> 512 513 <section title="ETag" anchor="header.etag"> 514 <iref primary="true" item="ETag header field" x:for-anchor=""/> 515 <iref primary="true" item="Header Fields" subitem="ETag" x:for-anchor=""/> 516 <x:anchor-alias value="ETag"/> 517 <x:anchor-alias value="entity-tag"/> 518 <x:anchor-alias value="entity.tags"/> 519 <x:anchor-alias value="opaque-tag"/> 520 <x:anchor-alias value="weak"/> 521 <t> 522 The ETag header field provides the current entity-tag for the 523 selected representation. 524 An entity-tag is an opaque validator for differentiating between 525 multiple representations of the same resource, regardless of whether 526 those multiple representations are due to resource state changes over 527 time, content negotiation resulting in multiple representations being 528 valid at the same time, or both. An entity-tag consists of an opaque 529 quoted string, possibly prefixed by a weakness indicator. 530 </t> 531 <figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="ETag"/><iref primary="true" item="Grammar" subitem="entity-tag"/><iref primary="true" item="Grammar" subitem="weak"/><iref primary="true" item="Grammar" subitem="opaque-tag"/> 532 <x:ref>ETag</x:ref> = <x:ref>entity-tag</x:ref> 533 534 <x:ref>entity-tag</x:ref> = [ <x:ref>weak</x:ref> ] <x:ref>opaque-tag</x:ref> 535 <x:ref>weak</x:ref> = <x:abnf-char-sequence>"W/"</x:abnf-char-sequence> ; "W/", case-sensitive 536 <x:ref>opaque-tag</x:ref> = <x:ref>quoted-string</x:ref> 537 </artwork></figure> 538 <t> 539 An entity-tag can be more reliable for validation than a modification 540 date in situations where it is inconvenient to store modification 541 dates, where the one-second resolution of HTTP date values is not 542 sufficient, or where modification dates are not consistently maintained. 543 </t> 544 <figure><preamble> 545 Examples: 546 </preamble> 547 <artwork type="example"> 548 ETag: "xyzzy" 549 ETag: W/"xyzzy" 550 ETag: "" 551 </artwork></figure> 552 <t> 553 An entity-tag can be either a weak or strong validator, with 554 strong being the default. If an origin server provides an entity-tag 555 for a representation and the generation of that entity-tag does not satisfy 556 the requirements for a strong validator 557 (<xref target="weak.and.strong.validators"/>), then that 558 entity-tag &MUST; be marked as weak by prefixing its opaque value 559 with "W/" (case-sensitive). 560 </t> 561 562 <section title="Generation" anchor="entity.tag.generation"> 563 <t> 564 The principle behind entity-tags is that only the service author 565 knows the implementation of a resource well enough to select the 566 most accurate and efficient validation mechanism for that resource, 567 and that any such mechanism can be mapped to a simple sequence of 568 octets for easy comparison. Since the value is opaque, there is no 569 need for the client to be aware of how each entity-tag is constructed. 570 </t> 571 <t> 572 For example, a resource that has implementation-specific versioning 573 applied to all changes might use an internal revision number, perhaps 574 combined with a variance identifier for content negotiation, to 575 accurately differentiate between representations. 576 Other implementations might use a stored hash of representation content, 577 a combination of various filesystem attributes, or a modification 578 timestamp that has sub-second resolution. 579 </t> 580 <t> 581 Origin servers &SHOULD; send ETag for any selected representation 582 for which detection of changes can be reasonably and consistently 583 determined, since the entity-tag's use in conditional requests and 584 evaluating cache freshness (&caching;) can result in a substantial 585 reduction of HTTP network traffic and can be a significant factor in 586 improving service scalability and reliability. 572 587 </t> 573 588 </section> … … 590 605 </t> 591 606 <t> 592 A "use" of a validator is either when a client generates a request593 and includes the validator in a precondition, or when a server594 compares two validators.595 </t>596 <t>597 Strong validators are usable in any context. Weak validators are only598 usable in contexts that do not depend on exact equality of a representation.599 For example, either kind is usable for a normal conditional GET.600 </t>601 <t>602 607 The example below shows the results for a set of entity-tag pairs, 603 608 and both the weak and strong comparison function results: … … 629 634 <c>match</c> 630 635 </texttable> 631 <t> 632 An entity-tag is strong unless it is explicitly tagged as weak. 633 </t> 636 </section> 637 638 <section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg"> 639 <t> 640 Consider a resource that is subject to content negotiation (&content-negotiation;), 641 and where the representations returned upon a GET request vary based on 642 the Accept-Encoding request header field (&header-accept-encoding;): 643 </t> 644 <figure><preamble>>> Request:</preamble><artwork type="message/http; msgtype="request"" x:indent-with=" "> 645 GET /index HTTP/1.1 646 Host: www.example.com 647 Accept-Encoding: gzip 648 649 </artwork></figure> 650 <t> 651 In this case, the response might or might not use the gzip content coding. 652 If it does not, the response might look like: 653 </t> 654 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype="response"" x:indent-with=" "> 655 HTTP/1.1 200 OK 656 Date: Thu, 26 Mar 2010 00:05:00 GMT 657 ETag: "123-a" 658 Content-Length: <x:length-of target="exbody"/> 659 Vary: Accept-Encoding 660 Content-Type: text/plain 661 662 <x:span anchor="exbody">Hello World! 663 Hello World! 664 Hello World! 665 Hello World! 666 Hello World! 667 </x:span></artwork></figure> 668 <t> 669 An alternative representation that does use gzip content coding would be: 670 </t> 671 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype="response"" x:indent-with=" "> 672 HTTP/1.1 200 OK 673 Date: Thu, 26 Mar 2010 00:05:00 GMT 674 ETag: "123-b" 675 Content-Length: 43 676 Vary: Accept-Encoding 677 Content-Type: text/plain 678 Content-Encoding: gzip 679 680 <spanx>...binary data...</spanx></artwork></figure> 681 <x:note> 682 <t> 683 <x:h>Note:</x:h> Content codings are a property of the representation, 684 so therefore an entity-tag of an encoded representation must be distinct 685 from an unencoded representation to prevent conflicts during cache updates 686 and range requests. In contrast, transfer codings (&transfer-codings;) 687 apply only during message transfer and do not require distinct entity-tags. 688 </t> 689 </x:note> 690 </section> 634 691 </section> 635 692 … … 712 769 </section> 713 770 714 <section title="Example: Entity-tags varying on Content-Negotiated Resources" anchor="example.entity.tag.vs.conneg">715 <t>716 Consider a resource that is subject to content negotiation (&content-negotiation;),717 and where the representations returned upon a GET request vary based on718 the Accept-Encoding request header field (&header-accept-encoding;):719 </t>720 <figure><preamble>>> Request:</preamble><artwork type="message/http; msgtype="request"" x:indent-with=" ">721 GET /index HTTP/1.1722 Host: www.example.com723 Accept-Encoding: gzip724 725 </artwork></figure>726 <t>727 In this case, the response might or might not use the gzip content coding.728 If it does not, the response might look like:729 </t>730 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype="response"" x:indent-with=" ">731 HTTP/1.1 200 OK732 Date: Thu, 26 Mar 2010 00:05:00 GMT733 ETag: "123-a"734 Content-Length: <x:length-of target="exbody"/>735 Vary: Accept-Encoding736 Content-Type: text/plain737 738 <x:span anchor="exbody">Hello World!739 Hello World!740 Hello World!741 Hello World!742 Hello World!743 </x:span></artwork></figure>744 <t>745 An alternative representation that does use gzip content coding would be:746 </t>747 <figure><preamble>>> Response:</preamble><artwork type="message/http; msgtype="response"" x:indent-with=" ">748 HTTP/1.1 200 OK749 Date: Thu, 26 Mar 2010 00:05:00 GMT750 ETag: "123-b"751 Content-Length: 43752 Vary: Accept-Encoding753 Content-Type: text/plain754 Content-Encoding: gzip755 756 <spanx>...binary data...</spanx></artwork></figure>757 <x:note>758 <t>759 <x:h>Note:</x:h> Content codings are a property of the representation,760 so therefore an entity-tag of an encoded representation must be distinct761 from an unencoded representation to prevent conflicts during cache updates762 and range requests. In contrast, transfer codings (&transfer-codings;)763 apply only during message transfer and do not require distinct entity-tags.764 </t>765 </x:note>766 </section>767 </section>768 771 </section> 769 772
Note: See TracChangeset
for help on using the changeset viewer.