WebDAV Working Group L. Dusseault Internet Draft Xythos Document: 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 HTTP/1.1 403 Forbidden Error: cannot execute move Dusseault Expires Aug 2000 4 Advanced Status Reporting for WebDAV Jan 2001 http://www.host.com/foo.html HTTP/1.1 403 Forbidden Error: cannot read source resource. http://www.host.com/bar.html HTTP/1.1 412 Precondition Failed Error: Destination resource already exists 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. Dusseault Expires Aug 2000 5 Advanced Status Reporting for WebDAV Jan 2001 http://www.foo.bar/top/container/ HTTP/1.1 409 Conflict Error: The "Copyright-Owner property is protected and may not be set or changed. 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. Host: 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: If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT 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. #?, 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. 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. 7.3 detail-code XML Element Used to contain one of the detail code elements defined in this draft (section 6) or elsewhere. 7.4 user-text XML Element Used for text displayable to the user. Takes the XML "lang" attribute defined in the W3C XML Recommendation. 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. 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. 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