Network Working Group C. Daboo
Internet-Draft Apple, Inc.
Intended status: Standards Track A. Quillaud
Expires: September 9, 2010 Sun Microsystems
March 8, 2010
Collection Synchronization for WebDAV
draft-daboo-webdav-sync-03
Abstract
This specification defines an extension to WebDAV that allows
efficient synchronization of the contents of a WebDAV collection.
Editorial Note (To be removed by RFC Editor before publication)
Please send comments to the Distributed Authoring and Versioning
(WebDAV) working group at <mailto:w3c-dist-auth@w3.org>, which may be
joined by sending a message with subject "subscribe" to
<mailto:w3c-dist-auth-request@w3.org>. Discussions of the WEBDAV
working group are archived at
<http://lists.w3.org/Archives/Public/w3c-dist-auth/>.
Status of This Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
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.
This Internet-Draft will expire on September 9, 2010.
Copyright Notice
Daboo & Quillaud Expires September 9, 2010 [Page 1]
Internet-Draft WebDAV Sync March 2010
Copyright (c) 2010 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 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.
Daboo & Quillaud Expires September 9, 2010 [Page 2]
Internet-Draft WebDAV Sync March 2010
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Conventions Used in This Document . . . . . . . . . . . . . . 4
3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5
3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6
3.3. Types of Changes Reported on Initial Synchronization . . . 7
3.4. Types of Changes Reported on Subsequent
Synchronizations . . . . . . . . . . . . . . . . . . . . . 7
3.4.1. Changed Resource . . . . . . . . . . . . . . . . . . . 8
3.4.2. Removed Resource . . . . . . . . . . . . . . . . . . . 8
3.5. Truncation of Results . . . . . . . . . . . . . . . . . . 8
3.6. Limiting Results . . . . . . . . . . . . . . . . . . . . . 9
3.7. Example: Initial DAV:sync-collection Report . . . . . . . 9
3.8. Example: DAV:sync-collection Report with Token . . . . . . 11
3.9. Example: Initial DAV:sync-collection Report with
Truncation . . . . . . . . . . . . . . . . . . . . . . . . 14
3.10. Example: Initial DAV:sync-collection Report with Limit . . 15
3.11. Example: DAV:sync-collection Report with Unsupported
Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 17
5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 18
5.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 18
5.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 19
5.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 19
6. Security Considerations . . . . . . . . . . . . . . . . . . . 19
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19
8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 20
9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20
9.1. Normative References . . . . . . . . . . . . . . . . . . . 20
9.2. Informative References . . . . . . . . . . . . . . . . . . 21
Appendix A. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 21
Daboo & Quillaud Expires September 9, 2010 [Page 3]
Internet-Draft WebDAV Sync March 2010
1. Introduction
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 DAV:getetag property 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 request 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 resources within the collection have changed.
2. Conventions Used in This Document
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:
1. element names use the "DAV:" namespace,
2. element ordering is irrelevant unless explicitly stated,
3. extension elements (elements not already defined as valid child
elements) may be added anywhere, except when explicitly stated
otherwise,
4. extension attributes (attributes not already defined as valid for
this element) may be added anywhere, except when explicitly
stated otherwise.
Daboo & Quillaud Expires September 9, 2010 [Page 4]
Internet-Draft WebDAV Sync March 2010
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].
3. WebDAV Synchronization
3.1. Overview
One way to synchronize data between two entities is to use some form
of synchronization token. The token defines the state of the data
being synchronized at a particular point in time. It can then be
used to determine what has changed since one point in time and
another.
This specification defines a new WebDAV report that is used to enable
client-server collection synchronization based on such a token.
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.
As an alternative, the client may choose to do its first
synchronization using some other mechanism on the collection (e.g.
some other form of batch resource information retrieval such as
PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those
defined in CalDAV [RFC4791] and CardDAV [I-D.ietf-vcarddav-carddav])
and ask for the DAV:sync-token property to be returned. This
property (defined in Section 4) contains the same token that can be
used later on to issue a DAV:sync-collection report.
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
Daboo & Quillaud Expires September 9, 2010 [Page 5]
Internet-Draft WebDAV Sync March 2010
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.
3.2. DAV:sync-collection Report
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.
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. Only internal members of the collection
(as defined in [RFC4918]) are to be considered. 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:
The request URI MUST identify a collection. The request body MUST
be a DAV:sync-collection XML element (see Section 5.1), which MUST
contain one DAV:sync-token XML element, and one DAV:prop XML
element.
The request MUST include a Depth header with a value of "1".
The response body for a successful request MUST be a DAV:
multistatus XML element, which MUST contain one DAV:sync-token
element in addition to one DAV:response element for each resource
that was created, has changed or been deleted since the last
synchronization operation as specified by the DAV:sync-token
provided in the request. A given resource MUST appear only once
Daboo & Quillaud Expires September 9, 2010 [Page 6]
Internet-Draft WebDAV Sync March 2010
in the response.
The content of each DAV:response element differs depending on how
the resource was altered:
For resources that have changed (i.e. are new or have been
modified) the DAV:response MUST contain at least one DAV:
propstat element and MUST NOT contain any DAV:status element.
For resources that have been removed, the DAV:response MUST
contain one DAV:status with a value set to '404 Not Found' and
MUST NOT contain any DAV:propstat element.
The conditions under which each type of change may occur is
further described in Section 3.4.
Preconditions:
(DAV:valid-sync-token): The DAV:sync-token element value MUST map
to a valid token previously returned by the server. A token may
become invalid as the result of being "out of date" (out of the
range of change history maintained by the server), or for other
reasons (e.g. collection deleted, then recreated, ACL changes,
etc...).
Postconditions:
(DAV:number-of-matches-within-limits): The number of changes
reported in the response must fall within the client specified
limit. This condition might be triggered if a client requests a
limit on the number of responses (as per Section 3.6) but the
server is unable to truncate the result set at or below that
limit.
3.3. Types of Changes Reported on Initial Synchronization
When the DAV:sync-collection request does not contain a sync-token,
the server MUST return all internal members of the collection and it
MUST NOT return any removed resource.
3.4. Types of Changes Reported on Subsequent Synchronizations
When the DAV:sync-collection request contains a valid sync-token, two
types of resource state changes can be returned (changed or removed).
This section defines what triggers each of these to be returned. It
also clarifies the case where a resource may have undergone multiple
changes in between two synchronizations.
Daboo & Quillaud Expires September 9, 2010 [Page 7]
Internet-Draft WebDAV Sync March 2010
3.4.1. Changed Resource
A resource MUST be reported as changed if it has been mapped directly
under the target collection since the request sync token was
generated. This includes resources that have been mapped as the
result of a COPY, MOVE or BIND ([I-D.ietf-webdav-bind]) operation.
This also includes collection resources that have been created.
In the case where a mapping between a resource and the target
collection was removed, then a new mapping with the same URI created,
the new resource MUST be reported as changed while the old resource
MUST NOT be reported as removed. For example, if a resource was
deleted, then recreated using the same URI, it should be reported as
a changed resource only.
A resource MUST be reported as changed if its entity tag value
(defined in [RFC2616]) has changed since the request sync token was
generated.
A resource MAY be reported as changed if the user issuing the request
was granted access to this resource, due to access control changes.
Collection resources MUST NOT be returned as changed, except in the
case stated above. Instead clients are expected to synchronize
changes in child collection resources on an individual basis.
3.4.2. Removed Resource
A resource MUST be reported as removed if its mapping under the
target collection has been removed since the request sync token was
generated, and it has not been re-mapped since it was removed. This
includes resources that have been unmapped as the result of a MOVE or
UNBIND ([I-D.ietf-webdav-bind]) operation. This also includes
collection resources that have been removed.
If a resource was created (and possibly modified), then removed in
between two synchronizations, it MUST be reported as removed.
A resource MAY be reported as removed if the user issuing the request
no longer has access to this resource, due to access control changes.
3.5. Truncation of Results
A server MAY limit the number of resources in a response, for
example, to limit the amount of work expended in processing a
request, or as the result of an explicit limit set by the client. If
the result set is truncated, the response MUST use status code 207,
return a DAV:multistatus response body, and indicate a status of 507
Daboo & Quillaud Expires September 9, 2010 [Page 8]
Internet-Draft WebDAV Sync March 2010
(Insufficient Storage) for the request URI. That DAV:response
element SHOULD include a DAV:error element with the DAV:number-of-
matches-within-limits precondition, as defined in [RFC3744] (Section
9.2). DAV:response elements for all the changes being reported are
also included.
When truncation occurs, the DAV:sync-token value returned in the
response MUST represent the correct state for the partial set of
changes returned. That allows the client to use the returned DAV:
sync-token to fetch the next set of changes. In this way the client
can effectively "page" through the entire set of changes in a
consistent manner.
Clients MUST handle the 507 status on the request-URI in the response
to the report.
For example, consider a server that records changes using a
monotonically increasing integer to represent a "revision number" and
uses that quantity as the DAV:sync-token value. Assume the last DAV:
sync-token used by the client was "10", and since then 20 additional
changes have occurred. If the client executes a DAV:sync-collection
request with a DAV:sync-token of "10", without a limit the server
would return 20 DAV:response elements and a DAV:sync-token with value
"30". But if the server choose to limit responses to at most 10
changes, then it would return only 10 DAV:response elements and a
DAV:sync-token with value "20", together with an addition DAV:
response element for the request-URI with a status code of 507.
Subsequently, the client can re-issue the request with the DAV:sync-
token value returned from the server and fetch the remaining 10
changes.
3.6. Limiting Results
A client can limit the number of results returned by the server
through use of the DAV:limit element ([RFC5323], Section 5.17) in the
request body. This is useful when clients have limited space or
bandwidth for the results. If a server is unable to truncate the
result at or below the requested number, then it MUST fail the
request with a DAV:number-of-matches-within-limits post-condition
error. When the results can be correctly limited by the server, the
server MUST follow the rules above for indicating a result set
truncation to the client.
3.7. Example: Initial DAV:sync-collection Report
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. It also asks for the DAV:getetag property and for a
Daboo & Quillaud Expires September 9, 2010 [Page 9]
Internet-Draft WebDAV Sync March 2010
proprietary property. The server responds with the items currently
in the targeted collection. The current synchronization token is
also returned.
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Depth: 1
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 xmlns:R="urn:ns.example.com:boxschema">
<D:getetag/>
<R:bigbox/>
</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:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00001-abcd1"</D:getetag>
<R:bigbox xmlns:R="urn:ns.example.com:boxschema">
<R:BoxType>Box type A</R:BoxType>
</R:bigbox>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
Daboo & Quillaud Expires September 9, 2010 [Page 10]
Internet-Draft WebDAV Sync March 2010
<D:propstat>
<D:prop>
<D:getetag>"00002-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00003-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:sync-token>1234</D:sync-token>
</D:multistatus>
3.8. Example: DAV:sync-collection Report with Token
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.
Daboo & Quillaud Expires September 9, 2010 [Page 11]
Internet-Draft WebDAV Sync March 2010
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Depth: 1
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 xmlns:R="urn:ns.example.com:boxschema">
<D:getetag/>
<R:bigbox/>
</D:prop>
</D:sync-collection>
Daboo & Quillaud Expires September 9, 2010 [Page 12]
Internet-Draft WebDAV Sync March 2010
>> 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:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00004-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00002-abcd2"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
<D:propstat>
<D:prop>
<R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
</D:prop>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:status>HTTP/1.1 404 Not Found</D:status>
</D:response>
<D:sync-token>1238</D:sync-token>
</D:multistatus>
Daboo & Quillaud Expires September 9, 2010 [Page 13]
Internet-Draft WebDAV Sync March 2010
3.9. Example: Initial DAV:sync-collection Report with Truncation
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. It also asks for the DAV:getetag property. The server
responds with the items currently in the targeted collection, but
truncated at two items. The synchronization token for the truncated
result set is returned.
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Depth: 1
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>
Daboo & Quillaud Expires September 9, 2010 [Page 14]
Internet-Draft WebDAV Sync March 2010
>> 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:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00001-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00002-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/</D:href>
<D:status>HTTP/1.1 507 Insufficient Storage</D:status>
</D:response>
<D:sync-token>1233</D:sync-token>
</D:multistatus>
3.10. Example: Initial DAV:sync-collection Report with Limit
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. It requests a limit of 1 for the responses returned by the
server. It also asks for the DAV:getetag property. The server
responds with the items currently in the targeted collection, but
truncated at one item. The synchronization token for the truncated
result set is returned.
Daboo & Quillaud Expires September 9, 2010 [Page 15]
Internet-Draft WebDAV Sync March 2010
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Depth: 1
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:limit>
<D:nresults>1</D:nresults>
</D:limit>
<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:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
<D:propstat>
<D:prop>
<D:getetag>"00001-abcd1"</D:getetag>
</D:prop>
<D:status>HTTP/1.1 200 OK</D:status>
</D:propstat>
</D:response>
<D:response>
<D:href
>http://webdav.example.com/home/cyrusdaboo/</D:href>
<D:status>HTTP/1.1 507 Insufficient Storage</D:status>
</D:response>
<D:sync-token>1232</D:sync-token>
</D:multistatus>
Daboo & Quillaud Expires September 9, 2010 [Page 16]
Internet-Draft WebDAV Sync March 2010
3.11. Example: DAV:sync-collection Report with Unsupported Limit
In this example, the client is making a synchronization request to
the server with a valid DAV:sync-token element value. It requests a
limit of 100 for the responses returned by the server. It also asks
for the DAV:getetag property. The server is unable to limit the
results to the maximum specified by the client, so it responds with a
507 status code and appropriate post-condition error code.
>> Request <<
REPORT /home/cyrusdaboo/ HTTP/1.1
Host: webdav.example.com
Depth: 1
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>1232</D:sync-token>
<D:limit>
<D:nresults>100</D:nresults>
</D:limit>
<D:prop>
<D:getetag/>
</D:prop>
</D:sync-collection>
>> Response <<
HTTP/1.1 507 Insufficient Storage
Content-Type: text/xml; charset="utf-8"
Content-Length: xxxx
<?xml version="1.0" encoding="utf-8" ?>
<D:error xmlns:D="DAV:">
<D:number-of-matches-within-limits/>
</D:error>
4. DAV:sync-token Property
Daboo & Quillaud Expires September 9, 2010 [Page 17]
Internet-Draft WebDAV Sync March 2010
Name: sync-token
Namespace: DAV:
Purpose: Contains the value of the synchronization token as it would
be returned by a DAV:sync-collection report.
Value: Any text.
Protected: MUST be protected because this value is created and
controlled by the server.
COPY/MOVE behavior: This property value is dependent on the final
state of the destination resource, not the value of the property
on the source resource.
Description: The DAV:sync-token property MUST be defined on all
resources that support the DAV:sync-collection report. It
contains the value of the synchronization token as it would be
returned by a DAV:sync-collection report on that resource at the
same point in time. It SHOULD NOT be returned by a PROPFIND DAV:
allprop request (as defined in [RFC4918]).
Definition:
<!ELEMENT sync-token #PCDATA>
5. XML Element Definitions
5.1. DAV:sync-collection XML Element
Name: sync-collection
Namespace: DAV:
Purpose: WebDAV report used to synchronize data between client and
server.
Description: See Section 3.
<!ELEMENT sync-collection (sync-token, DAV:limit?, DAV:prop)>
<!-- DAV:limit defined in RFC 5323, Section 5.17 -->
<!-- DAV:prop defined in RFC 4918, Section 14.18 -->
Daboo & Quillaud Expires September 9, 2010 [Page 18]
Internet-Draft WebDAV Sync March 2010
5.2. DAV:sync-token XML Element
Name: sync-token
Namespace: DAV:
Purpose: The synchronization token provided by the server and
returned by the client.
Description: See Section 3.
<!ELEMENT sync-token CDATA>
5.3. DAV:multistatus XML Element
Name: multistatus
Namespace: DAV:
Purpose: Extends the DAV:multistatus element to include
synchronization details.
Description: See Section 3.
<!ELEMENT multistatus (DAV:response*, DAV:responsedescription?,
sync-token?) >
<!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
but overridden here to add the DAV:sync-token element -->
<!-- DAV:response defined in RFC 4918, Section 14.24 -->
<!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->
6. Security Considerations
This extension does not introduce any new security concerns than
those already described in HTTP and WebDAV.
7. IANA Considerations
This document does not require any actions on the part of IANA.
Daboo & Quillaud Expires September 9, 2010 [Page 19]
Internet-Draft WebDAV Sync March 2010
8. Acknowledgments
The following individuals contributed their ideas and support for
writing this specification: Bernard Desruisseaux, Mike Douglass, Ciny
Joy, Andrew McMillan, Julian Reschke, and Wilfredo Sanchez. We would
like to thank the Calendaring and Scheduling Consortium for
facilitating interoperability testing for early implementations of
this specification.
9. References
9.1. Normative References
[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.
[RFC3744] Clemm, G., Reschke, J., Sedlar, E., and
J. Whitehead, "Web Distributed Authoring
and Versioning (WebDAV)
Access Control Protocol", RFC 3744,
May 2004.
[RFC4918] Dusseault, L., "HTTP Extensions for Web
Distributed Authoring and Versioning
(WebDAV)", RFC 4918, June 2007.
[RFC5323] Reschke, J., Reddy, S., Davis, J., and
A. Babich, "Web Distributed Authoring
and Versioning (WebDAV) SEARCH",
RFC 5323, November 2008.
[W3C.REC-xml-20081126] Maler, E., Yergeau, F., Sperberg-
McQueen, C., Paoli, J., and T. Bray,
"Extensible Markup Language (XML) 1.0
(Fifth Edition)", World Wide Web
Consortium Recommendation REC-xml-
20081126, November 2008, <http://
www.w3.org/TR/2008/REC-xml-20081126>.
Daboo & Quillaud Expires September 9, 2010 [Page 20]
Internet-Draft WebDAV Sync March 2010
9.2. Informative References
[I-D.ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to WebDAV
(CardDAV)",
draft-ietf-vcarddav-carddav-10 (work in
progress), November 2009.
[I-D.ietf-webdav-bind] Clemm, G., Crawford, J., Reschke, J.,
and J. Whitehead, "Binding Extensions to
Web Distributed Authoring and Versioning
(WebDAV)", draft-ietf-webdav-bind-27
(work in progress), December 2009.
[RFC4791] Daboo, C., Desruisseaux, B., and L.
Dusseault, "Calendaring Extensions to
WebDAV (CalDAV)", RFC 4791, March 2007.
Appendix A. Change History (to be removed prior to publication as an
RFC)
Changes in -03:
1. Changed D:propstat to D:prop in marshalling.
2. Added request for dead property in examples.
3. Made D:prop mandatory in request so that D:response always
contains at least one D:propstat as per WebDAV definition.
4. Removed DAV:status from response when resource is created/
modified, thus allowing to get rid of DAV:sync-response in favor
of a regular DAV:response. As a consequence, there is no longer
any difference in the report between created and modified
resources.
5. Resource created, then removed between 2 sync MUST be returned as
removed.
6. Added ability for server to truncate results and indicate such to
the client.
7. Added ability for client to request the server to limit the
result set.
Changes in -02:
1. Added definition of sync-token WebDAV property.
Daboo & Quillaud Expires September 9, 2010 [Page 21]
Internet-Draft WebDAV Sync March 2010
2. Added references to SEARCH, CalDAV, CardDAV as alternative ways
to first synchronize a collection.
3. Added section defining under which condition each state change
(new, modified, removed) should be reported. Added reference to
BIND.
4. Incorporated feedback from Julian Reschke and Ciny Joy.
5. More details on the use of the DAV:valid-sync-token precondition.
Changes in -01:
1. Updated to 4918 reference.
2. Fixed examples to properly include DAV:status in DAV:propstat
3. Switch to using XML conventions text from RFC5323.
Authors' Addresses
Cyrus Daboo
Apple Inc.
1 Infinite Loop
Cupertino, CA 95014
USA
EMail: cyrus@daboo.name
URI: http://www.apple.com/
Arnaud Quillaud
Sun Microsystems
180, Avenue de l'Europe
Saint Ismier cedex, 38334
France
EMail: arnaud.quillaud@sun.com
URI: http://www.sun.com/
Daboo & Quillaud Expires September 9, 2010 [Page 22]
