Ignore:
Timestamp:
11/08/13 10:20:11 (8 years ago)
Author:
fielding@…
Message:

Rephrase If-Match and If-Unmodified-Since, again, to describe how a cache is supposed to evaluate them; addresses part of #479

File:
1 edited

Legend:

Unmodified
Added
Removed
  • draft-ietf-httpbis/latest/p4-conditional.xml

    r2354 r2355  
    2929  <!ENTITY semantics                  "<xref target='Part2' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3030  <!ENTITY caching                    "<xref target='Part6' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     31  <!ENTITY cache-key                  "<xref target='Part6' x:rel='#constructing.responses.from.caches' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3132  <!ENTITY freshening-responses       "<xref target='Part6' x:rel='#freshening.responses' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
    3233  <!ENTITY header-accept-encoding     "<xref target='Part2' x:rel='#header.accept-encoding' xmlns:x='http://purl.org/net/xml2rfc/ext'/>">
     
    661662  <x:anchor-alias value="If-Match"/>
    662663<t>
    663    The "If-Match" header field can be used to make a request method conditional
    664    on the current existence or value of an entity-tag for one or more
    665    representations of the target resource.
    666 </t>
    667 <t>
    668    If-Match is generally useful for resource update requests, such as PUT
    669    requests, as a means for protecting against accidental overwrites when
    670    multiple clients are acting in parallel on the same resource (i.e., the
    671    "lost update" problem).  An If-Match field-value of "*" places the
    672    precondition on the existence of any current representation for the
    673    target resource.
     664   The "If-Match" header field makes the request method conditional on either
     665   the existence of a current representation for the target resource, when
     666   the field-value is "*", or on the selected representation having an
     667   entity-tag that matches one of those provided in the field-value.
    674668</t>
    675669<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Match"/>
     
    677671</artwork></figure>
    678672<t>
    679    The If-Match condition is met if and only if any of the entity-tags listed
    680    in the If-Match field value match the entity-tag of the selected
    681    representation using the weak comparison function (as per <xref
    682    target="entity.tag.comparison"/>), or if "*" is given and any current
     673   Examples:
     674</t>
     675<figure><artwork type="example">
     676  If-Match: "xyzzy"
     677  If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
     678  If-Match: *
     679</artwork></figure>
     680<t>
     681   If the request semantics (method and header fields) allow the request to be
     682   satisfied with a cached response, a cache &SHOULD; evaluate the condition
     683   based on its currently stored set of suitable responses for that request
     684   (see &cache-key;).
     685   If the field-value is "*" and any suitable response is currently stored,
     686   or if the field-value is a list of entity-tag values and at least one of
     687   the suitable responses has an <x:ref>ETag</x:ref> header field with a
     688   value matching an entity-tag in that list, then the cache &SHOULD; reuse
     689   the most suitable of those matching responses to satisfy the request.
     690   If the condition is not met, none of the cached responses is suitable for
     691   reuse in response to this request.
     692</t>
     693<t>
     694   If the request semantics cannot be satisfied with a cached response, the
     695   conditional is only evaluated when received by an origin server.
     696   For example, If-Match is most often used with state-changing requests,
     697   such as PUT, to prevent accidental overwrites when multiple user agents
     698   might be acting in parallel on the same resource (i.e., to prevent the
     699   "lost update" problem).
     700</t>
     701<t>
     702   When the If-Match field-value consists of a list of entity-tag values,
     703   the condition is met if any of the entity-tags listed match, using the weak
     704   comparison function (as per <xref target="entity.tag.comparison"/>), the
     705   entity-tag of the selected representation.
     706   When the If-Match field-value is "*", the condition is met if any current
    683707   representation exists for the target resource.
    684708</t>
    685709<t>
    686    If the condition is met, the server &MAY; perform the request method.
     710   If the condition is met, the origin server &MAY; perform the requested
     711   method.
    687712</t>
    688713<t>
     
    694719   state is already reflected in the current state of the target resource
    695720   (i.e., the change requested by the user agent has already succeeded, but
    696    the user agent might not be aware of that due to the prior response message
    697    being lost or because a compatible change was made by some other user
    698    agent). In the latter case, the origin server &MUST-NOT; send a
    699    <x:ref>204 (No Content)</x:ref> status code unless it can verify that the
    700    request is a duplicate of an immediately prior change made by the same user
    701    agent.
    702 </t>
    703 <t>
    704    A proxy using a cached response as the selected representation
    705    &MUST-NOT; perform the requested method if the condition is not met;
    706    instead, the proxy &MUST; forward the request towards the origin server.
    707 </t>
    708 <t>
    709    Examples:
    710 </t>
    711 <figure><artwork type="example">
    712   If-Match: "xyzzy"
    713   If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
    714   If-Match: *
    715 </artwork></figure>
     721   the user agent might not be aware of that because the prior response message
     722   was lost or a compatible change was made by some other user agent).
     723   In the latter case, the origin server &MUST-NOT; send a validator header
     724   field in the response unless it can verify that the request is a duplicate
     725   of an immediately prior change made by the same user agent.
     726</t>
    716727</section>
    717728
     
    861872  <x:anchor-alias value="If-Unmodified-Since"/>
    862873<t>
    863    The "If-Unmodified-Since" header field can be used to make a request
    864    method conditional by modification date: if the selected representation
    865    has not been modified since the time specified in this field, then the
    866    condition is met.  If-Unmodified-Since is useful for resource update
    867    requests, when the resource does not provide entity-tag values, as a means
    868    for protecting against accidental overwrites when multiple clients are
    869    acting in parallel on the same resource (i.e., the "lost update" problem).
     874   The "If-Unmodified-Since" header field makes the request method conditional
     875   on the selected representation's last modification date being earlier or
     876   equal to the date provided in the field-value. This field accomplishes the
     877   same purpose as <x:ref>If-Match</x:ref> for cases where the user agent does
     878   not have an entity-tag for the representation.
    870879</t>
    871880<figure><artwork type="abnf2616"><iref primary="true" item="Grammar" subitem="If-Unmodified-Since"/>
     
    879888</artwork></figure>
    880889<t>
    881    If the condition is met, the server &MAY; perform the request method.
     890   A server &MUST; ignore If-Unmodified-Since if the selected representation
     891   has an entity-tag and the request contains an If-Match header field;
     892   the condition in If-Match, when applicable, is considered to be a more
     893   accurate replacement for the condition in If-Unmodified-Since.
     894</t>
     895<t>
     896   A server &MUST; ignore the If-Unmodified-Since header field if the
     897   received field-value is not a valid HTTP-date.
     898</t>
     899<t>
     900   If the request semantics (method and header fields) allow the request to be
     901   satisfied with a cached response, a cache &SHOULD; evaluate the condition
     902   based on its currently stored set of suitable responses for that request
     903   (see &cache-key;).
     904   If the most suitable response has a <x:ref>Last-Modified</x:ref> date that
     905   is earlier or equal to the date given in If-Unmodified-Since, the
     906   cache &SHOULD; reuse that response to satisfy the request.
     907   If the condition is not met, none of the stored responses is suitable for
     908   reuse in response to this request.
     909</t>
     910<t>
     911   If the request semantics cannot be satisfied with a cached response, the
     912   conditional is only evaluated when received by an origin server.
     913   If the selected representation has not been modified since the time
     914   specified in this field, then the condition is met.
     915</t>
     916<t>
     917   If the condition is met, the origin server &MAY; perform the requested
     918   method.
    882919</t>
    883920<t>
     
    889926   state is already reflected in the current state of the target resource
    890927   (i.e., the change requested by the user agent has already succeeded, but
    891    the user agent might not be aware of that due to the prior response message
    892    being lost or because a compatible change was made by some other user
    893    agent). In the latter case, the origin server &MUST-NOT; send a
    894    <x:ref>204 (No Content)</x:ref> status code unless it can verify that the
    895    request is a duplicate of an immediately prior change made by the same user
    896    agent.
    897 </t>
    898 <t>
    899    A proxy using a cached response as the selected representation
    900    &MUST-NOT; perform the requested method if the condition is not met;
    901    instead, the proxy &MUST; forward the request towards the origin server.
    902 </t>
    903 <t>
    904    A server &MUST; ignore the If-Unmodified-Since header field if the
    905    received value is not a valid HTTP-date.
     928   the user agent might not be aware of that because the prior response message
     929   was lost or a compatible change was made by some other user agent).
     930   In the latter case, the origin server &MUST-NOT; send a validator header
     931   field in the response unless it can verify that the request is a duplicate
     932   of an immediately prior change made by the same user agent.
    906933</t>
    907934</section>
Note: See TracChangeset for help on using the changeset viewer.