[Docs] [txt|pdf] [Tracker] [WG] [Email] [Nits]
Versions: 00
WebDAV Working Group L. Dusseault
Internet Draft Xythos
Document: <draft-ietf-webdav-status-00.txt> January 2000
Category: Informational
WebDAV -- Advanced Status Reporting
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026 [1].
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts. Internet-Drafts are draft documents valid for a maximum of
six months and may be updated, replaced, or obsoleted by other
documents at any time. It is inappropriate to use Internet- Drafts
as reference material or to cite them other than as "work in
progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
1. Abstract
HTTP 1.1 [2] defines 20 status codes: 100-101, 200-206, 300-305,
400-415, and 500-505. The WebDAV RFC [3] adds six more: 102, 207,
422, 423, 424 and 507. However, WebDAV implementers have found this
to be insufficient. The space of status codes available is limited,
but even if it were not, additional information would often be very
helpful. WebDAV clients frequently need to be able to present
distinct options and helpful information to users, and sometimes
clients might even be able to deal with errors automatically.
Currently, HTTP and WebDAV servers frequently add HTML bodies to
error responses, so that a simple web browser can present the HTML
for the user to read. However, this approach does not allow custom
client UI or automated client operation, and may handle
internationalization poorly.
This Internet-Draft proposes a new header to allow sophisticated or
automated WebDAV clients to request advanced status reporting rather
than the single-code approach available today. This draft also
proposes a simple XML format for the body of the error response.
Finally, this draft proposes a number of "detail codes" expressed as
XML elements, suitable for automatic processing of error conditions.
These detail codes augment the existing response codes.
Dusseault Expires Aug 2000 1
Advanced Status Reporting for WebDAV Jan 2001
This draft does not specify how additional codes are to be defined.
2. Conventions used in this document
In examples, "C:" and "S:" indicate lines sent by the client and
server respectively.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in RFC-2119 [4].
3. Client Request
There are several ways clients can handle the typical HTTP error
response, with or without HTML body. Some clients (i.e. web
browsers) simply present the HTML or text response to the user.
Other clients present a UI (a dialog box, an error message) based on
the status code, ignoring the HTML response if the server sent it.
Finally, there are automated clients that may respond to the error
with further automated action if enough information is present.
This specification addresses the latter two types of clients, and
thus has to solve the problem of how these clients identify
themselves to the server.
3.1 Accept-Error Header
Accept-Error = "Accept-Error" ":" "type=" media-type
The "media-type" field is a type/subtype pair as defined in HTTP 1.1
for the "Accept" header.
Example: "Accept-Error: type=text/xml"
The Accept-Error header MAY be sent on any client request to a
WebDAV server. A server MAY choose to ignore the header. The
header specifies what format the client wishes to receive with the
extra status information. If the header is not present or the
server does not support the format requested by the client, the
server MAY send some default response, e.g. many servers already
return an HTML page with displayable text.
The client MAY choose not to include this header in every request,
since most requests are likely to succeed. The client MAY choose to
resend failed requests, adding at this point the Accept-Error
header. The server MAY cache the client's support for this feature,
although it SHOULD be able to update the cache if the client sends a
new Accept-Error header with a different media type.
This specification only describes two formats that can be requested.
A request for "text/xml" MUST be considered a request for a body
with the DAV:response-detail top-level element and sub-elements
Dusseault Expires Aug 2000 2
Advanced Status Reporting for WebDAV Jan 2001
defined in this specification. A request for "text/html" MAY be
considered a request for a free-form HTML page describing the error,
intended for display to the user (such as some HTTP servers already
create).
3.2 Use of Accept-Language Header
It is recommended that the client include the Accept-Language header
defined for HTTP 1.1. The server MAY respond with human-readable
text, and MAY be able to localize the text.
4. Response Body
The key pieces of information to be returned to the client are at
least one tuple, containing an advanced status code (XML element)
and displayable text string. The server MAY provide status codes
and/or text strings for additional errors pinpointed to specific
resources. This section describes how this information is formatted
into a text/xml body to be returned in the response.
If the client request has the "Accept-Error: text/xml" header, then
the server MAY respond with an appropriate HTTP response code, and
add text/xml body with the elements defined in this specification.
The server MAY return a regular error with no body or with a
text/html body if it chooses to ignore the Accept-Error header.
The server MUST NOT add an error body if the response code does not
allow a body or already has a body defined. HTTP 1.1 forbids
response bodies on 1xx, 204, 205 and 304 responses. The 200
response already has a body defined, and 307 response is supposed to
contain "hypertext". WebDAV defines a body for 207 (however this
specification allows extension of the 207 "multi-status" XML body to
contain status codes defined in this specification [ref later
section]).
HTTP 1.1 encourages response bodies on some errors, e.g. for 409
Conflict it states "The response body SHOULD include enough
information for the user to recognize the source of the conflict".
This specification is intended to go further in defining the
formatting required for automated client software to be able to
recognize the source of the conflict.
This specification defines a response body for the response codes
400, 401, 405, 409, 412, 415, 423 and 500.
The server response MUST have an appropriate HTTP response code,
even if an error body is returned.
The text/xml body of the status response MUST have the DAV:response-
detail top-level element, though it need not be the first or only
top-level element in the XML document. The DAV:response-detail
element MUST contain one or more DAV:status-detail elements, which
Dusseault Expires Aug 2000 3
Advanced Status Reporting for WebDAV Jan 2001
MUST contain one DAV:detail-code element. Each DAV:detail-code
element MUST contain a detail code. This is the minimum useful
response body.
The DAV:response-detail element MAY also contain any number of
DAV:response elements (defined in the WebDAV RFC). These serve to
pinpoint errors to particular resources when more than one resource
is involved, for example when a depth header is present or when a
source and destination resource are specified in the request. The
DAV:response element in this context can contain the DAV:href and
DAV:status elements as it normally does (defined by the WebDAV RFC).
It can also contain two new elements defined here: DAV:detail-code
and DAV:user-text
The DAV:status-detail element MAY contain one or more DAV:user-text
elements with language code specified.
4.1 Using existing status codes
It is expected and recommended that servers continue to use existing
status codes in the body, as well as the first line of the response.
For example, when a MOVE or COPY cannot be executed because the user
does not have sufficient permissions on the destination, a "403
Forbidden" response is quite informative -- as long as the
client/user knows which is forbidden, the source or the destination.
Thus, the DAV:status element is allowed in the DAV:status-detail
element defined here.
4.2 Example request/response
This example has two DAV:response elements to show the status on
both the source and destination resources involved in a MOVE. For
the overall status information in the DAV:status-detail element, the
server arbitrarily chose to present the 403 Forbidden response. It
could equally well have chosen the DAV:destination-resource-exists
status code.
C: MOVE http://www.host.com/foo.html HTTP/1.1
Host: www.host.com
Destination: http://www.host.com/bar.html
Overwrite: F
Accept-Language: En
S: HTTP/1.1 403 Forbidden
Content-Type: text/xml
Content-Length: xxx
<?xml version="1.0"?>
<D:response-detail xmlns:D="DAV:">
<D:status-detail>
<D:status>HTTP/1.1 403 Forbidden</D:status>
<D:user-text xml:lang="en">Error: cannot execute move
Dusseault Expires Aug 2000 4
Advanced Status Reporting for WebDAV Jan 2001
</D:user-text>
</D:status-detail>
<D:response>
<D:href>http://www.host.com/foo.html</D:href>
<D:status>HTTP/1.1 403 Forbidden</D:status>
<D:user-text xml:lang="en">Error: cannot read source
resource.</D:user-text>
</D:response>
<D:response>
<D:href>http://www.host.com/bar.html</D:href>
<D:status>HTTP/1.1 412 Precondition Failed</D:status>
<D:detail-code><D:destination-resource-exists/>
</D:detail-code>
<D:user-text xml:lang="en">Error: Destination resource
already exists</D:user-text>
</D:response>
</D:response-detail>
5. Extending 207 Multistatus body
WebDAV already defines a text/xml body for the 207 Multistatus
response, containing one XML DAV:response element for each resource
being reported on. The DAV:propstat element indicates that the
status being given is for a property of the resource. The existing
schema is extended by allowing both the existing DAV:response and
the existing DAV:propstat elements to contain the new DAV:status-
detail. If the error information is inside a DAV:propstat element
it should be clear the error refers to the property; otherwise it
refers to the resource. The DAV:status-detail element can contain
DAV:detail-code and/or DAV:user-text (DAV:status must already be in
the DAV:propstat element).
The server MAY choose to always augment a 207 Multistatus body with
this extra information. The server MAY choose to add this
information only if the client indicates support for the feature.
The server MUST return all elements already required by the WebDAV
RFC.
5.1 Example Multistatus Body with Detail Codes
This is an example of a 207 Multistatus response body with the
simple addition of the DAV:status-detail element within the
DAV:propstat element. The user requested to PROPPATCH a single
property on a single resource.
<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:"
xmlns:Z="http://www.w3.com/standards/z39.50">
<D:response>
Dusseault Expires Aug 2000 5
Advanced Status Reporting for WebDAV Jan 2001
<D:href>http://www.foo.bar/top/container/</D:href>
<D:propstat>
<D:prop><Z:Copyright-Owner/></D:prop>
<D:status>HTTP/1.1 409 Conflict</D:status>
<D:status-detail>
<D:detail-code><D: property-protected></D:detail-code>
<D:user-text xml:lang="En">Error: The "Copyright-Owner
property is protected and may not be set or changed.
</D:user-text>
</D:status-detail>
</D:propstat>
</D:response>
</D:multistatus>
6. Detail Codes
All codes defined in this section are XML elements in the DAV:
namespace. Since the server must usually present a response code as
well (in the DAV:status element within DAV:propstat, or in the
response header line), this specification suggests an appropriate
code to use.
6.1 ancestor-does-not-exist
Suggested response code: 409 Conflict
Used when a resource is being created (method might be MOVE, COPY,
PUT or MKCOL) when not all ancestors of the destination resource
exist.
6.2 authentication-insufficient
Suggested response code: 401 Unauthorized
Used when the client is currently authenticated, but would need
different permissions in order to succeed in the request. Do not
use this status code when the request would be forbidden no matter
how the user is able to authenticate (use 403 Forbidden instead).
6.3 authentication-required
Suggested response code: 401 Unauthorized
Used when the client is NOT currently authenticated and therefore
the server forbids the request. Do not use this status code when
the request would be forbidden no matter how the user is able to
authenticate, or when the user is already authenticated (use 403
Forbidden instead).
This is analogous to a "authentication timed out" or "logout" status
message from the server, however it does not require the server to
Dusseault Expires Aug 2000 6
Advanced Status Reporting for WebDAV Jan 2001
maintain a list of clients that were authenticated at one point in
order to differentiate from clients that never have authenticated.
6.4 child-is-locked
Suggested response code: 423 Locked
Used when a request cannot be carried out because some child
resource of the source or destination resource was locked. For
example, a MOVE request with a depth header of "infinity" may not be
performed if some child resource is already locked and a lock token
was not provided.
6.5 body-encoding-not-supported
Suggested response code: 400 Bad Request
Used when the request body is encoded in a format that the server
does not support.
6.6 body-missing
Suggested response code: 400 Bad Request
Used when a body is required for the request method, but none was
provided in the request.
6.7 body-not-supported-on-method
Suggested response code: 415 Unsupported Media Type
Used when a body is NOT accepted for the request method used,
however the client sent one anyway. The WebDAV RFC suggests the
"415 Unsupported Media Type" response when the client sends a body
with a MKCOL request. This new code differentiates the MKCOL case
from the case where the server doesn't support the media type under
any circumstances.
6.8 depth-not-supported
Suggested response code: 500 Internal Server Error
Used when a depth of "1" or "infinity" was requested but is not
allowed on this kind of request. E.g. some servers may choose not
to support depth-infinity PROPFIND requests. Most servers do not
support depth 1 or infinity MKCOL requests.
6.9 destination-resource-exists
Suggested response code: 412 Precondition Failed
Dusseault Expires Aug 2000 7
Advanced Status Reporting for WebDAV Jan 2001
Used when a client did not provide an "Overwrite:True" header when
doing a MOVE or COPY; when the destination already exists, the
request must be failed.
6.10 header-missing
Suggested response code: 400 Bad Request
Used when a required header is missing, such as the content-length
or host header. This element contains the name of the missing
header. E.g.
<D:missing-header>Host:</D:missing-header>
6.11 header-syntax-error
Suggested response code: 400 Bad Request
Used when a header cannot be parsed correctly. E.g. content-length
containing a string rather than an integer. This element contains
the name of the problematic header (see header-missing).
6.12 header-value-error
Suggested response code: 400 Bad Request
Used when a header is parsable but the value is out-of-bounds or
incorrect. E.g. content-length value which exceeds the length of
the body received, or depth header value of '1' or 'infinity' when
the resource is not a collection. This element contains the name of
the problematic header (see header-missing).
6.13 precondition-failed
Suggested response code: 412 Precondition Failed
Used when a precondition failed to specify which precondition
failed. The header and precondition are included inside the
element. E.g:
<D:precondition-failed>If-Modified-Since: Sat, 29 Oct 1994 19:43:31
GMT</D:precondition-failed>
6.14 property-protected
Suggested response code: 409 Conflict
Used when a property is protected by the server and may never be
changed by a WebDAV request regardless of permissions.
6.15 resource-not-locked
Suggested response code: 405 Method Not Allowed
Dusseault Expires Aug 2000 8
Advanced Status Reporting for WebDAV Jan 2001
Used when an UNLOCK cannot be performed because the resource is not
locked.
6.16 resource-unlockable
Suggested response code: 405 Method Not Allowed
Used when a LOCK cannot be granted because the resource cannot be
locked (this may occur when the resource is not an ordinary
resource, but something still URL-addressable servlet, the root
directory, or a script). If a LOCK is requested on a resource but
it is a child of the resource that cannot be locked, the server must
specify which child in a DAV:response element.
6.17 url-contains-invalid-characters
Suggested response code: 400 Bad Request
Used when the target URL has characters not supported on the server,
e.g. on PUT or MKCOL, so the resource cannot be created. The
element SHOULD contain a list of invalid characters, e.g.
<D:url-contains-invalid-characters>#?,</D:url-contains-invalid-
characters>
6.18 xml-not-well-formed
Suggested response code: 400 Bad Request
Used only when the XML body of the request is not well-formed, as
defined for XML 1.0 [5] in section 2.l.
6.19 xml-syntax-error
Suggested response code: 400 Bad Request
Used when the XML body of the request is well-formed but has some
other error. E.g. if a PROPFIND request has both DAV:allprop and
DAV:propname in the body.
7. XML Element Definitions
DAV:status and DAV:href are used in this specification, and are
unchanged in definition from RFC2518.
All elements defined in this draft are in the "DAV:" namespace.
7.1 response-detail XML Element
Used as a top-level XML Element for most status responses with
bodies, except 207 Multistatus. This is the container element for
Dusseault Expires Aug 2000 9
Advanced Status Reporting for WebDAV Jan 2001
the detailed status information produced by the server, including
overall status and status on specific resources. It MUST contain a
status-detail element and zero or more response elements.
<!ELEMENT response-detail (status-detail, response*) >
7.2 status-detail XML Element
Used to contain detailed status information for a resource, a
property, or an entire response. It MUST contain either status or
detail-code.
<!ELEMENT status-detail (status?, detail-code?, user-text?) >
7.3 detail-code XML Element
Used to contain one of the detail code elements defined in this
draft (section 6) or elsewhere.
<!ELEMENT detail-code ANY>
7.4 user-text XML Element
Used for text displayable to the user. Takes the XML "lang"
attribute defined in the W3C XML Recommendation.
<!ELEMENT user-text (#PCDATA)>
7.5 response XML Element Extended
The WebDAV RFC defines this element for use in 207 Multistatus
bodies. This specification extends the usage and children of the
response element for a new context.
<!ELEMENT response
( href,
((href*, status) | propstat+ | (detail-code, user-text),
responsedescription?
)>
7.6 propstat XML Element Extended
The WebDAV RFC defines this element for use in 207 Multistatus
bodies. This specification extends the usage and children of the
propstat element in the same context.
<!ELEMENT propstat (prop, status, responsedescription?, detail-code?
user-text?>
8. Security Considerations
This draft does not substantially alter the security considerations
outlined in WebDAV (RFC 2518).
Dusseault Expires Aug 2000 10
Advanced Status Reporting for WebDAV Jan 2001
Returning error information can only make security worse if the
server chooses to return secure information in the error response.
Implementers should be wary of returning sensitive information such
as the names of hidden resources.
9. References
1 Bradner, S., "The Internet Standards Process -- Revision 3", BCP
9, RFC 2026, October 1996.
2 Fielding, R., J. Gettys, J. Mogul, H. Frystyk, T. Berners-Lee,
ôHypertext Transfer Protocol û HTTP/1.1ö, RFC 2616, January 1997.
3 Goland, Y., E. Whitehead, A. Faizi, S. Carter, D. Jensen, "HTTP
Extensions for Distributed Authoring -- WebDAV", RFC 2518,
February 1999.
4 Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997
5 Bray, T., J. Paoli, C. M. Sperberg-McQueen, E. Maler, "Extensible
Markup Language (XML) 1.0" W3C Recommendation,
http://www.w3.org/TR/2000/REC-xml-20001006
10. Acknowledgments
Thanks to Sean Lyndersay, John Stracke, and Roy Fielding for
substantial suggestions.
11. Author's Addresses
Lisa Dusseault
Xythos Software Inc
1582 Gordon Street
Redwood City, CA 94061
Email: lisa@Xythos.com
Dusseault Expires Aug 2000 11
Advanced Status Reporting for WebDAV Jan 2001
Full Copyright Statement
"Copyright (C) The Internet Society (date). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implmentation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into
Dusseault Expires Aug 2000 12
Html markup produced by rfcmarkup 1.129d, available from
https://tools.ietf.org/tools/rfcmarkup/