Ignore:
Timestamp:
Aug 3, 2011, 10:41:28 PM (8 years ago)
Author:
fielding@…
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.