Subject: Issue 181, DAV:error

From: Julian Reschke <[email-masked]>
Date: Sun, 12 Mar 2006 13:36:01 +0100

Following up on issue 181 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=181>), which is 
about preconditions/postconditions and the DAV:error element, mainly in 
Section 16.

IMHO, the spec as it is today is really in a bad shape, both from an 
editorial point of view, and regarding correctness/preciseness.

The main issues are:

1) General confusion about whether we're talking about condition codes 
or errors. This is a left-over from early drafts where the RFC3253 was 
borrowed without actually using it's semantics. As a guideline, every 
time the spec says "error code" it's likely to be incorrect, because it 
either should say "status code" (this is the numerical status code 
defined in RFC2616, and "status" != "error") or "condition code" (that's 
what we use for pre/postconditions).

2) Spec organization: there's no structure within Section 16, which 
makes it extremely hard to read, and impossible to directly reference 
pre/postcondition names. Right now, they don't appear in the TOC nor in 
an index (because we don't have one; another issue). See for instance 
<http://tools.ietf.org/html/draft-ietf-webdav-rfc2518bis-14.txt#page-107>).

3) Mostly, the individual condition descriptions do not define a 
precondition or a postcondition, but instead talk about error 
marshalling. This is  inconsistent with the usage in all other specs.

4) Condition descriptions are given with an HTTP status code labeled 
"Used with". Again, this is misleading (a precondition/postcondition is 
independant of a specific status, and in general the status may vary for 
the same condition). Also, the same information is already provided in 
the method definitions; yet another useless repetition of information 
(with the risk t be inconsistent).

5) Providing DTD fragments for error conditions that are EMPTY is just 
distracting; please restrict them to the cases where they actually are 
needed.

Some of these issues have been discussed before on teleconferences, see 
BugZilla issues 220 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=220>), 221 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=221>), 222 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=222>) and 223 
(<http://ietf.cse.ucsc.edu:8080/bugzilla/show_bug.cgi?id=223>), but it 
doesn't seem I've been able to convince the participants of the calls. 
So to those who agree, PLEASE SPEAK UP.

Also see 
<http://greenbytes.de/tech/webdav/draft-reschke-webdav-rfc2518bis-latest.html#rfc.section.16> 
for a proposal how all problems with this section could be resolved.

Below is a set of proposed changes that attempts to address the main 
problems with terminology.

Section 8.7., para. 1:
OLD:

     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 error body 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 error body mechanism is
     covered in Section 16

NEW:

     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 error body 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 error body mechanism is
     covered in Section 16.

Section 9.1.1., para. 2:
OLD:

     403 Forbidden - A server MAY reject PROPFIND requests on collections
     with depth header of "Infinity", in which case it SHOULD use this
     error with the precondition code 'propfind-finite-depth' inside the
     error body.

NEW:

     403 Forbidden (with the condition code 'propfind-finite-depth'
     defined in Section 16) - A server MAY reject PROPFIND requests on
     collections with depth header of "Infinity".

Section 9.2., para. 10:
OLD:

     403 (Forbidden): The client has attempted to set a read-only
     property, such as DAV:getetag.  If returning this error, the server
     SHOULD use the precondition code 'cannot-modify-protected-property'
     inside the response body.

NEW:

     403 (Forbidden) (with the condition code 'cannot-modify-protected-
     property' defined in Section 16) - The client has attempted to set a
     protected property, such as DAV:getetag.

Section 14.5., para. 2:
OLD:

     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 an XML element with the code of a failed
        precondition or postcondition.

NEW:

     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 an XML element with the name of a failed
        precondition or postcondition.

Section 16., para. 1:
OLD:

     As introduced in section Section 8.7, extra information on error
     conditions can be included in the body of many status responses.
     This section makes requirements on the use of the error body
     mechanism and introduces a number of precondition and postcondition
     codes.

NEW:

     As introduced in Section 8.7, extra information on error conditions
     can be included in the body of many status responses.  This section
     makes requirements on the use of the error body mechanism and
     introduces a number of precondition and postcondition codes.

Section 16., para. 3:
OLD:

     Each precondition and postcondition has a unique XML element
     associated with it.  In a 207 Multi-Status response, the XML element
     MUST appear inside an 'error' element in the appropriate 'propstat or
     'response' element depending on whether the condition applies to one
     or more properties or the resource as a whole.  In all other error
     responses, the XML element MUST be returned as the child of a top-
     level 'error' element in the response body, unless otherwise
     negotiated by the request, along with an appropriate response status.
     The most common response status codes are 403 (Forbidden) if the
     request should not be repeated because it will always fail, and 409
     (Conflict) if it is expected that the user might be able to resolve
     the conflict and resubmit the request.  The 'error' element MAY
     contain child elements with specific error information and MAY be
     extended with any custom child elements.

NEW:

     Each precondition and postcondition has a unique XML element
     associated with it.  In a 207 Multi-Status response, the XML element
     MUST appear inside an 'error' element in the appropriate 'propstat or
     'response' element depending on whether the condition applies to one
     or more properties or to the resource as a whole.  In all other error
     responses, the XML element MUST be returned as the child of a top-
     level 'error' element in the response body, unless otherwise
     negotiated by the request, along with an appropriate response status.
     The most common response status codes are 403 (Forbidden) if the
     request should not be repeated because it will always fail, and 409
     (Conflict) if it is expected that the user might be able to resolve
     the conflict and resubmit the request.  The 'error' element MAY
     contain child elements with specific error information and MAY be
     extended with any custom child elements.

Section 16., para. 4:
OLD:

     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, so naturally any group defining a new error code can
     use their own namespace.  As always, the "DAV:" namespace is reserved
     for use by IETF-chartered WebDAV working groups.

NEW:

     This mechanism does not take the place of using a correct numeric
     status 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 status code.  However, it does remove the need to define
     new numeric status codes.  The machine-readable codes used for this
     purpose are XML elements classified as preconditions and
     postconditions, so naturally any group defining a new condition code
     can use their own namespace.  As always, the "DAV:" namespace is
     reserved for use by IETF-chartered WebDAV working groups.

Section 16., para. 5:
OLD:

     A server supporting this specification SHOULD use the XML error
     whenever a precondition or postcondition defined in this document is
     violated.  For error conditions not specified in this document, the
     server MAY simply choose an appropriate numeric status and leave the
     response body blank.  However, a server MAY instead use a custom
     error code and other supporting text, because even when clients do
     not automatically recognize error codes they can be quite useful in
     interoperability testing and debugging.

NEW:

     A server supporting this specification SHOULD use the XML error
     whenever a precondition or postcondition defined in this document is
     violated.  For error conditions not specified in this document, the
     server MAY simply choose an appropriate numeric status and leave the
     response body blank.  However, a server MAY instead use a custom
     condition code and other supporting text, because even when clients
     do not automatically recognize status codes they can be quite useful
     in interoperability testing and debugging.

Section 16., para. 6:
OLD:

     Example - Response with precondition code"
     >>Response

NEW:

     Example - Response with precondition code
     >>Response

Best regards, Julian

---

From: Geoffrey M Clemm <[email-masked]>
Date: Sun, 12 Mar 2006 19:33:39 -0500

I strongly agree with all of Julian's points below.

It was my understanding that the consensus was to adopt the condition
code approach taken by all of the other specs, and so these are
remnants of the alternative "error code" approach that was rejected by 
the working group.

Cheers,
Geoff