Subject: [Bug 181] error element

From: [email-masked]
Date: Thu, 22 Dec 2005 15:01:15 -0800

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

------- Additional Comments From [email-masked]  2005-12-22 15:01 -------
OK,

the proposed change affects many individual parts, so I can't include the whole
set of changes here (see
<http://greenbytes.de/tech/webdav/draft-reschke-webdav-rfc2518bis-latest.html#rfc.issue.bz181>
for the complete picture).

Summary:

   Fix description in Section 13.5.  Update descriptions in Section 15.
   Merge stuff from Section 15 into Section 8.1.5 (removing overlaps and
   conflicting text).  Minor changes where conditions are mentioned,
   mainly adding forward references to section Section 15.  See issue
   181 [13].

In particular:

8.1.5  Including error response bodies

   HTTP and WebDAV did not use the bodies of most error responses for
   machine-parsable information until DeltaV introduced a mechanism to
   include more specific information in the body of an error response
   (section 1.6 of [RFC3253]).  The mechanism is appropriate to use with
   any error response that may take a body but does not already have a
   body defined.  The mechanism is particularly appropriate when a
   status code can mean many things (for example, 400 Bad Request can
   mean required headers are missing, headers are incorrectly formatted,
   or much more).

   This mechanism does not take the place of using a correct numeric
   error code as defined here or in HTTP, because the client MUST always
   be able to take a reasonable course of action based only on the
   numeric error.  However, it does remove the need to define new
   numeric error codes.  The machine-readable codes used for this
   purpose are XML elements classified as preconditions and
   postconditions.  As always, the "DAV:" namespace is reserved for use
   by IETF-chartered WebDAV working groups.

   A "precondition" of a method describes the state of the server that
   must be true for that method to be performed.  A "postcondition" of a
   method describes the state of the server that must be true after that
   method has been completed.  If a method precondition or postcondition
   for a request is not satisfied and unless specified explicitly
   otherwise, the response status of the request MUST be either 403
   (Forbidden) if the request should not be repeated because it will
   always fail, or 409 (Conflict) if it is expected that the user might
   be able to resolve the conflict and resubmit the request.

   When a specific condition code is defined, and that condition is not
   satisfied, servers SHOULD return the XML element associated with the
   condition as the child of a top-level DAV:error element
   (Section 13.5) in the response body, unless otherwise negotiated by
   the request.  Servers MAY include multiple XML elements if more than
   one condition could not be satisfied.

   In a 207 Multi-Status response, the DAV:error element would appear in
   the appropriate DAV:responsedescription element.

   In this specification, both the HTTP status code and the condition
   name are defined for some failure situations, in which case the XML
   condition element is in the "DAV:" namespace, appears in the "error"
   root element, and SHOULD be returned in a body with the specified
   numeric HTTP status code.

8.1.5.1  Example - Response with precondition code

   >>Response

     HTTP/1.1 403 Forbidden
     Content-Type: application/xml; charset="utf-8"
     Content-Length: xxxx

     <?xml version="1.0" encoding="utf-8" ?>
     <D:error xmlns:D="DAV:">
       <D:no-external-entities/>
     </D:error>

13.5  error XML Element

   Name:  error

   Purpose:  Error responses, particularly 403 Forbidden and 409
      Conflict, sometimes need more information to indicate what went
      wrong.  When an error response contains a body in WebDAV, the body
      is in XML with the root element 'error'.  The 'error' element
      SHOULD include a an XML element with the name of the failed pre-
      or postcondition.

   Description:  Contains any XML element

   <!ELEMENT error ANY >

15.  Precondition/postcondition XML elements

   Some other useful preconditions and postconditions have been defined
   in other specifications extending WebDAV, such as [RFC3253],
   [RFC3648] and [RFC3744] (see particularly Section 7.1.1).

   If not specified otherwise, the content for each condition's XML
   element is defined to be empty.

15.1  DAV:no-external-entities (precondition)

   If the request body is XML, and the server does not support external
   entities, this condition code can be used to signal the problem (see
   also Section 19.6).

15.2  DAV:lock-token-matches-request-uri (precondition)

   A request may include a Lock-Token header to identify a lock for the
   purposes of an operation such as refresh LOCK or UNLOCK.  However, if
   the Request-URI does not fall within the scope of the lock identified
   by the token, the server SHOULD use this condition code.

15.3  DAV:preserved-live-properties (postcondition)

   Servers may reject MOVE requests, if they cannot maintain live
   properties with the same behaviour at the destination URL.  In this
   case, this postcondition name may be used to signal the failure
   condition. [[q-copy-live-prop: Does this really apply to COPY as
   well???]]

15.4  DAV:cannot-modify-protected-property (precondition)

   An attempt to modify a property that is defined by this document, as
   being protected for that kind of resource, MUST fail (see [RFC3253],
   Section 3.12).

15.5  DAV:propfind-finite-depth (precondition)

   Used to signal that a request was rejected because the server did not
   allow a value of "infinity" for the "Depth" request header.

15.6  DAV:lock-token-present (precondition)

   If a request would modify the content for a locked resource, a dead
   property of a locked resource, a live property that is defined to be
   lockable for a locked resource, or an internal member URI of a locked
   collection, the request MUST fail unless the lock-token for that lock
   is submitted in the request.  An internal member URI of a collection
   is considered to be modified if it is added, removed, or identifies a
   different resource.

          <!ELEMENT lock-token-present (href)* >

   Servers SHOULD insert DAV:href elements for the URLs of each root of
   a lock for which a lock token was needed, unless that URL identifies
   the same resource to that the request was sent.

15.6.1  Example

   In the example below, a client unaware of a "Depth: infinity" lock on
   the parent collection "/workspace/webdav/" attempts to modify the
   collection member "/workspace/webdav/proposal.doc".

   >>Request

          PUT /workspace/webdav/proposal.doc HTTP/1.1
          Host: example.com

   >>Response

          HTTP/1.1 423 Locked
          Content-Type: application/xml; charset="utf-8"
          Content-Length: xxxx

          <?xml version="1.0" encoding="utf-8" ?>
          <D:error xmlns:D="DAV:">
            <D:lock-token-present>
              <D:href>/workspace/webdav/</D:href>
            </D:lock-token-present>
          </D:error>

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