[Bug 161] EVALUATE_ALL_OF_IF_HEADER

http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=161

julian.reschke@greenbytes.de changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|julian.reschke@greenbytes.de|elias@cse.ucsc.edu
             Status|ASSIGNED                    |NEW



------- Additional Comments From julian.reschke@greenbytes.de  2006-02-11 04:24 -------
OK, here's my attempt to describe the If header in a more readable way.

Changes relative to previous versions:

1) Added note that syntax does NOT allow splitting the header across multiple
headers:

-- begin --
   Note that the ABNF for the If header does not allow splitting its
   value across separate instances of the header.  However, the HTTP
   header syntax allows extending values across multiple lines (see
   [RFC2616], Section 4.2).
-- end --

2) Added example for matching function on unmapped URL (as discussed in previous
telecon):   
   
-- begin --
   10.4.4.2.  Example: Matching ETags on unmapped URLs

   Consider a collection "/specs" that does not contain the member
   "/specs/rfc2518.doc".  In this case, the If header

    If: </specs/rfc2518.docs> (["4217"])

   will evaluate to false (the URI isn't mapped, thus the resource
   identified by the URI doesn't have an entity matching the ETag
   "4217").

   On the other hand, an If header of

    If: </specs/rfc2518.docs> (Not ["4217"])

   will consequently evaluate to true.
-- end --
   
Below is the full text version for the section (XML source has been attached to
this issue):
   
   
10.4.  If Header

   The If request header is intended to have similar functionality to
   the If-Match header defined in Section 14.24 of [RFC2616].  However,
   the If header is intended for use with any URI which represents state
   information, referred to as a state token, about a resource as well
   as ETags.  A typical example of a state token is a lock token, and
   lock tokens are the only state tokens defined in this specification.

10.4.1.  Purpose

   The If header has two distinct purposes:

   o  The first purpose is to make a request conditional by supplying a
      series of state lists.  If the state of the resource to which the
      header is applied does not match any of the specified state lists
      then the request MUST fail with a 412 (Precondition Failed)
      status.  On the other hand, if one of the described state lists
      does match the state of the resource then the request may succeed.
      The matching functions for ETags and state tokens are defined in
      Section 10.4.4 below.

   o  Additionally, the mere fact that a state token appears in an If
      header means that is has been "submitted" with the request.  In
      general, this is used to indicate that the client has knowledge of
      that state token.  The meaning of submitting a state token depends
      on its type (for lock tokens, please refer to Section 6).

   Note that these two purposes need to be treated distinctly: a state
   token counts as being submitted independantly of whether the server
   actually has evaluated the state list it appears in, and also
   independantly of whether the condition it expressed was found to be
   true or not.

10.4.2.  Syntax

      If = "If" ":" ( *No-tag-list | 1*Tagged-list )

      No-tag-list = List
      Tagged-list = Resource 1*List

      List = "(" 1*Condition ")"
      Condition = ["Not"] (State-token | "[" entity-tag "]")
      ; entity-tag: see Section 3.11 of [RFC2616]
      ; No LWS allowed between "[", entity-tag and "]"

      State-token = Coded-URL

      Resource = Coded-Reference
      Coded-Reference = "<" Simple-ref ">"
      ; Simple-ref: see Section 8.2
      ; No LWS allowed in Coded-Reference

   The syntax distinguishes between untagged lists ("No-tag-list") and
   tagged lists ("Tagged-list").  Untagged lists apply to the resource
   identified by the Request-URI, while tagged lists apply to the
   resource identified by the preceding Resource "tag".

   A Resource tag applies to all subsequent Lists, up to the next
   Resource tag.

   Note that the two list types can not be mixed within an If header.
   This is not a functional restriction because the No-tag-list syntax
   is just a shorthand notation for a Tagged-list production with a tag
   referring to the Request-URI.

   Each List consists of one or more Conditions.  Each Condition is
   defined in terms of an entity-tag or state-token, potentially negated
   by the prefix "Not".

   Note that the ABNF for the If header does not allow splitting its
   value across separate instances of the header.  However, the HTTP
   header syntax allows extending values across multiple lines (see
   [RFC2616], Section 4.2).

10.4.3.  Evaluation

   A Condition that consists of a single entity-tag or state-token
   evaluates to true if the resource matches the described state (where
   the individual matching functions are define below in
   Section 10.4.4).  Prefixing it with "Not" reverses the result of the
   evaluation (thus, the "Not" applies only to the subsequent entity-tag
   or state-token).

   Each List production describes a series of conditions.  The whole
   list evaluates to true if and only if each condition evaluates to
   true (that is, the list represents a logical conjunction of
   Conditions).

   Each No-tag-list and Tagged-list production may contain one or more
   Lists.  They evaluate to true if and only if any of the contained
   lists evaluates to true (that is, if there's more than one List, that
   List sequence represents a logical disjunction of the Lists).

   Finally, the whole If header evaluates to true if and only if at
   least one of the No-tag-list or Tagged-list productions evaluates to
   true.  If the header evaluates to false, the server MUST reject the
   request with a 412 (Precondition Failed) status.  Otherwise,
   execution of the request can proceed as if the header wasn't present.

10.4.3.1.  Example: No-tag Production

      If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
             ["I am an ETag"])
          (["I am another ETag"])

   The previous header would require that the resource identified in the
   Request-URI be locked with the specified lock token and be in the
   state identified by the "I am an ETag" ETag or in the state
   identified by the second ETag "I am another ETag".

   To put the matter more plainly one can think of the previous If
   header as expressing the condition below:

     (
       is-locked-with(urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2) AND
       matches-etag("I am an ETag")
     )
     OR
     (
       matches-etag("I am another ETag")
     )

10.4.3.2.  Example: using "Not" with No-tag Production

     If: (Not <urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
         <urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092>)

   This If header requires that the resource must not be locked with a
   lock having the lock token
   urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 and must be locked by a
   lock with the lock token with
   urn:uuid:58f202ac-22cf-11d1-b12d-002035b29092.

10.4.3.3.  Example: causing a Condition to always evaluate to True

   There may be cases where a client wishes to submit state tokens, but
   doesn't want the request to fail just because the state token isn't
   current anymore.  One simple way to do this is to include a Condition
   that is known to always evaluate to true, such as in:

     If: (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)
         (Not <DAV:no-lock>)

   "DAV:no-lock" is known to never represent a current lock token, as
   lock tokens are assigned by the server, following the uniqueness
   requirements described in Section 6.5, therefore in particular
   exclude URIs in the "DAV:" scheme.  Thus, by applying "Not" to a
   known not to be current state token, the Condition always evaluates
   to true.  Consequently, the whole If header will always evaluate to
   true, and the lock token
   urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2 will be submitted in
   any case.

10.4.3.4.  Example: Tagged List If header in COPY

   >>Request

   COPY /resource1 HTTP/1.1
   Host: www.example.com
   Destination: /resource2
   If: </resource1>
         (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>
         [W/"A weak ETag"]) (["strong ETag"])
       </random>
         (["another strong ETag"])

   In this example http://www.example.com/resource1 is being copied to
   http://www.example.com/resource2.  When the method is first applied
   to http://www.example.com/resource1, resource1 must be in the state
   specified by "(<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2> [W/"A
   weak ETag"]) (["strong ETag"])", that is, it either must be locked
   with a lock token of "urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2"
   and have a weak entity tag W/"A weak ETag" or it must have a strong
   entity tag "strong ETag".

   That is the only success condition since the resource
   http://www.example.com/random never has the method applied to it (the
   only other resource listed in the If header) and
   http://www.example.com/resource2 is not listed in the If header.

10.4.4.  Matching Function

   When performing If header processing, the definition of a matching
   state token or entity tag is as follows:

   Identifying a resource: The resource is identified by the URI along
   with the token, in tagged list production, or by the Request-URI in
   untagged list production.

   Matching entity tag: Where the entity tag matches an entity tag
   associated with the identified resource.  Servers MUST use either the
   weak or the strong comparison function defined in Section 13.3.3 of
   [RFC2616].

   Matching state token: Where there is an exact match between the state
   token in the If header and any state token on the identified
   resource.  A lock state token is considered to match if the resource
   is anywhere in the scope of the lock.

   Note that for the purpose of matching entity tags and state tokens,
   the URL being unmapped should be treated the same way as if the
   resource existed, but did not have the specified state.

10.4.4.1.  Example: Matching lock tokens with collection locks

     DELETE /specs/rfc2518.txt HTTP/1.1
     Host: www.example.com
     If: <http://www.example.com/specs/>
         (<urn:uuid:181d4fae-7d8c-11d0-a765-00a0c91e6bf2>)

   For this example, the lock token must be compared to the identified
   resource, which is the 'specs' collection identified by the URL in
   the tagged list production.  If the 'specs' collection is not locked
   or has a lock with a different token, the request MUST fail.  If the
   'specs' collection is locked (depth infinity) with that lock token,
   then this request could succeed, both because the If header evaluates
   to true, and because the lock token for the lock affecting the
   affected resource has been submitted.  Alternatively, a request where
   the 'rfc2518.txt' URL is associated with the lock token in the If
   header could also succeed.

10.4.4.2.  Example: Matching ETags on unmapped URLs

   Consider a collection "/specs" that does not contain the member
   "/specs/rfc2518.doc".  In this case, the If header

    If: </specs/rfc2518.docs> (["4217"])

   will evaluate to false (the URI isn't mapped, thus the resource
   identified by the URI doesn't have an entity matching the ETag
   "4217").

   On the other hand, an If header of

    If: </specs/rfc2518.docs> (Not ["4217"])

   will consequently evaluate to true.

10.4.5.  If Header and Non-DAV Aware Proxies

   Non-DAV aware proxies will not honor the If header, since they will
   not understand the If header, and HTTP requires non-understood
   headers to be ignored.  When communicating with HTTP/1.1 proxies, the
   "Cache-Control: no-cache" request header MUST be used so as to
   prevent the proxy from improperly trying to service the request from
   its cache.  When dealing with HTTP/1.0 proxies the "Pragma: no-cache"
   request header MUST be used for the same reason.

10.4.6.  If Header and Authentication

   Servers MUST do authorization checks before checking this header
   (thus, supplying a carefully crafted If header must not allow a
   client to learn information about resources it's not authorized to
   access).




------- You are receiving this mail because: -------
You are the QA contact for the bug, or are watching the QA contact.

Received on Saturday, 11 February 2006 12:24:19 UTC