- From: Julian Reschke <julian.reschke@gmx.de>
- Date: Sun, 12 Mar 2006 13:36:01 +0100
- To: WebDAV <w3c-dist-auth@w3.org>
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
Received on Sunday, 12 March 2006 12:37:17 UTC