Collection Synchronization for WebDAVApple Inc.1 Infinite LoopCupertinoCA95014USAcyrus@daboo.namehttp://www.apple.com/Oracle Corporation180, Avenue de l'EuropeSaint Ismier cedex38334Francearnaud.quillaud@oracle.comhttp://www.oracle.com/
Applications
This specification defines an extension to WebDAV that allows efficient synchronization of the contents of a WebDAV collection.
Please send comments to the
Distributed Authoring and Versioning (WebDAV) working group at , which may be joined by sending a message with subject
"subscribe" to .
Discussions of the WEBDAV working group are archived at
.
WebDAV defines the concept of 'collections' which are hierarchical groupings of WebDAV resources on an
HTTP 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.
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 .
This document uses XML DTD fragments (, 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:
element names use the "DAV:" namespace,element ordering is irrelevant unless explicitly stated,extension elements (elements not already defined as valid child elements) may be added anywhere, except when explicitly stated otherwise,extension attributes (attributes not already defined as valid for this element) may be added anywhere, except when explicitly stated otherwise.
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 .
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 might 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 , or specialized REPORTs such as those defined in
CalDAV and CardDAV ) and ask for the DAV:sync-token property to be returned.
This property (defined in ) contains the same token that can
be used later on to issue a DAV:sync-collection report.
In some cases a server might 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.
If the DAV:sync-collection 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 member resources in a collection (as defined in Section 3 of ).
This includes noting the addition of new resources, changes to existing resources and removal of resources.
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.
For example, a simple implementation of such a token could 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
), which MUST contain one DAV:sync-token XML element, and one DAV:prop XML element, and MAY contain a DAV:limit XML element.
The request MUST include a Depth header with a value of "1" or "infinity".
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 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.
For child collection resources that are unable to support the DAV:sync-collection report, the DAV:response MUST contain one DAV:status with a value set to '405 Method Not Allowed' and MUST NOT contain any DAV:propstat element.
The conditions under which each type of change can occur is further described in .
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, access control 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 ) but the server is unable to truncate the result set at or below that limit.
The DAV:sync-collection report supports both Depth:1 and Depth:infinity request headers.
When the client specifies Depth:1, only additions, changes or removals of immediate children of the collection specified as the request URI are reported.When the client specifies Depth:infinity, additions, changes or removals of any child resource of the collection specified as the request URI are reported, provided child collections themselves also support the DAV:sync-collection report.DAV:sync-token values returned by the server are not specific to the value of the Depth header used in the request. As such clients MAY use a DAV:sync-token value from a request with one Depth value for a similar request with a different Depth value, however the utility of this is limited.
Note that when a server supports Depth:infinity reports, it might not be possible to synchronize some child collections within the collection targeted by the report. In such cases the server is REQUIRED to return a DAV:response with status '405 Method Not Allowed' to inform the client that alternative methods have to be used to synchronize the contents of those collections. The 405 response MUST be sent once, when the collection is first reported to the client.
When the DAV:sync-collection request contains an empty DAV:sync-token element, the server MUST return
all members of the collection (taking account of Depth header requirements as per , and optional truncation of results set as per ) and it MUST NOT return any removed resources. All types of resource (collection or non-collection) MUST be reported.
When the DAV:sync-collection request contains a valid value for the DAV:sync-token element, 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 between two synchronization report requests. In all cases, the Depth header requirements as per , and optional truncation of results set as per , are taken into account by the server.
A resource MUST be reported as changed if it has been mapped as an member of 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 request. All types of resource (collection or non-collection) MUST be reported.
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 Section 3.11 of ) 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 be returned as changed if they have an entity tag associated with them and that entity tag changes. There is no guarantee that changes to members of a collection will result in a change in any entity tag of that collection, so clients cannot rely on a series of Depth:1 reports at multiple levels to track all changes within a collection. Instead Depth:infinity has to be used.
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 operation.
This also includes collection resources that have been removed, including ones that themselves do not support the DAV:sync-collection report.
If a resource was created (and possibly modified), then removed between two synchronization report requests,
it MUST be reported as removed. This ensures that a client that creates a resource is informed of the removal of the resource, if the removal occurs before the client has had a chance to request a synchronization report.
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.
For a Depth:infinity report where a collection is removed, the server MUST NOT report the removal of any resources that are members of the removed collection. Clients MUST assume that if a collection is reported as being removed, then all internal members of that collection have also been removed.
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 (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 (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 15 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 15 DAV:response elements and a DAV:sync-token with value "25". 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 5 changes.
A client can limit the number of results returned by the server through use of the DAV:limit element (, 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.
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 proprietary property.
The server responds with the items currently in the targeted collection. The current synchronization token is also returned.
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.
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.
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.
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.
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 is using Depth:infinity. It also asks for the DAV:getetag property and for a proprietary property.
The server responds with the items currently in the targeted collection. The current synchronization token is also returned.
The collection /home/cyrusdaboo/collection1/ exists and has one child resource which is also reported. The collection /home/cyrusdaboo/collection2/ exists but has no child resources. The collection /home/cyrusdaboo/shared/ is returned with a 405 status indicating that a collection exists but it is unable to report on changes within it in the scope of the current Depth:infinity report. Instead the client can try a DAV:sync-collection report directly on the collection URI.
sync-token
DAV:
Contains the value of the synchronization token as it would be returned by a DAV:sync-collection report.
Any text.
MUST be protected because this value is created and controlled by the server.
This property value is dependent on the final state of the destination resource, not the value of the property on the source resource.
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 Section 14.2 of ).
sync-collection
DAV:
WebDAV report used to synchronize data between client and server.
See .
sync-token
DAV:
The synchronization token provided by the server and returned by the client.
See .
multistatus
DAV:
Extends the DAV:multistatus element to include synchronization details.
See .
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,
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.
Key words for use in RFCs to Indicate Requirement LevelsHarvard University1350 Mass. Ave.CambridgeMA 02138- +1 617 495 3864sob@harvard.edu
General
keyword
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their 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
RFC 2119.
Note that the force of these words is modified by the requirement
level of the document in which they are used.
Hypertext Transfer Protocol -- HTTP/1.1Department of Information and Computer ScienceUniversity of California, IrvineIrvineCA92697-3425+1(949)824-1715fielding@ics.uci.eduWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682jg@w3.orgCompaq Computer CorporationWestern Research Laboratory250 University AvenuePalo AltoCA94305mogul@wrl.dec.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682frystyk@w3.orgXerox CorporationMIT Laboratory for Computer Science, NE43-3563333 Coyote Hill RoadPalo AltoCA94034masinter@parc.xerox.comMicrosoft Corporation1 Microsoft WayRedmondWA98052paulle@microsoft.comWorld Wide Web ConsortiumMIT Laboratory for Computer Science, NE43-356545 Technology SquareCambridgeMA02139+1(617)258-8682timbl@w3.org
The Hypertext Transfer Protocol (HTTP) is an application-level
protocol for distributed, collaborative, hypermedia information
systems. It is a generic, stateless, protocol which can be used for
many tasks beyond its use for hypertext, such as name servers and
distributed object management systems, through extension of its
request methods, error codes and headers . A feature of HTTP is
the typing and negotiation of data representation, allowing systems
to be built independently of the data being transferred.
HTTP has been in use by the World-Wide Web global information
initiative since 1990. This specification defines the protocol
referred to as "HTTP/1.1", and is an update to RFC 2068 .
Web Distributed Authoring and Versioning (WebDAV) Access Control ProtocolIBM20 Maguire RoadLexingtonMA02421geoffrey.clemm@us.ibm.comgreenbytes GmbHSalzmannstrasse 152MuensterNW48159Germanyjulian.reschke@greenbytes.deOracle Corporation500 Oracle ParkwayRedwood ShoresCA94065eric.sedlar@oracle.comU.C. Santa Cruz, Dept. of Computer Science1156 High StreetSanta CruzCA95064ejw@cse.ucsc.edu
This document specifies a set of methods, headers, message bodies,
properties, and reports that define Access Control extensions to the
WebDAV Distributed Authoring Protocol. This protocol permits a client to
read and modify access control lists that instruct a server whether to
allow or deny operations upon a resource (such as HyperText Transfer
Protocol (HTTP) method invocations) by a given principal. A lightweight
representation of principals as Web resources supports integration of a
wide range of user management repositories. Search operations allow
discovery and manipulation of principals using human names.
HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)Web Distributed Authoring and Versioning (WebDAV) consists of a set of methods, headers, and content-types ancillary to HTTP/1.1 for the management of resource properties, creation and management of resource collections, URL namespace manipulation, and resource locking (collision avoidance).</t><t> RFC 2518 was published in February 1999, and this specification obsoletes RFC 2518 with minor revisions mostly due to interoperability experience. [STANDARDS TRACK]Web Distributed Authoring and Versioning (WebDAV) SEARCHThis document specifies a set of methods, headers, and properties composing Web Distributed Authoring and Versioning (WebDAV) SEARCH, an application of the HTTP/1.1 protocol to efficiently search for DAV resources based upon a set of client-supplied criteria. [STANDARDS-TRACK]Extensible Markup Language (XML) 1.0 (Fifth Edition)Calendaring Extensions to WebDAV (CalDAV)Apple Inc.1 Infinite LoopCupertinoCA95014USAcyrus@daboo.namehttp://www.apple.com/Oracle Corporation600 Blvd. de Maisonneuve WestSuite 1900MontrealQCH3A 3J2CANADAbernard.desruisseaux@oracle.comhttp://www.oracle.com/CommerceNet169 University Ave.Palo AltoCA94301USAldusseault@commerce.nethttp://commerce.net/
Applications
calschedcalschcaldavcalendarcalendaringschedulingwebdaviCaliCalendariTIPtext/calendarHTTP
This document defines extensions to the Web Distributed Authoring
and Versioning (WebDAV) protocol to specify a standard way of
accessing, managing, and sharing calendaring and scheduling
information based on the iCalendar format. This document
defines the "calendar-access" feature of CalDAV.
Binding Extensions to Web Distributed Authoring and Versioning (WebDAV)This specification defines bindings, and the BIND method for creating multiple bindings to the same resource. Creating a new binding to a resource causes at least one new URI to be mapped to that resource. Servers are required to ensure the integrity of any bindings that they allow to be created. This document defines an Experimental Protocol for the Internet community.vCard Extensions to WebDAV (CardDAV)This document defines extensions to the Web Distributed Authoring and Versioning (WebDAV) protocol to specify a standard way of accessing, managing, and sharing contact information based on the vCard format.Changes in -04:
Depth:infinity support added.Collection resources are now reported as changed if they have a valid entity tag associated with them.Changes in -03:
Changed D:propstat to D:prop in marshalling.Added request for dead property in examples.Made D:prop mandatory in request so that D:response always contains at least one D:propstat
as per WebDAV definition.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.Resource created, then removed between 2 sync MUST be returned as removed.Added ability for server to truncate results and indicate such to the client.Added ability for client to request the server to limit the result set.Changes in -02:
Added definition of sync-token WebDAV property.Added references to SEARCH, CalDAV, CardDAV as alternative ways to first synchronize a collection.Added section defining under which condition each state change (new, modified, removed) should be reported. Added reference to BIND.Incorporated feedback from Julian Reschke and Ciny Joy.More details on the use of the DAV:valid-sync-token precondition.Changes in -01:
Updated to 4918 reference.Fixed examples to properly include DAV:status in DAV:propstatSwitch to using XML conventions text from RFC5323.