| Network Working Group | C. Daboo |
| Internet-Draft | Apple, Inc. |
| Intended status: Standards Track | January 27, 2012 |
| Expires: July 28, 2012 |
Collection Synchronization for WebDAV
draft-daboo-webdav-sync-01
This specification defines an extension to WebDAV that allows efficient synchronization of the contents of a WebDAV collection.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/.
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."
This Internet-Draft will expire on July 28, 2012.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English.
WebDAV [RFC4918] defines the concept of 'collections' which are hierarchical groupings of WebDAV resources on an HTTP [RFC2616] server. Collections can be of arbitrary size and depth (i.e., collections within collections). WebDAV clients that cache resource content need a way to synchronize that data with the server (i.e., detect what has changed and update their cache). This can currently be done using a WebDAV PROPFIND request on a collection to list all members of a collection along with their HTTP ETag values, which allows the client to determine which resources were changed, added or deleted. However this does not scale well to large collections as the XML response to the PROPFIND response will grow with the collection size.
This specification defines a new WebDAV REPORT that results in the server returning to the client only information about those resources which have changed, are new or were deleted since a previous execution of the REPORT on the collection.
Additionally, a new property is added to collection resources that is used to convey a "synchronization token" that is guaranteed to change when the contents of the collection have changed.
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 [RFC2119].
This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 3.2) as a purely notational convention. WebDAV request and response bodies cannot be validated by a DTD due to the specific extensibility rules defined in Section 17 of [RFC4918] and due to the fact that all XML elements defined by this specification use the XML namespace name "DAV:". In particular:
When an XML element type in the "DAV:" namespace is referenced in this document outside of the context of an XML fragment, the string "DAV:" will be prefixed to the element type.
This document inherits, and sometimes extends, DTD productions from Section 14 of [RFC4918].
One way to synchronize data between two entities is to use some form of synchronization token. This defines the state of the data being synchronized at a particular point in time. That token can then be used to determine what has changed since one point in time and another.
HTTP already defines a synchronization token in the form of an entity tag which is attached to a resource. However, the entity tag is not always required to be 'strong' and thus cannot be relied on absolutely as a valid synchronization indicator. In addition, there is no concept of an entity tag for a collection's contents.
The is specification defines a new WebDAV REPORT that is used to enable client-server collection synchronization.
In order to synchronize the contents of a collection between a server and client, the server provides the client with a synchronization token each time the synchronization REPORT is executed. That token represents the state of the data being synchronized at that point in time. The client can then present that same token back to the server at some later time and the server will return only those items that are new, have changed or were deleted since that token was generated. The server also returns a new token representing the new state at the time the REPORT was run.
Typically the first time a client connects to the server it will need to be informed of the entire state of the collection (i.e., a full list of all resources that are currently contained in the collection). That is done by the client sending an empty token value to the server. This indicates to the server that a full listing is required.
In some cases a server may only wish to maintain a limited amount of history about changes to a collection. In that situation it will return an error to the client when the client presents a token that is "out of date". At that point the client has to fall back to synchronizing the entire collection by re-running the report request using an empty token value.
This specification defines the DAV:sync-collection REPORT.
If this REPORT is implemented by a WebDAV server, then the server MUST list the REPORT in the "DAV:supported-report-set" property on any collection supporting synchronization. If the report is not available, clients MUST NOT attempt to execute one.
To implement the behavior for this REPORT a server needs to keep track of changes to any resources in a collection. This includes noting the addition of new resources, changes to existing resources and removal of resources (where "removal" could be the result of a DELETE or MOVE WebDAV request). The server will track each change and provide a synchronization "token" to the client that describes the state of the server at a specific point in time. This "token" is returned as part of the response to the "sync-collection" report. Clients include the last token they got from the server in the next "sync-collection" report that they execute and the server provides the changes from the previous state represented by the token to the current state, represented by the new token returned.
The synchronization token itself is an "opaque" string - i.e., the actual string data has no specific meaning or syntax. A simple implementation of such a token would be a numeric counter that counts each change as it occurs and relates that change to the specific object that changed.
Marshalling:
Preconditions:
Postconditions:
In this example, the client is making its first synchronization request to the server, so the DAV:sync-token element in the request is empty, and it also asks for the DAV:getetag property. The server responds with the items currently in the targeted collection (indicating that they are 'new' via the '201 Created' status code). The current synchronization token is also returned.
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:">
<D:sync-token/>
<D:prop>
<D:getetag/>
</D:prop>
</D:sync-collection>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
<D:getetag>"00001-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:sync-response>
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
<D:getetag>"00002-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:sync-response>
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
<D:getetag>"00003-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:sync-response>
<D:sync-token>1234</D:sync-token>
</D:multistatus>
In this example, the client is making a synchronization request to the server and is using the DAV:sync-token element returned from the last report it ran on this collection. The server responds listing the items that have been added, changed or removed. The (new) current synchronization token is also returned.
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:sync-collection xmlns:D="DAV:">
<D:sync-token>1234</D:sync-token>
<D:prop>
<D:getetag/>
</D:prop>
</D:sync-collection>
>> Response <<
HTTP/1.1 207 Multi-Status
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:multistatus xmlns:D="DAV:">
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
<D:status>HTTP/1.1 201 Created</D:status>
<D:propstat>
<D:prop>
<D:getetag>"00004-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:sync-response>
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
<D:status>HTTP/1.1 200 OK</D:status>
<D:propstat>
<D:prop>
<D:getetag>"00002-abcd2"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:sync-response>
<D:sync-response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:sync-response>
<D:sync-token>1238</D:sync-token>
</D:multistatus>
<!ELEMENT sync-collection (sync-token, DAV:prop?)>
<!ELEMENT sync-token CDATA>
<!ELEMENT multistatus ((DAV:response*, DAV:responsedescription?) |
(DAV:sync-response*, DAV:sync-token,
DAV:responsedescription?))>
<!ELEMENT sync-response (DAV:href, DAV:status, DAV:propstat?)>
This extension does not introduce any new security concerns than those already described in HTTP and WebDAV.
This document does not require any actions on the part of IANA.
The following individuals contributed their ideas and support for writing this specification: Bernard Desruisseaux, Mike Douglass, Arnaud Quillaud, and Julian Reschke.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [RFC4918] | Dusseault, L., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, June 2007. |
| [W3C.REC-xml-20081126] | Bray, T., Yergeau, F., Sperberg-McQueen, C., Maler, E. and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008. |
Changes in -01: