[CalendarServer-changes] [9182] CalendarServer/trunk/doc/RFC
source_changes at macosforge.org
source_changes at macosforge.org
Tue Apr 24 18:40:27 PDT 2012
Revision: 9182
http://trac.macosforge.org/projects/calendarserver/changeset/9182
Author: cdaboo at apple.com
Date: 2012-04-24 18:40:25 -0700 (Tue, 24 Apr 2012)
Log Message:
-----------
WebDAV Sync published as RFC.
Added Paths:
-----------
CalendarServer/trunk/doc/RFC/rfc6578-WebDAV Sync.txt
Removed Paths:
-------------
CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt
Deleted: CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt 2012-04-24 23:20:12 UTC (rev 9181)
+++ CalendarServer/trunk/doc/RFC/draft-daboo-webdav-sync.txt 2012-04-25 01:40:25 UTC (rev 9182)
@@ -1,1624 +0,0 @@
-
-
-
-Network Working Group C. Daboo
-Internet-Draft Apple, Inc.
-Intended status: Standards Track A. Quillaud
-Expires: January 12, 2012 Oracle
- July 11, 2011
-
-
- Collection Synchronization for WebDAV
- draft-daboo-webdav-sync-06
-
-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 at w3.org>, which may be
- joined by sending a message with subject "subscribe" to
- <mailto:w3c-dist-auth-request at 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 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 January 12, 2012.
-
-Copyright Notice
-
- Copyright (c) 2011 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
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 1]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- (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.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 2]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-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. Depth behavior . . . . . . . . . . . . . . . . . . . . . . 8
- 3.4. Types of Changes Reported on Initial Synchronization . . . 9
- 3.5. Types of Changes Reported on Subsequent
- Synchronizations . . . . . . . . . . . . . . . . . . . . . 9
- 3.5.1. Changed Member . . . . . . . . . . . . . . . . . . . . 9
- 3.5.2. Removed Member . . . . . . . . . . . . . . . . . . . . 10
- 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 10
- 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 11
- 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 11
- 3.9. Example: DAV:sync-collection Report with Token . . . . . . 13
- 3.10. Example: Initial DAV:sync-collection Report with
- Truncation . . . . . . . . . . . . . . . . . . . . . . . . 16
- 3.11. Example: Initial DAV:sync-collection Report with Limit . . 17
- 3.12. Example: DAV:sync-collection Report with Unsupported
- Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 19
- 3.13. Example: Depth:infinity initial DAV:sync-collection
- Report . . . . . . . . . . . . . . . . . . . . . . . . . . 19
- 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 22
- 5. DAV:sync-token Use with If Header . . . . . . . . . . . . . . 22
- 5.1. Example: If Pre-Condition with PUT . . . . . . . . . . . . 23
- 5.2. Example: If Pre-Condition with MKCOL . . . . . . . . . . . 23
- 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 24
- 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 24
- 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 24
- 6.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 25
- 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
- 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26
- 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 26
- 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 26
- 10.1. Normative References . . . . . . . . . . . . . . . . . . . 26
- 10.2. Informative References . . . . . . . . . . . . . . . . . . 27
- Appendix A. Change History (to be removed prior to
- publication as an RFC) . . . . . . . . . . . . . . . 27
-
-
-
-
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 3]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-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 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 member
- URIs that were added or deleted, or whose mapped resources were
- changed, 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 collection's member URIs or their mapped resources 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
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 4]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 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 [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 member URIs that are currently 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 [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.
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 5]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 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.
-
-3.2. DAV:sync-collection Report
-
- 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 URIs and their mapped resources in a
- collection (as defined in Section 3 of [RFC4918]). This includes
- noting the addition of new member URIs, changes to the mapped
- resources of existing member URIs, and removal of member URIs. 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. However, the
- token MUST be a valid URI to allow its use in an If pre-condition
- request header (see Section 5). 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. The numeric value could be appended to a "base" URI to form
- the valid sync-token.
-
- Marshalling:
-
- The request URI MUST identify a collection. The request body MUST
- be a DAV:sync-collection XML element (see Section 6.1), 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
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 6]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- element in addition to one DAV:response element for each member
- URI that was added, has had its mapped resource changed, or was
- deleted since the last synchronization operation as specified by
- the DAV:sync-token provided in the request. A given member URI
- MUST appear only once in the response. In the case where multiple
- member URIs of the request-URI are mapped to the same resource, if
- the resource is changed, each member URI MUST be returned in the
- response.
-
- The content of each DAV:response element differs depending on how
- the member was altered:
-
- For members that have changed (i.e., are new or have had their
- mapped resource modified) the DAV:response MUST contain at
- least one DAV:propstat element and MUST NOT contain any DAV:
- status element.
-
- For members 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 members that are collections and are unable to support the
- DAV:sync-collection report, the DAV:response MUST contain one
- DAV:status with a value set to '403 Forbidden', a DAV:error
- containing DAV:supported-report or DAV:sync-traversal-supported
- (see Section 3.3 for which is appropriate), and MUST NOT
- contain any DAV:propstat element.
-
- The conditions under which each type of change can occur is
- further described in Section 3.5.
-
- Preconditions:
-
- (DAV:valid-sync-token): The DAV:sync-token element value MUST be a
- valid token previously returned by the server. A token can 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 Section 3.7) but the
- server is unable to truncate the result set at or below that
- limit.
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 7]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-3.3. Depth behavior
-
- Servers MUST support both Depth:1 and Depth:infinity behavior with
- the DAV:sync-collection report. Clients MUST include either a
- Depth:1 or Depth:infinity request header with the DAV:sync-collection
- report.
-
- o When the client specifies a Depth:1 request header, only
- appropriate internal member URIs (immediate children) of the
- collection specified as the request URI are reported.
-
- o When the client specifies a Depth:infinity request header, all
- appropriate member URIs of the collection specified as the request
- URI are reported, provided child collections themselves also
- support the DAV:sync-collection report.
-
- o 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. When this occurs, the server MUST
- include a DAV:response element for the child collection with status
- '403 Forbidden'. The 403 response MUST be sent once, when the
- collection is first reported to the client. In addition, the server
- MUST include a DAV:error element in the DAV:response element,
- indicating one of two possible causes for this:
-
- The DAV:sync-collection report is not supported at all on the
- child collection. The DAV:error element MUST contain the DAV:
- supported-report element.
-
- The server is unwilling to report results for the child collection
- when a Depth:infinity DAV:sync-collection report is executed on a
- parent resource. This might happen when, for example, the
- synchronization state of the collection resource is controlled by
- another sub-system. In such cases clients can perform the DAV:
- sync-collection report directly on the child collection instead.
- The DAV:error element MUST contain the DAV:sync-traversal-
- supported element.
-
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 8]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-3.4. Types of Changes Reported on Initial Synchronization
-
- When the DAV:sync-collection request contains an empty DAV:sync-token
- element, the server MUST return all member URIs of the collection
- (taking account of Depth header requirements as per Section 3.3, and
- optional truncation of results set as per Section 3.6) and it MUST
- NOT return any removed member URIs. All types of member (collection
- or non-collection) MUST be reported.
-
-3.5. Types of Changes Reported on Subsequent Synchronizations
-
- When the DAV:sync-collection request contains a valid value for the
- DAV:sync-token element, two types of member URI 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
- member URI might have undergone multiple changes between two
- synchronization report requests. In all cases, the Depth header
- requirements as per Section 3.3, and optional truncation of results
- set as per Section 3.6, are taken into account by the server.
-
-3.5.1. Changed Member
-
- A member URI MUST be reported as changed if it has been mapped as a
- member of the target collection since the request sync-token was
- generated. This includes member URIs that have been mapped as the
- result of a COPY, MOVE, BIND [RFC5842], or REBIND [RFC5842] request.
- All types of member URI (collection or non-collection) MUST be
- reported.
-
- In the case where a mapping between a member URI and the target
- collection was removed, then a new mapping with the same URI created,
- the member URI MUST be reported as changed and MUST NOT be reported
- as removed.
-
- A member URI MUST be reported as changed if its mapped resource's
- entity tag value (defined in Section 3.11 of [RFC2616]) has changed
- since the request sync-token was generated.
-
- A member URI MAY be reported as changed if the user issuing the
- request was granted access to this member URI, due to access control
- changes.
-
- Collection member URIs MUST be returned as changed if they are mapped
- to an underlying resource (i.e., entity body) and if the entity tag
- associated with that resource 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
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 9]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- collection. Instead Depth:infinity has to be used.
-
-3.5.2. Removed Member
-
- A member 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 members that have been unmapped as the result of a MOVE,
- UNBIND [RFC5842], or REBIND [RFC5842] operation. This also includes
- collection members that have been removed, including ones that
- themselves do not support the DAV:sync-collection report.
-
- If a member was added (and its mapped resource possibly modified),
- then removed between two synchronization report requests, it MUST be
- reported as removed. This ensures that a client that adds a member
- is informed of the removal of the member, if the removal occurs
- before the client has had a chance to execute a synchronization
- report.
-
- A member MAY be reported as removed if the user issuing the request
- no longer has access to this member, due to access control changes.
-
- For a Depth:infinity report where a collection is removed, the server
- MUST NOT report the removal of any members of the removed collection.
- Clients MUST assume that if a collection is reported as being
- removed, then all members of that collection have also been removed.
-
-3.6. Truncation of Results
-
- A server MAY limit the number of member URIs 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 [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
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 10]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 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 (appropriately encoded
- as a URI). Assume the last DAV:sync-token used by the client was
- "http://example.com/sync/10", and since then 15 additional changes
- have occurred. If the client executes a DAV:sync-collection request
- with a DAV:sync-token of "http://example.com/sync/10", without a
- limit the server would return 15 DAV:response elements and a DAV:
- sync-token with value "http://example.com/sync/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
- "http://example.com/sync/20", together with an additional 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.
-
-3.7. 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.8. 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
- proprietary property. The server responds with the items currently
- in the targeted collection. The current synchronization token is
- also returned.
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 11]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> 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>
- <D:propstat>
- <D:prop>
- <D:getetag>"00002-abcd1"</D:getetag>
- </D:prop>
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 12]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- <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>http://example.com/ns/sync/1234</D:sync-token>
- </D:multistatus>
-
-
-3.9. 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 January 12, 2012 [Page 13]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> 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>http://example.com/ns/sync/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 January 12, 2012 [Page 14]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> 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>http://example.com/ns/sync/1238</D:sync-token>
- </D:multistatus>
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 15]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-3.10. 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 January 12, 2012 [Page 16]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> 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:error><D:number-of-matches-within-limits/></D:error>
- </D:response>
- <D:sync-token>http://example.com/ns/sync/1233</D:sync-token>
- </D:multistatus>
-
-
-3.11. 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 January 12, 2012 [Page 17]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> 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:error><D:number-of-matches-within-limits/></D:error>
- </D:response>
- <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
- </D:multistatus>
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 18]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-3.12. 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>http://example.com/ns/sync/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>
-
-
-3.13. Example: Depth:infinity 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, and it is using Depth:infinity. It also asks for the DAV:
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 19]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 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 403 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.
-
- >> Request <<
-
-
- REPORT /home/cyrusdaboo/ HTTP/1.1
- Host: webdav.example.com
- Depth: infinity
- 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>/home/cyrusdaboo/collection1/</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>
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 20]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- </R:bigbox>
- </D:prop>
- <D:status>HTTP/1.1 200 OK</D:status>
- </D:propstat>
- </D:response>
- <D:response>
- <D:href>/home/cyrusdaboo/collection1/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>/home/cyrusdaboo/collection2/</D:href>
- <D:propstat>
- <D:prop>
- <D:getetag/>
- </D:prop>
- <D:status>HTTP/1.1 404 Not Found</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>/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:response>
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 21]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- <D:href>/home/cyrusdaboo/shared/</D:href>
- <D:status>HTTP/1.1 403 Forbidden</D:status>
- <D:error><D:sync-traversal-supported/></D:error>
- </D:response>
- <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
- </D:multistatus>
-
-
-4. DAV:sync-token Property
-
- 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 valid URI.
-
- 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 Section 14.2 of [RFC4918]).
-
- Definition:
-
-
- <!ELEMENT sync-token #PCDATA>
- <!-- Text MUST be a valid URI -->
-
-
-5. DAV:sync-token Use with If Header
-
- WebDAV provides an If pre-condition header that allows for "state
- tokens" to be used as pre-conditions on HTTP requests (as defined in
- Section 10.4 of [RFC4918]). This specification allows the DAV:sync-
- token value to be used as one such token in an If header. By using
- this, clients can ensure requests only complete when there have been
- no changes to the content of a collection, by virtue of an un-changed
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 22]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- DAV:sync-token value. Servers MUST support use of DAV:sync-token
- values in If request headers.
-
-5.1. Example: If Pre-Condition with PUT
-
- In this example, the client has already used the DAV:sync-collection
- report to synchronize the collection /home/cyrusdaboo/collection/.
- Now it wants to add a new resource to the collection, but only if
- there have been no other changes since the last synchronization.
- Note, that because the DAV:sync-token is defined on the collection
- and not on the resource targeted by the request, the If header value
- needs to use the "Resource_Tag" construct for the header syntax to
- correctly identify that the supplied state token refers to the
- collection resource.
-
- >> Request <<
-
-
- PUT /home/cyrusdaboo/collection/newresource.txt HTTP/1.1
- Host: webdav.example.com
- If: </home/cyrusdaboo/collection/>
- (<http://example.com/ns/sync/12345>)
- Content-Type: text/plain; charset="utf-8"
- Content-Length: xxxx
-
- Some content here...
-
-
- >> Response <<
-
-
- HTTP/1.1 201 Created
-
-
-5.2. Example: If Pre-Condition with MKCOL
-
- In this example, the client has already used the DAV:sync-collection
- report to synchronize the collection /home/cyrusdaboo/collection/.
- Now it wants to add a new collection to the collection, but only if
- there have been no other changes since the last synchronization.
- Note, that because the DAV:sync-token is defined on the collection
- and not on the resource targeted by the request, the If header value
- needs to use the "Resource_Tag" construct for the header syntax to
- correctly identify that the supplied state token refers to the
- collection resource. In this case the request fails as another
- change has occurred to the collection corresponding to the supplied
- DAV:sync-token.
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 23]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- >> Request <<
-
-
- MKCOL /home/cyrusdaboo/collection/child/ HTTP/1.1
- Host: webdav.example.com
- If: </home/cyrusdaboo/collection/>
- (<http://example.com/ns/sync/12346>)
-
-
- >> Response <<
-
-
- HTTP/1.1 412 Pre-condition Failed
-
-
-6. XML Element Definitions
-
-6.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 -->
-
-
-6.2. DAV:sync-token XML Element
-
- Name: sync-token
-
- Namespace: DAV:
-
- Purpose: The synchronization token provided by the server and
- returned by the client.
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 24]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- Description: See Section 3.
-
-
-
- <!ELEMENT sync-token CDATA>
- <!-- Text MUST be a URI -->
-
-
-6.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 -->
-
-
-7. Security Considerations
-
- Servers MUST take care to limit the scope of DAV:sync-collection
- requests so that clients cannot use excessive server resources by
- executing, for example, a Depth:infinity report on the root URI. For
- example, CalDAV [RFC4791] servers might only support the DAV:sync-
- collection report on user calendar home collections, and prevent use
- of the report on the parent resource of all calendar homes (assuming
- there is one). That way each individual user's request is scoped to
- changes only within their own calendar home and not across the entire
- set of calendar users.
-
- Beyond the above considerations, this extension does not introduce
- any new security concerns than those already described in HTTP and
- WebDAV.
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 25]
-
-Internet-Draft WebDAV Sync July 2011
-
-
-8. IANA Considerations
-
- This document does not require any actions on the part of IANA.
-
-9. Acknowledgments
-
- The following individuals contributed their ideas and support for
- writing this specification: Bernard Desruisseaux, Werner Donne, 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.
-
-10. References
-
-10.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.
-
- [RFC5842] Clemm, G., Crawford, J., Reschke, J.,
- and J. Whitehead, "Binding Extensions to
- Web Distributed Authoring and Versioning
- (WebDAV)", RFC 5842, April 2010.
-
- [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T.,
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 26]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- Sperberg-McQueen, C., and E. Maler,
- "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>.
-
-10.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.
-
- [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 -06:
-
- 1. Changed the 405 error into a 403 with a DAV:error element.
-
- 2. Stated more clearly that both depth:1 and depth:infinity must be
- supported.
-
- 3. Tied up sync-token as URI changes.
-
- 4. Made BIND a normative reference.
-
- 5. Take into account REBIND.
-
- 6. Reworked text to more accurately make the distinction between
- member URIs and resources, which should clarify the interaction
- with extensions like BIND.
-
- Changes in -05:
-
- 1. Added option to use DAV:sync-token as an If pre-condition state
- token.
-
- 2. DAV:sync-token value now required to be a URI so it can be used
- in the If header.
-
- Changes in -04:
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 27]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 1. Depth:infinity support added.
-
- 2. Collection resources are now reported as changed if they have a
- valid entity tag associated with them.
-
- 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.
-
- 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.
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 28]
-
-Internet-Draft WebDAV Sync July 2011
-
-
- 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 at daboo.name
- URI: http://www.apple.com/
-
-
- Arnaud Quillaud
- Oracle Corporation
- 180, Avenue de l'Europe
- Saint Ismier cedex, 38334
- France
-
- EMail: arnaud.quillaud at oracle.com
- URI: http://www.oracle.com/
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Daboo & Quillaud Expires January 12, 2012 [Page 29]
-
Added: CalendarServer/trunk/doc/RFC/rfc6578-WebDAV Sync.txt
===================================================================
--- CalendarServer/trunk/doc/RFC/rfc6578-WebDAV Sync.txt (rev 0)
+++ CalendarServer/trunk/doc/RFC/rfc6578-WebDAV Sync.txt 2012-04-25 01:40:25 UTC (rev 9182)
@@ -0,0 +1,1627 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF) C. Daboo
+Request for Comments: 6578 Apple Inc.
+Category: Standards Track A. Quillaud
+ISSN: 2070-1721 Oracle
+ March 2012
+
+
+ Collection Synchronization
+ for Web Distributed Authoring and Versioning (WebDAV)
+
+Abstract
+
+ This specification defines an extension to Web Distributed Authoring
+ and Versioning (WebDAV) that allows efficient synchronization of the
+ contents of a WebDAV collection.
+
+Status of This Memo
+
+ This is an Internet Standards Track document.
+
+ This document is a product of the Internet Engineering Task Force
+ (IETF). It represents the consensus of the IETF community. It has
+ received public review and has been approved for publication by the
+ Internet Engineering Steering Group (IESG). Further information on
+ Internet Standards is available in Section 2 of RFC 5741.
+
+ Information about the current status of this document, any errata,
+ and how to provide feedback on it may be obtained at
+ http://www.rfc-editor.org/info/rfc6578.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 1]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Copyright Notice
+
+ 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.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 2]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+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. Depth Behavior . . . . . . . . . . . . . . . . . . . . . . 8
+ 3.4. Types of Changes Reported on Initial Synchronization . . . 9
+ 3.5. Types of Changes Reported on Subsequent
+ Synchronizations . . . . . . . . . . . . . . . . . . . . . 10
+ 3.5.1. Changed Member . . . . . . . . . . . . . . . . . . . . 10
+ 3.5.2. Removed Member . . . . . . . . . . . . . . . . . . . . 10
+ 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 11
+ 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 12
+ 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 12
+ 3.9. Example: DAV:sync-collection Report with Token . . . . . . 14
+ 3.10. Example: Initial DAV:sync-collection Report with
+ Truncation . . . . . . . . . . . . . . . . . . . . . . . . 16
+ 3.11. Example: Initial DAV:sync-collection Report with Limit . . 17
+ 3.12. Example: DAV:sync-collection Report with Unsupported
+ Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 18
+ 3.13. Example: DAV:sync-level Set to Infinite, Initial
+ DAV:sync-collection Report . . . . . . . . . . . . . . . . 19
+ 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 22
+ 5. DAV:sync-token Use with If Header . . . . . . . . . . . . . . 22
+ 5.1. Example: If Precondition with PUT . . . . . . . . . . . . 22
+ 5.2. Example: If Precondition with MKCOL . . . . . . . . . . . 23
+ 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 24
+ 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 24
+ 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 24
+ 6.3. DAV:sync-level XML Element . . . . . . . . . . . . . . . . 24
+ 6.4. DAV:multistatus XML Element . . . . . . . . . . . . . . . 25
+ 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25
+ 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25
+ 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25
+ 9.1. Normative References . . . . . . . . . . . . . . . . . . . 25
+ 9.2. Informative References . . . . . . . . . . . . . . . . . . 26
+ Appendix A. Backwards-Compatible Handling of Depth . . . . . . . 27
+ Appendix B. Example of a Client Synchronization Approach . . . . 27
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 3]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+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). Currently, this can
+ 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 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 member
+ URLs that were added or deleted, or whose mapped resources were
+ changed, 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 collection's member URLs or their mapped resources 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
+ otherwise.
+
+ 3. Extension elements (elements not already defined as valid child
+ elements) may be added anywhere, except when explicitly stated
+ otherwise.
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 4]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ 4. 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 [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 between 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 member URLs that are currently 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 [RFC5323], or specialized REPORTs such as those
+ defined in CalDAV [RFC4791] and CardDAV [RFC6352]) and ask for the
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 5]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ DAV:sync-token property to be returned. This property (defined in
+ Section 4) contains the same token that can be used later 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.
+
+ Typically, a client will use the synchronization report to retrieve
+ the list of changes and will follow that with requests to retrieve
+ the content of changed resources. It is possible that additional
+ changes to the collection could occur between the time of the
+ synchronization report and resource content retrieval, which could
+ result in an inconsistent view of the collection. When clients use
+ this method of synchronization, they need to be aware that such
+ additional changes could occur and track them, e.g., by differences
+ between the ETag values returned in the synchronization report and
+ those returned when actually fetching resource content, by using
+ conditional requests as described in Section 5, or by repeating the
+ synchronization process until no changes are returned.
+
+3.2. DAV:sync-collection Report
+
+ 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 that supports
+ synchronization.
+
+ To implement the behavior for this report, a server needs to keep
+ track of changes to any member URLs and their mapped resources in a
+ collection (as defined in Section 3 of [RFC4918]). This includes
+ noting the addition of new member URLs, the changes to the mapped
+ resources of existing member URLs, and the removal of member URLs.
+ 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 MUST be treated as an "opaque"
+ string by the client, i.e., the actual string data has no specific
+ meaning or syntax. However, the token MUST be a valid URI to allow
+
+
+
+Daboo & Quillaud Standards Track [Page 6]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ its use in an If precondition request header (see Section 5). 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. The numeric value could be
+ appended to a "base" URI to form the valid sync-token.
+
+ Marshalling:
+
+ The request-URI MUST identify a collection. The request body MUST
+ be a DAV:sync-collection XML element (see Section 6.1), which MUST
+ contain one DAV:sync-token XML element, one DAV:sync-level
+ element, and one DAV:prop XML element, and MAY contain a DAV:limit
+ XML element.
+
+ This report is only defined when the Depth header has value "0";
+ other values result in a 400 (Bad Request) error response. Note
+ that [RFC3253], Section 3.6, states that if the Depth header is
+ not present, it defaults to a value of "0".
+
+ 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 member
+ URL that was added, has had its mapped resource changed, or was
+ deleted since the last synchronization operation as specified by
+ the DAV:sync-token provided in the request. A given member URL
+ MUST appear only once in the response. In the case where multiple
+ member URLs of the request-URI are mapped to the same resource, if
+ the resource is changed, each member URL MUST be returned in the
+ response.
+
+ The content of each DAV:response element differs depending on how
+ the member was altered:
+
+ For members that have changed (i.e., are new or have had their
+ mapped resource modified), the DAV:response MUST contain at
+ least one DAV:propstat element and MUST NOT contain any
+ DAV:status element.
+
+ For members 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 members that are collections and are unable to support the
+ DAV:sync-collection report, the DAV:response MUST contain one
+ DAV:status with a value set to '403 Forbidden', a DAV:error
+ containing DAV:supported-report or DAV:sync-traversal-supported
+ (see Section 3.3 for which is appropriate) and MUST NOT contain
+ any DAV:propstat element.
+
+
+
+Daboo & Quillaud Standards Track [Page 7]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ The conditions under which each type of change can occur are
+ further described in Section 3.5.
+
+ Preconditions:
+
+ (DAV:valid-sync-token): The DAV:sync-token element value MUST be a
+ valid token previously returned by the server for the collection
+ targeted by the request-URI. Servers might need to invalidate
+ tokens previously returned to clients. Doing so will cause the
+ clients to fall back to doing full synchronization using the
+ report, though that will not require clients to download resources
+ that are already cached and have not changed. Even so, servers
+ MUST limit themselves to invalidating tokens only when absolutely
+ necessary. Specific reasons include:
+
+ * Servers might be unable to maintain all of the change data for
+ a collection due to storage or performance reasons, e.g.,
+ servers might only be able to maintain up to 3 weeks worth of
+ changes to a collection, or only up to 10,000 total changes, or
+ not wish to maintain changes for a deleted collection.
+
+ * Change to server implementation: servers might be upgraded to a
+ new implementation that tracks the history in a different
+ manner, and thus previous synchronization history is no longer
+ valid.
+
+ 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.7), but the
+ server is unable to truncate the result set at or below that
+ limit.
+
+3.3. Depth Behavior
+
+ Servers MUST support only Depth:0 behavior with the
+ DAV:sync-collection report, i.e., the report targets only the
+ collection being synchronized in a single request. However, clients
+ do need to "scope" the synchronization to different levels within
+ that collection -- specifically, immediate children (level "1") and
+ all children at any depth (level "infinite"). To specify which level
+ to use, clients MUST include a DAV:sync-level XML element in the
+ request.
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 8]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ o When the client specifies the DAV:sync-level XML element with a
+ value of "1", only appropriate internal member URLs (immediate
+ children) of the collection specified as the request-URI are
+ reported.
+
+ o When the client specifies the DAV:sync-level XML element with a
+ value of "infinite", all appropriate member URLs of the collection
+ specified as the request-URI are reported, provided child
+ collections themselves also support the DAV:sync-collection
+ report.
+
+ o DAV:sync-token values returned by the server are not specific to
+ the value of the DAV:sync-level XML element used in the request.
+ As such, clients MAY use a DAV:sync-token value from a request
+ with one DAV:sync-level XML element value for a similar request
+ with a different DAV:sync-level XML element value; however, the
+ utility of this is limited.
+
+ Note that when a server supports a DAV:sync-level XML element with a
+ value of "infinite", it might not be possible to synchronize some
+ child collections within the collection targeted by the report. When
+ this occurs, the server MUST include a DAV:response element for the
+ child collection with status 403 (Forbidden). The 403 response MUST
+ be sent once, when the collection is first reported to the client.
+ In addition, the server MUST include a DAV:error element in the
+ DAV:response element, indicating one of two possible causes for this:
+
+ The DAV:sync-collection report is not supported at all on the
+ child collection. The DAV:error element MUST contain the
+ DAV:supported-report element.
+
+ The server is unwilling to report results for the child collection
+ when a DAV:sync-collection report with the DAV:sync-level XML
+ element set to "infinite" is executed on a parent resource. This
+ might happen when, for example, the synchronization state of the
+ collection resource is controlled by another subsystem. In such
+ cases clients can perform the DAV:sync-collection report directly
+ on the child collection instead. The DAV:error element MUST
+ contain the DAV:sync-traversal-supported element.
+
+3.4. Types of Changes Reported on Initial Synchronization
+
+ When the DAV:sync-collection request contains an empty DAV:sync-token
+ element, the server MUST return all member URLs of the collection
+ (taking account of the DAV:sync-level XML element value as per
+ Section 3.3, and optional truncation of the result set as per
+ Section 3.6) and it MUST NOT return any removed member URLs. All
+ types of member (collection or non-collection) MUST be reported.
+
+
+
+Daboo & Quillaud Standards Track [Page 9]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+3.5. Types of Changes Reported on Subsequent Synchronizations
+
+ When the DAV:sync-collection request contains a valid value for the
+ DAV:sync-token element, two types of member URL 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
+ member URL might have undergone multiple changes between two
+ synchronization report requests. In all cases, the DAV:sync-level
+ XML element value (as per Section 3.3) and optional truncation of the
+ result set (as per Section 3.6) are taken into account by the server.
+
+3.5.1. Changed Member
+
+ A member URL MUST be reported as changed if it has been newly mapped
+ as a member of the target collection since the request sync-token was
+ generated (e.g., when a new resource has been created as a child of
+ the collection). For example, this includes member URLs that have
+ been newly mapped as the result of a COPY, MOVE, BIND [RFC5842], or
+ REBIND [RFC5842] request. All types of member URL (collection or
+ non-collection) MUST be reported.
+
+ In the case where a mapping between a member URL and the target
+ collection was removed, then a new mapping with the same URI was
+ created, the member URL MUST be reported as changed and MUST NOT be
+ reported as removed.
+
+ A member URL MUST be reported as changed if its mapped resource's
+ entity tag value (defined in Section 3.11 of [RFC2616]) has changed
+ since the request sync-token was generated.
+
+ A member URL MAY be reported as changed if the user issuing the
+ request was granted access to this member URL, due to access control
+ changes.
+
+ Collection member URLs MUST be returned as changed if they are mapped
+ to an underlying resource (i.e., entity body) and if the entity tag
+ associated with that resource 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
+ reports using the DAV:sync-level XML element value set to "1" at
+ multiple levels to track all changes within a collection. Instead, a
+ DAV:sync-level XML element with a value of "infinite" has to be used.
+
+3.5.2. Removed Member
+
+ A member 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 remapped since it was removed. For
+
+
+
+Daboo & Quillaud Standards Track [Page 10]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ example, this includes members that have been unmapped as the result
+ of a MOVE, UNBIND [RFC5842], or REBIND [RFC5842] operation. This
+ also includes collection members that have been removed, including
+ ones that themselves do not support the DAV:sync-collection report.
+
+ If a member was added (and its mapped resource possibly modified),
+ then removed between two synchronization report requests, it MUST be
+ reported as removed. This ensures that a client that adds a member
+ is informed of the removal of the member, if the removal occurs
+ before the client has had a chance to execute a synchronization
+ report.
+
+ A member MAY be reported as removed if the user issuing the request
+ no longer has access to this member, due to access control changes.
+
+ For a report with the DAV:sync-level XML element value set to
+ "infinite", where a collection is removed, the server MUST NOT report
+ the removal of any members of the removed collection. Clients MUST
+ assume that if a collection is reported as being removed, then all
+ members of that collection have also been removed.
+
+3.6. Truncation of Results
+
+ A server MAY limit the number of member URLs 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
+ (Multi-Status), 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
+ [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 strictly
+ increasing integer to represent a "revision number" and uses that
+ quantity as the DAV:sync-token value (appropriately encoded as a
+ URI). Assume the last DAV:sync-token used by the client was
+
+
+
+Daboo & Quillaud Standards Track [Page 11]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ "http://example.com/sync/10", and since then 15 additional changes to
+ different resources have occurred. If the client executes a
+ DAV:sync-collection request with a DAV:sync-token of
+ "http://example.com/sync/10", without a limit, the server would
+ return 15 DAV:response elements and a DAV:sync-token with value
+ "http://example.com/sync/25". But if the server chooses to limit
+ responses to at most 10 changes, then it would return only 10
+ DAV:response elements and a DAV:sync-token with value
+ "http://example.com/sync/20", together with an additional
+ DAV:response element for the request-URI with a status code of 507.
+ Subsequently, the client can reissue the request with the
+ DAV:sync-token value returned from the server and fetch the remaining
+ 5 changes.
+
+3.7. 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 postcondition
+ 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.8. 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
+ 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: 0
+ 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:sync-level>1</D:sync-level>
+
+
+
+Daboo & Quillaud Standards Track [Page 12]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <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>
+ <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>
+
+
+
+Daboo & Quillaud Standards Track [Page 13]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <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>http://example.com/ns/sync/1234</D:sync-token>
+ </D:multistatus>
+
+3.9. 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.
+
+ >> 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>http://example.com/ns/sync/1234</D:sync-token>
+ <D:sync-level>1</D:sync-level>
+ <D:prop xmlns:R="urn:ns.example.com:boxschema">
+ <D:getetag/>
+ <R:bigbox/>
+ </D:prop>
+ </D:sync-collection>
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 14]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> 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>http://example.com/ns/sync/1238</D:sync-token>
+ </D:multistatus>
+
+
+
+Daboo & Quillaud Standards Track [Page 15]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+3.10. 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: 0
+ 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:sync-level>1</D:sync-level>
+ <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>
+
+
+
+Daboo & Quillaud Standards Track [Page 16]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <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:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1233</D:sync-token>
+ </D:multistatus>
+
+3.11. 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.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ 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:sync-level>1</D:sync-level>
+ <D:limit>
+ <D:nresults>1</D:nresults>
+ </D:limit>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ </D:sync-collection>
+
+
+
+Daboo & Quillaud Standards Track [Page 17]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> 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:error><D:number-of-matches-within-limits/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
+ </D:multistatus>
+
+3.12. 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 postcondition error code.
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ Content-Type: text/xml; charset="utf-8"
+ Content-Length: xxxx
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 18]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <?xml version="1.0" encoding="utf-8" ?>
+ <D:sync-collection xmlns:D="DAV:">
+ <D:sync-token>http://example.com/ns/sync/1232</D:sync-token>
+ <D:sync-level>1</D:sync-level>
+ <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>
+
+3.13. Example: DAV:sync-level Set to Infinite, 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, and it is using DAV:sync-level set to "infinite". 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 that is also reported. The collection /home/cyrusdaboo/
+ collection2/ exists but has no child resources. The collection
+ /home/cyrusdaboo/shared/ is returned with a 403 status indicating
+ that a collection exists, but it is unable to report on changes
+ within it in the scope of the current DAV:sync-level "infinite"
+ report. Instead, the client can try a DAV:sync-collection report
+ directly on the collection URI.
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 19]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> Request <<
+
+
+ REPORT /home/cyrusdaboo/ HTTP/1.1
+ Host: webdav.example.com
+ Depth: 0
+ 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:sync-level>infinite</D:sync-level>
+ <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>/home/cyrusdaboo/collection1/</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>/home/cyrusdaboo/collection1/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>
+
+
+
+Daboo & Quillaud Standards Track [Page 20]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ </R:bigbox>
+ </D:prop>
+ <D:status>HTTP/1.1 200 OK</D:status>
+ </D:propstat>
+ </D:response>
+ <D:response>
+ <D:href>/home/cyrusdaboo/collection2/</D:href>
+ <D:propstat>
+ <D:prop>
+ <D:getetag/>
+ </D:prop>
+ <D:status>HTTP/1.1 404 Not Found</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>/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:response>
+ <D:href>/home/cyrusdaboo/shared/</D:href>
+ <D:status>HTTP/1.1 403 Forbidden</D:status>
+ <D:error><D:sync-traversal-supported/></D:error>
+ </D:response>
+ <D:sync-token>http://example.com/ns/sync/1234</D:sync-token>
+ </D:multistatus>
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 21]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+4. DAV:sync-token Property
+
+ 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 valid URI.
+
+ 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 Section 14.2 of [RFC4918]).
+
+ Definition:
+
+ <!ELEMENT sync-token #PCDATA>
+
+ <!-- Text MUST be a valid URI -->
+
+5. DAV:sync-token Use with If Header
+
+ WebDAV provides an If precondition header that allows for "state
+ tokens" to be used as preconditions on HTTP requests (as defined in
+ Section 10.4 of [RFC4918]). This specification allows the
+ DAV:sync-token value to be used as one such token in an If header.
+ By using this, clients can ensure requests only complete when there
+ have been no changes to the content of a collection, by virtue of an
+ unchanged DAV:sync-token value. Servers MUST support use of
+ DAV:sync-token values in If request headers.
+
+5.1. Example: If Precondition with PUT
+
+ In this example, the client has already used the DAV:sync-collection
+ report to synchronize the collection /home/cyrusdaboo/collection/.
+ Now it wants to add a new resource to the collection, but only if
+ there have been no other changes since the last synchronization.
+
+
+
+Daboo & Quillaud Standards Track [Page 22]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ Note that because the DAV:sync-token is defined on the collection and
+ not on the resource targeted by the request, the If header value
+ needs to use the "Resource_Tag" construct for the header syntax to
+ correctly identify that the supplied state token refers to the
+ collection resource.
+
+ >> Request <<
+
+
+ PUT /home/cyrusdaboo/collection/newresource.txt HTTP/1.1
+ Host: webdav.example.com
+ If: </home/cyrusdaboo/collection/>
+ (<http://example.com/ns/sync/12345>)
+ Content-Type: text/plain; charset="utf-8"
+ Content-Length: xxxx
+
+ Some content here...
+
+
+ >> Response <<
+
+
+ HTTP/1.1 201 Created
+
+5.2. Example: If Precondition with MKCOL
+
+ In this example, the client has already used the DAV:sync-collection
+ report to synchronize the collection /home/cyrusdaboo/collection/.
+ Now, it wants to add a new collection to the collection, but only if
+ there have been no other changes since the last synchronization.
+ Note that because the DAV:sync-token is defined on the collection and
+ not on the resource targeted by the request, the If header value
+ needs to use the "Resource_Tag" construct for the header syntax to
+ correctly identify that the supplied state token refers to the
+ collection resource. In this case, the request fails as another
+ change has occurred to the collection corresponding to the supplied
+ DAV:sync-token.
+
+ >> Request <<
+
+
+ MKCOL /home/cyrusdaboo/collection/child/ HTTP/1.1
+ Host: webdav.example.com
+ If: </home/cyrusdaboo/collection/>
+ (<http://example.com/ns/sync/12346>)
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 23]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ >> Response <<
+
+
+ HTTP/1.1 412 Precondition Failed
+
+6. XML Element Definitions
+
+6.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, sync-level, limit?, prop)>
+
+ <!-- DAV:limit defined in RFC 5323, Section 5.17 -->
+ <!-- DAV:prop defined in RFC 4918, Section 14.18 -->
+
+6.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>
+
+ <!-- Text MUST be a URI -->
+
+6.3. DAV:sync-level XML Element
+
+ Name: sync-level
+
+ Namespace: DAV:
+
+ Purpose: Indicates the "scope" of the synchronization report
+ request.
+
+ Description: See Section 3.3.
+
+
+
+Daboo & Quillaud Standards Track [Page 24]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ <!ELEMENT sync-level CDATA>
+
+ <!-- Text MUST be either "1" or "infinite" -->
+
+6.4. DAV:multistatus XML Element
+
+ Name: multistatus
+
+ Namespace: DAV:
+
+ Purpose: Extends the DAV:multistatus element to include
+ synchronization details.
+
+ Description: See Section 3.
+
+ <!ELEMENT multistatus (response*, 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 -->
+
+7. Security Considerations
+
+ This extension does not introduce any new security concerns beyond
+ those already described in HTTP and WebDAV.
+
+8. Acknowledgments
+
+ The following individuals contributed their ideas and support for
+ writing this specification: Bernard Desruisseaux, Werner Donne, 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.
+
+
+
+
+Daboo & Quillaud Standards Track [Page 25]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, C., and J.
+ Whitehead, "Versioning Extensions to WebDAV
+ (Web Distributed Authoring and Versioning)", RFC 3253,
+ March 2002.
+
+ [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]
+ Sperberg-McQueen, C., Yergeau, F., Paoli, J., Maler, E.,
+ 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>.
+
+9.2. Informative References
+
+ [RFC4791] Daboo, C., Desruisseaux, B., and L. Dusseault,
+ "Calendaring Extensions to WebDAV (CalDAV)", RFC 4791,
+ March 2007.
+
+ [RFC5842] Clemm, G., Crawford, J., Reschke, J., and J. Whitehead,
+ "Binding Extensions to Web Distributed Authoring and
+ Versioning (WebDAV)", RFC 5842, April 2010.
+
+ [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web Distributed
+ Authoring and Versioning (WebDAV)", RFC 6352, August 2011.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 26]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Appendix A. Backwards-Compatible Handling of Depth
+
+ In prior draft versions of this specification, the Depth request
+ header was used instead of the DAV:sync-level element to indicate the
+ "scope" of the synchronization request. Servers that wish to be
+ backwards compatible with clients conforming to the older
+ specification should do the following: if a DAV:sync-level element is
+ not present in the request body, use the Depth header value as the
+ equivalent value for the missing DAV:sync-level element.
+
+Appendix B. Example of a Client Synchronization Approach
+
+ This appendix gives an example of how a client might accomplish
+ collection synchronization using the WebDAV sync report defined in
+ this specification. Note that this is provided purely as an example,
+ and is not meant to be treated as a normative "algorithm" for client
+ synchronization.
+
+ This example assumes a WebDAV client interacting with a WebDAV server
+ supporting the sync report. The client keeps a local cache of
+ resources in a targeted collection, "/collection/". Local changes
+ are assumed to not occur. The client is only tracking changes to the
+ immediate children of the collection resource.
+
+ ** Initial State **
+
+ The client starts out with an empty local cache.
+
+ The client starts out with no DAV:sync-token stored for
+ "/collection/".
+
+
+ ** Initial Synchronization **
+
+ The client issues a sync report request to the server with an
+ empty DAV:sync-token element, and DAV:sync-level set to "1". The
+ request asks for the server to return the DAV:getetag WebDAV
+ property for each resource it reports.
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 27]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+ The server returns a response containing the list of current
+ resources (with their associated DAV:getetag properties) as well
+ as a new DAV:sync-token value.
+
+ The client associates the new DAV:sync-token value with the
+ collection.
+
+ For each reported resource, the client creates a set of (resource
+ path, DAV:getetag) tuples.
+
+ For each tuple, the client issues an HTTP GET request to the
+ server to retrieve its content, and updates the (resource path,
+ DAV:getetag) entry in its local cache for that resource with the
+ ETag response header value returned in the GET request.
+
+
+ ** Routine Synchronization **
+
+ The client issues a sync report request to the server with the
+ DAV:sync-token set to the current cached value from the last sync,
+ and DAV:sync-level set to "1". The request asks for the server to
+ return the DAV:getetag WebDAV property for each resource it
+ reports.
+
+ The server returns a response containing the list of changes as
+ well as a new DAV:sync-token value.
+
+ The client associates the new DAV:sync-token value with the
+ collection.
+
+ * Process Removed Resources *
+
+ For each resource reported with a 404 response status, the client
+ removes the corresponding resource from its local cache.
+
+ * Process Resources *
+
+ For each remaining reported resource, the client creates a new set
+ of (resource path, DAV:getetag) tuples.
+
+ The client then determines which resources are in the new set but
+ not in the current cache, and which resources are in the new set
+ and the current cache but have a different DAV:getetag value. For
+ each of those, the client issues an HTTP GET request to the server
+ to retrieve the resource content, and updates the (resource path,
+ DAV:getetag) entry in its local cache for that resource with the
+ ETag response header value returned in the GET request.
+
+
+
+
+Daboo & Quillaud Standards Track [Page 28]
+
+RFC 6578 WebDAV Sync March 2012
+
+
+Authors' Addresses
+
+ Cyrus Daboo
+ Apple Inc.
+ 1 Infinite Loop
+ Cupertino, CA 95014
+ USA
+
+ EMail: cyrus at daboo.name
+ URI: http://www.apple.com/
+
+
+ Arnaud Quillaud
+ Oracle Corporation
+ 180, Avenue de l'Europe
+ Saint Ismier cedex 38334
+ France
+
+ EMail: arnaud.quillaud at oracle.com
+ URI: http://www.oracle.com/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Daboo & Quillaud Standards Track [Page 29]
+
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.macosforge.org/pipermail/calendarserver-changes/attachments/20120424/083c71f4/attachment-0001.html>
More information about the calendarserver-changes
mailing list