* WGs marked with an * asterisk has had at least one new draft made available during the last 5 days

Ignore:
Timestamp:
2011-08-03 22:41:28 (3 years ago)
Author:
fielding@gbiv.com
Message:

Clarify what should happen when a response is incomplete.
Disentangle the requirements surrounding conditional range
requests, strong validators, and recombining partial content
to remove redundant redundancy. Separate handling of 304
responses into a separate section on cache freshening.

Add definitions for "cache entry" and "cache key".
Improve introductions for caching and cache operation.

These changes should all be editorial, hopefully.
Tangentially related to #101 and #304.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p6-cache.xml

    r1373 r1374  
    2121  <!ENTITY effective-request-uri      "<xref target='Part1' x:rel='#effective.request.uri' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2222  <!ENTITY messaging                   "<xref target='Part1' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     23  <!ENTITY semantics                   "<xref target='Part2' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2324  <!ENTITY conditional                 "<xref target='Part4' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    2425  <!ENTITY partial                     "<xref target='Part5' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     
    3233  <!ENTITY header-fields               "<xref target='Part1' x:rel='#header.fields' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    3334  <!ENTITY safe-methods                "<xref target='Part2' x:rel='#safe.methods' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     35  <!ENTITY entity-tags                 "<xref target='Part4' x:rel='#header.etag' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    3436  <!ENTITY weak-and-strong             "<xref target='Part4' x:rel='#weak.and.strong.validators' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     37  <!ENTITY lastmod-comparison          "<xref target='Part4' x:rel='#lastmod.comparison' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    3538  <!ENTITY status-codes                "<xref target='Part2' x:rel='#status.codes' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
    3639  <!ENTITY status.2xx                  "<xref target='Part2' x:rel='#status.2xx' xmlns:x='http://purl.org/net/xml2rfc/ext'/>"> 
     
    252255</t> 
    253256<t> 
    254    Caching would be useless if it did not significantly improve performance. 
    255    The goal of caching in HTTP/1.1 is to reuse a prior response message to 
    256    satisfy a current request. In some cases, a stored response can be reused 
    257    without the need for a network request, reducing latency and network 
    258    round-trips; a "freshness" mechanism is used for this purpose (see <xref 
    259    target="expiration.model" />). Even when a new request is required, it is 
    260    often possible to reuse all or parts of the payload of a prior response to 
    261    satisfy the request, thereby reducing network bandwidth usage; a 
    262    "validation" mechanism is used for this purpose (see <xref 
    263    target="validation.model" />). 
     257   The goal of caching in HTTP/1.1 is to significantly improve performance 
     258   by reusing a prior response message to satisfy a current request. 
     259   A stored response is considered "fresh", as defined in 
     260   <xref target="expiration.model" />, if the response can be reused without 
     261   "validation" (checking with the origin server to see if the cached response 
     262   remains valid for this request).  A fresh cache response can therefore 
     263   reduce both latency and network transfers each time it is reused. 
     264   When a cached response is not fresh, it might still be reusable if it can 
     265   be freshened by validation (<xref target="validation.model" />) or if the 
     266   origin is unavailable. 
    264267</t> 
    265268</section> 
     
    283286   <x:dfn>shared cache</x:dfn> 
    284287   <list> 
    285       <t>A cache that is accessible to more than one user; usually (but 
    286         not always) deployed as part of an intermediary.</t> 
     288      <t>A cache that stores responses to be reused by more than one user; 
     289         usually (but not always) deployed as part of an intermediary.</t> 
    287290   </list> 
    288291</t> 
     
    366369      <t>A protocol element (e.g., an entity-tag or a Last-Modified time) that 
    367370      is used to find out whether a stored response is an equivalent copy of 
    368       a representation.</t> 
     371      a representation. See &weak-and-strong;.</t> 
     372   </list> 
     373</t> 
     374<t> 
     375   <iref item="strong validator" /> 
     376   <iref item="validator, strong" /> 
     377   <x:dfn>strong validator</x:dfn> 
     378   <list> 
     379      <t>A validator that is defined by the origin server such that its 
     380         current value will change if the representation body changes; i.e., 
     381         an entity-tag that is not marked as weak (&entity-tags;) or, 
     382         if no entity-tag is provided, a Last-Modified value that is strong 
     383         in the sense defined by &lastmod-comparison;.</t> 
    369384   </list> 
    370385</t> 
     
    468483 
    469484<section anchor="caching.overview" title="Cache Operation"> 
     485<iref item="cache entry" /> 
     486<iref item="cache key" /> 
     487<t> 
     488   Proper cache operation preserves the semantics of HTTP transfers 
     489   (&semantics;) while eliminating the transfer of information already held 
     490   in the cache.  Although caching is an entirely &OPTIONAL; feature of HTTP, 
     491   we assume that reusing the cached response is desirable and that such 
     492   reuse is the default behavior when no requirement or locally-desired 
     493   configuration prevents it.  Therefore, HTTP cache requirements are focused 
     494   on preventing a cache from either storing a non-reusable response or 
     495   reusing a stored response inappropriately. 
     496</t> 
     497<t> 
     498   Each <x:dfn>cache entry</x:dfn> consists of a cache key and one or more 
     499   HTTP responses corresponding to prior requests that used the same key. 
     500   The most common form of cache entry is a successful result of a retrieval 
     501   request: i.e., a 200 (OK) response containing a representation of the 
     502   resource identified by the request target.  However, it is also possible 
     503   to cache negative results (e.g., 404 not found), incomplete results 
     504   (e.g., 206 partial content), and responses to safe methods other than 
     505   GET if the method's definition allows such caching and defines something 
     506   suitable for use as a cache key. 
     507</t> 
     508<t> 
     509   The default <x:dfn>cache key</x:dfn> consists of the request method and 
     510   target URI.  However, since HTTP caches in common use today are typically 
     511   limited to caching responses to GET, most implementations simply decline 
     512   other methods and use only the URI as the key. 
     513</t> 
     514<t> 
     515   If a request target is subject to content negotiation, its cache entry 
     516   might consist of multiple stored responses, each differentiated by a 
     517   secondary key for the values of the original request's selecting header 
     518   fields (<xref target="caching.negotiated.responses"/>). 
     519</t> 
    470520 
    471521<section anchor="response.cacheability" title="Response Cacheability"> 
     
    509559<t> 
    510560   In this context, a cache has "understood" a request method or a response 
    511    status code if it recognises it and implements any cache-specific 
    512    behavior. In particular, 206 Partial Content responses cannot be cached by 
    513    an implementation that does not handle partial content (see <xref 
    514    target="errors.or.incomplete.response.cache.behavior" />). 
    515 </t> 
    516 <t> 
    517    Note that in normal operation, most caches will not store a response that 
     561   status code if it recognizes it and implements any cache-specific 
     562   behavior. 
     563</t> 
     564<t> 
     565   Note that, in normal operation, most caches will not store a response that 
    518566   has neither a cache validator nor an explicit expiration time, as such 
    519567   responses are not usually useful to store. However, caches are not 
    520568   prohibited from storing such responses. 
    521569</t> 
    522  
    523 <section anchor="errors.or.incomplete.response.cache.behavior"  
    524    title="Storing Partial and Incomplete Responses"> 
    525 <t> 
    526    A cache that receives an incomplete response (for example, with fewer bytes 
    527    of data than specified in a Content-Length header field) can store the response, 
    528    but &MUST; treat it as a partial response &partial;. Partial responses can 
    529    be combined as described in &combining-byte-ranges;; the result might be a 
    530    full response or might still be partial. A cache &MUST-NOT; return a 
    531    partial response to a client without explicitly marking it as such using 
    532    the 206 (Partial Content) status code. 
    533 </t> 
    534 <t> 
    535    A cache that does not support the Range and Content-Range header fields 
    536    &MUST-NOT; store incomplete or partial responses. 
    537 </t> 
    538 </section> 
    539  
     570<t> 
     571   A response message is considered complete when all of the octets 
     572   indicated by the message framing (&messaging;) are received 
     573   prior to the connection being closed. 
     574   If the request is GET, the response status is 200 (OK), and the entire 
     575   response header block has been received, a cache &MAY; store an incomplete 
     576   response message-body if the cache entry is recorded as incomplete. 
     577   Likewise, a 206 (Partial Content) response &MAY; be stored as if it were 
     578   an incomplete 200 (OK) cache entry.  However, a cache &MUST-NOT; store 
     579   incomplete or partial content responses if it does not support the Range 
     580   and Content-Range header fields or if it does not understand the 
     581   range units used in those fields. 
     582</t> 
     583<t> 
     584   A cache &MAY; complete a stored incomplete response by making a subsequent 
     585   range request (&partial;) and combining the successful response with the 
     586   stored entry, as defined in <xref target="combining.responses"/>. 
     587   A cache &MUST-NOT; use an incomplete response to answer requests 
     588   unless the response has been made complete or the request is partial and 
     589   specifies a range that is wholly within the incomplete response. 
     590   A cache &MUST-NOT; send a partial response to a client without explicitly 
     591   marking it as such using the 206 (Partial Content) status code. 
     592</t> 
    540593</section> 
    541594 
     
    881934<t> 
    882935   A 304 (Not Modified) response status code indicates that the stored 
    883    response can be updated and reused; see <xref target="combining.responses"/>. 
     936   response can be updated and reused; see <xref target="freshening.responses"/>. 
    884937</t> 
    885938<t> 
     
    887940   stored responses nominated in the conditional request is suitable. Instead, 
    888941   a cache &SHOULD; use the full response to satisfy the request and &MAY;  
    889    replace the stored response. 
     942   replace the stored response(s). 
    890943</t> 
    891944<t> 
     
    10161069</section> 
    10171070 
    1018 <section anchor="combining.responses" title="Combining Responses"> 
    1019 <t> 
    1020    When a cache receives a 304 (Not Modified) response or a 206 (Partial 
    1021    Content) response (in this section, the "new" response"), it needs to 
    1022    create an updated response by combining the stored response with the new 
    1023    one, so that the updated response can be used to satisfy the request, and 
    1024    potentially update the cached response. 
    1025 </t> 
    1026 <t> 
    1027    If the new response contains an ETag, it identifies the stored response to 
    1028    use. <cref anchor="TODO-mention-CL">might need language about 
    1029    Content-Location here</cref><cref 
    1030    anchor="TODO-select-for-combine">Shouldn't this be the selected 
    1031    response?</cref> 
    1032 </t> 
    1033 <t> 
    1034    When the new response's status code is 206 (partial content), a cache 
    1035    &MUST-NOT; combine it with the old response if either response does not 
    1036    have a validator, and &MUST-NOT; combine it with the old response when 
    1037    those validators do not match with the strong comparison function 
    1038    (see &weak-and-strong;). 
    1039 </t> 
    1040 <t> 
    1041    The stored response header fields are used as those of the updated response, 
    1042    except that 
     1071<section anchor="combining.responses" title="Combining Partial Content"> 
     1072<t> 
     1073   A response might transfer only a partial representation if the 
     1074   connection closed prematurely or if the request used one or more Range 
     1075   specifiers (&partial;).  After several such transfers, a cache might have 
     1076   received several ranges of the same representation.  A cache &MAY; combine 
     1077   these ranges into a single stored response, and reuse that response to 
     1078   satisfy later requests, if they all share the same strong validator and 
     1079   the cache complies with the client requirements in &combining-byte-ranges;. 
     1080</t> 
     1081<t> 
     1082   When combining the new response with one or more stored responses, a 
     1083   cache &MUST;: 
    10431084   <list style="symbols"> 
    1044       <t>a cache &MUST; delete any stored Warning header fields with warn-code 1xx (see <xref 
    1045       target="header.warning" />).</t> 
    1046       <t>a cache &MUST; retain any stored Warning header fields with warn-code 2xx.</t> 
    1047       <t>a cache &MUST; use other header fields provided in the new response to replace all 
    1048       instances of the corresponding header fields from the stored response.</t> 
    1049    </list> 
    1050 </t> 
    1051 <t> 
    1052    A cache &MUST; use the updated response header fields to replace those of the stored 
    1053    response (unless the stored response is removed). In 
    1054    the case of a 206 response, a cache &MAY; store the combined representation. 
     1085      <t>delete any Warning header fields in the stored response with 
     1086         warn-code 1xx (see <xref target="header.warning" />);</t> 
     1087      <t>retain any Warning header fields in the stored response with 
     1088         warn-code 2xx; and,</t> 
     1089      <t>use other header fields provided in the new response, aside 
     1090         from Content-Range, to replace all instances of the corresponding 
     1091         header fields in the stored response.</t> 
     1092   </list> 
     1093</t> 
     1094</section> 
     1095 
     1096<section anchor="freshening.responses" title="Freshening Responses"> 
     1097<t> 
     1098   When a cache receives a 304 (Not Modified) response and already has one 
     1099   or more stored 200 (OK) responses for the same cache key, the cache needs 
     1100   to identify which of the stored responses are updated by this new response 
     1101   and then update the stored response(s) with the new information provided in 
     1102   the 304 response. 
     1103   <list style="symbols"> 
     1104    <t> 
     1105     If the new response contains a strong validator, then that strong 
     1106     validator identifies the selected representation.  All of the stored 
     1107     responses with the same strong validator are selected. 
     1108     If none of the stored responses contain the same strong validator, then 
     1109     this new response corresponds to a new selected representation and 
     1110     &MUST-NOT; update the existing stored responses. 
     1111    </t> 
     1112    <t> 
     1113     If the new response contains a weak validator and that validator 
     1114     corresponds to one of the cache's stored responses, then the most 
     1115     recent of those matching stored responses is selected. 
     1116    </t> 
     1117    <t> 
     1118     If the new response does not include any form of validator, there is 
     1119     only one stored response, and that stored response also lacks a 
     1120     validator, then that stored response is selected. 
     1121    </t> 
     1122   </list> 
     1123</t> 
     1124<t> 
     1125   If a stored response is selected for update, the cache &MUST;: 
     1126   <list style="symbols"> 
     1127      <t>delete any Warning header fields in the stored response with 
     1128         warn-code 1xx (see <xref target="header.warning" />);</t> 
     1129      <t>retain any Warning header fields in the stored response with 
     1130         warn-code 2xx; and,</t> 
     1131      <t>use other header fields provided in the 304 response to replace 
     1132         all instances of the corresponding header fields in the stored 
     1133         response.</t> 
     1134   </list> 
    10551135</t> 
    10561136</section> 
Note: See TracChangeset for help on using the changeset viewer.