[Docs] [txt|pdf|xml] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05 06 07 08 RFC 6578

Network Working Group                                           C. Daboo
Internet-Draft                                               Apple, Inc.
Intended status: Standards Track                             A. Quillaud
Expires: April 8, 2011                                            Oracle
                                                         October 5, 2010


                 Collection Synchronization for WebDAV
                       draft-daboo-webdav-sync-04

Abstract

   This specification defines an extension to WebDAV that allows
   efficient synchronization of the contents of a WebDAV collection.

Editorial Note (To be removed by RFC Editor before publication)

   Please send comments to the Distributed Authoring and Versioning
   (WebDAV) working group at <mailto:w3c-dist-auth@w3.org>, which may be
   joined by sending a message with subject "subscribe" to
   <mailto:w3c-dist-auth-request@w3.org>.  Discussions of the WEBDAV
   working group are archived at
   <http://lists.w3.org/Archives/Public/w3c-dist-auth/>.

Status of This Memo

   This Internet-Draft is submitted 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 April 8, 2011.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents



Daboo & Quillaud          Expires April 8, 2011                 [Page 1]

Internet-Draft                 WebDAV Sync                  October 2010


   (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 April 8, 2011                 [Page 2]

Internet-Draft                 WebDAV Sync                  October 2010


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Conventions Used in This Document  . . . . . . . . . . . . . .  4
   3.  WebDAV Synchronization . . . . . . . . . . . . . . . . . . . .  5
     3.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . .  5
     3.2.  DAV:sync-collection Report . . . . . . . . . . . . . . . .  6
     3.3.  Depth behavior . . . . . . . . . . . . . . . . . . . . . .  7
     3.4.  Types of Changes Reported on Initial Synchronization . . .  8
     3.5.  Types of Changes Reported on Subsequent
           Synchronizations . . . . . . . . . . . . . . . . . . . . .  8
       3.5.1.  Changed Resource . . . . . . . . . . . . . . . . . . .  8
       3.5.2.  Removed Resource . . . . . . . . . . . . . . . . . . .  9
     3.6.  Truncation of Results  . . . . . . . . . . . . . . . . . .  9
     3.7.  Limiting Results . . . . . . . . . . . . . . . . . . . . . 10
     3.8.  Example: Initial DAV:sync-collection Report  . . . . . . . 11
     3.9.  Example: DAV:sync-collection Report with Token . . . . . . 12
     3.10. Example: Initial DAV:sync-collection Report with
           Truncation . . . . . . . . . . . . . . . . . . . . . . . . 15
     3.11. Example: Initial DAV:sync-collection Report with Limit . . 16
     3.12. Example: DAV:sync-collection Report with Unsupported
           Limit  . . . . . . . . . . . . . . . . . . . . . . . . . . 18
     3.13. Example: Depth:infinity initial DAV:sync-collection
           Report . . . . . . . . . . . . . . . . . . . . . . . . . . 18
   4.  DAV:sync-token Property  . . . . . . . . . . . . . . . . . . . 21
   5.  XML Element Definitions  . . . . . . . . . . . . . . . . . . . 21
     5.1.  DAV:sync-collection XML Element  . . . . . . . . . . . . . 22
     5.2.  DAV:sync-token XML Element . . . . . . . . . . . . . . . . 22
     5.3.  DAV:multistatus XML Element  . . . . . . . . . . . . . . . 22
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 23
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 23
   8.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 23
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 23
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 24
   Appendix A.  Change History (to be removed prior to
                publication as an RFC)  . . . . . . . . . . . . . . . 24














Daboo & Quillaud          Expires April 8, 2011                 [Page 3]

Internet-Draft                 WebDAV Sync                  October 2010


1.  Introduction

   WebDAV [RFC4918] defines the concept of 'collections' which are
   hierarchical groupings of WebDAV resources on an HTTP [RFC2616]
   server.  Collections can be of arbitrary size and depth (i.e.,
   collections within collections).  WebDAV clients that cache resource
   content need a way to synchronize that data with the server (i.e.,
   detect what has changed and update their cache).  This can currently
   be done using a WebDAV PROPFIND request on a collection to list all
   members of a collection along with their DAV:getetag property values,
   which allows the client to determine which resources were changed,
   added or deleted.  However, this does not scale well to large
   collections as the XML response to the PROPFIND request will grow
   with the collection size.

   This specification defines a new WebDAV report that results in the
   server returning to the client only information about those resources
   which have changed, are new or were deleted since a previous
   execution of the report on the collection.

   Additionally, a new property is added to collection resources that is
   used to convey a "synchronization token" that is guaranteed to change
   when resources within the collection have changed.

2.  Conventions Used in This Document

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

   This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section
   3.2) as a purely notational convention.  WebDAV request and response
   bodies cannot be validated by a DTD due to the specific extensibility
   rules defined in Section 17 of [RFC4918] and due to the fact that all
   XML elements defined by this specification use the XML namespace name
   "DAV:".  In particular:

   1.  element names use the "DAV:" namespace,

   2.  element ordering is irrelevant unless explicitly stated,

   3.  extension elements (elements not already defined as valid child
       elements) may be added anywhere, except when explicitly stated
       otherwise,

   4.  extension attributes (attributes not already defined as valid for
       this element) may be added anywhere, except when explicitly
       stated otherwise.



Daboo & Quillaud          Expires April 8, 2011                 [Page 4]

Internet-Draft                 WebDAV Sync                  October 2010


   When an XML element type in the "DAV:" namespace is referenced in
   this document outside of the context of an XML fragment, the string
   "DAV:" will be prefixed to the element type.

   This document inherits, and sometimes extends, DTD productions from
   Section 14 of [RFC4918].

3.  WebDAV Synchronization

3.1.  Overview

   One way to synchronize data between two entities is to use some form
   of synchronization token.  The token defines the state of the data
   being synchronized at a particular point in time.  It can then be
   used to determine what has changed since one point in time and
   another.

   This specification defines a new WebDAV report that is used to enable
   client-server collection synchronization based on such a token.

   In order to synchronize the contents of a collection between a server
   and client, the server provides the client with a synchronization
   token each time the synchronization report is executed.  That token
   represents the state of the data being synchronized at that point in
   time.  The client can then present that same token back to the server
   at some later time and the server will return only those items that
   are new, have changed or were deleted since that token was generated.
   The server also returns a new token representing the new state at the
   time the report was run.

   Typically, the first time a client connects to the server it will
   need to be informed of the entire state of the collection (i.e., a
   full list of all resources that are currently contained in the
   collection).  That is done by the client sending an empty token value
   to the server.  This indicates to the server that a full listing is
   required.

   As an alternative, the client 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.

   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



Daboo & Quillaud          Expires April 8, 2011                 [Page 5]

Internet-Draft                 WebDAV Sync                  October 2010


   return an error to the client when the client presents a token that
   is "out of date".  At that point the client has to fall back to
   synchronizing the entire collection by re-running the report request
   using an empty token value.

3.2.  DAV:sync-collection Report

   If the DAV:sync-collection report is implemented by a WebDAV server,
   then the server MUST list the report in the "DAV:supported-report-
   set" property on any collection supporting synchronization.

   To implement the behavior for this report a server needs to keep
   track of changes to any member resources in a collection (as defined
   in Section 3 of [RFC4918]).  This includes noting the addition of new
   resources, changes to existing resources and removal of resources.
   The server will track each change and provide a synchronization
   "token" to the client that describes the state of the server at a
   specific point in time.  This "token" is returned as part of the
   response to the "sync-collection" report.  Clients include the last
   token they got from the server in the next "sync-collection" report
   that they execute and the server provides the changes from the
   previous state, represented by the token, to the current state,
   represented by the new token returned.

   The synchronization token itself is an "opaque" string - i.e., the
   actual string data has no specific meaning or syntax.  For example, a
   simple implementation of such a token could be a numeric counter that
   counts each change as it occurs and relates that change to the
   specific object that changed.

   Marshalling:

      The request URI MUST identify a collection.  The request body MUST
      be a DAV:sync-collection XML element (see Section 5.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
      element in addition to one DAV:response element for each resource
      that was created, has changed or been deleted since the last
      synchronization operation as specified by the DAV:sync-token
      provided in the request.  A given resource MUST appear only once
      in the response.




Daboo & Quillaud          Expires April 8, 2011                 [Page 6]

Internet-Draft                 WebDAV Sync                  October 2010


      The content of each DAV:response element differs depending on how
      the resource was altered:

         For resources that have changed (i.e., are new or have been
         modified) the DAV:response MUST contain at least one DAV:
         propstat element and MUST NOT contain any DAV:status element.

         For resources that have been removed, the DAV:response MUST
         contain one DAV:status with a value set to '404 Not Found' and
         MUST NOT contain any DAV:propstat element.

         For child collection resources that are unable to support the
         DAV:sync-collection report, the DAV:response MUST contain one
         DAV:status with a value set to '405 Method Not Allowed' and
         MUST NOT contain any DAV:propstat element.

      The conditions under which each type of change can occur is
      further described in Section 3.5.

   Preconditions:

      (DAV:valid-sync-token): The DAV:sync-token element value MUST map
      to a valid token previously returned by the server.  A token may
      become invalid as the result of being "out of date" (out of the
      range of change history maintained by the server), or for other
      reasons (e.g. collection deleted, then recreated, access control
      changes, etc...).

   Postconditions:

      (DAV:number-of-matches-within-limits): The number of changes
      reported in the response must fall within the client specified
      limit.  This condition might be triggered if a client requests a
      limit on the number of responses (as per Section 3.7) but the
      server is unable to truncate the result set at or below that
      limit.

3.3.  Depth behavior

   The DAV:sync-collection report supports both Depth:1 and Depth:
   infinity request headers.

   o  When the client specifies Depth:1, only additions, changes or
      removals of immediate children of the collection specified as the
      request URI are reported.

   o  When the client specifies Depth:infinity, additions, changes or
      removals of any child resource of the collection specified as the



Daboo & Quillaud          Expires April 8, 2011                 [Page 7]

Internet-Draft                 WebDAV Sync                  October 2010


      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.  In such cases the server is
   REQUIRED to return a DAV:response with status '405 Method Not
   Allowed' to inform the client that alternative methods have to be
   used to synchronize the contents of those collections.  The 405
   response MUST be sent once, when the collection is first reported to
   the client.

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 members 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 resources.  All types of resource (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 resource state changes can be
   returned (changed or removed).  This section defines what triggers
   each of these to be returned.  It also clarifies the case where a
   resource may have undergone multiple changes between two
   synchronization report requests.  In all cases, the Depth header
   requirements as per 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 Resource

   A resource MUST be reported as changed if it has been mapped as an
   member of the target collection since the request sync-token was
   generated.  This includes resources that have been mapped as the
   result of a COPY, MOVE or BIND [RFC5842] request.  All types of
   resource (collection or non-collection) MUST be reported.

   In the case where a mapping between a resource and the target
   collection was removed, then a new mapping with the same URI created,



Daboo & Quillaud          Expires April 8, 2011                 [Page 8]

Internet-Draft                 WebDAV Sync                  October 2010


   the new resource MUST be reported as changed while the old resource
   MUST NOT be reported as removed.  For example, if a resource was
   deleted, then recreated using the same URI, it should be reported as
   a changed resource only.

   A resource MUST be reported as changed if its entity tag value
   (defined in Section 3.11 of [RFC2616]) has changed since the request
   sync-token was generated.

   A resource MAY be reported as changed if the user issuing the request
   was granted access to this resource, due to access control changes.

   Collection resources MUST be returned as changed if they have an
   entity tag associated with them and that entity tag changes.  There
   is no guarantee that changes to members of a collection will result
   in a change in any entity tag of that collection, so clients cannot
   rely on a series of Depth:1 reports at multiple levels to track all
   changes within a collection.  Instead Depth:infinity has to be used.

3.5.2.  Removed Resource

   A resource MUST be reported as removed if its mapping under the
   target collection has been removed since the request sync-token was
   generated, and it has not been re-mapped since it was removed.  This
   includes resources that have been unmapped as the result of a MOVE or
   UNBIND [RFC5842] operation.  This also includes collection resources
   that have been removed, including ones that themselves do not support
   the DAV:sync-collection report.

   If a resource was created (and possibly modified), then removed
   between two synchronization report requests, it MUST be reported as
   removed.  This ensures that a client that creates a resource is
   informed of the removal of the resource, if the removal occurs before
   the client has had a chance to request a synchronization report.

   A resource MAY be reported as removed if the user issuing the request
   no longer has access to this resource, due to access control changes.

   For a Depth:infinity report where a collection is removed, the server
   MUST NOT report the removal of any resources that are members of the
   removed collection.  Clients MUST assume that if a collection is
   reported as being removed, then all internal members of that
   collection have also been removed.

3.6.  Truncation of Results

   A server MAY limit the number of resources in a response, for
   example, to limit the amount of work expended in processing a



Daboo & Quillaud          Expires April 8, 2011                 [Page 9]

Internet-Draft                 WebDAV Sync                  October 2010


   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
   to the report.

   For example, consider a server that records changes using a
   monotonically increasing integer to represent a "revision number" and
   uses that quantity as the DAV:sync-token value.  Assume the last DAV:
   sync-token used by the client was "10", and since then 15 additional
   changes have occurred.  If the client executes a DAV:sync-collection
   request with a DAV:sync-token of "10", without a limit the server
   would return 15 DAV:response elements and a DAV:sync-token with value
   "25".  But if the server choose to limit responses to at most 10
   changes, then it would return only 10 DAV:response elements and a
   DAV:sync-token with value "20", together with an addition DAV:
   response element for the request-URI with a status code of 507.
   Subsequently, the client can re-issue the request with the DAV:sync-
   token value returned from the server and fetch the remaining 5
   changes.

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.






Daboo & Quillaud          Expires April 8, 2011                [Page 10]

Internet-Draft                 WebDAV Sync                  October 2010


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: 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>



Daboo & Quillaud          Expires April 8, 2011                [Page 11]

Internet-Draft                 WebDAV Sync                  October 2010


     </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>
     <D:propstat>
       <D:prop>
         <D:getetag>"00003-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     <D:propstat>
       <D:prop>
         <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
       </D:prop>
       <D:status>HTTP/1.1 404 Not Found</D:status>
     </D:propstat>
     </D:response>
     <D:sync-token>1234</D:sync-token>
   </D:multistatus>


3.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 April 8, 2011                [Page 12]

Internet-Draft                 WebDAV Sync                  October 2010


   >> Request <<


   REPORT /home/cyrusdaboo/ HTTP/1.1
   Host: webdav.example.com
   Depth: 1
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:sync-collection xmlns:D="DAV:">
     <D:sync-token>1234</D:sync-token>
     <D:prop xmlns:R="urn:ns.example.com:boxschema">
       <D:getetag/>
       <R:bigbox/>
     </D:prop>
   </D:sync-collection>


































Daboo & Quillaud          Expires April 8, 2011                [Page 13]

Internet-Draft                 WebDAV Sync                  October 2010


   >> Response <<


   HTTP/1.1 207 Multi-Status
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D="DAV:">
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/file.xml</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00004-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     <D:propstat>
       <D:prop>
         <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
       </D:prop>
       <D:status>HTTP/1.1 404 Not Found</D:status>
     </D:propstat>
     </D:response>
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00002-abcd2"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     <D:propstat>
       <D:prop>
         <R:bigbox xmlns:R="urn:ns.example.com:boxschema"/>
       </D:prop>
       <D:status>HTTP/1.1 404 Not Found</D:status>
     </D:propstat>
     </D:response>
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
     <D:status>HTTP/1.1 404 Not Found</D:status>
     </D:response>
     <D:sync-token>1238</D:sync-token>
   </D:multistatus>



Daboo & Quillaud          Expires April 8, 2011                [Page 14]

Internet-Draft                 WebDAV Sync                  October 2010


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 April 8, 2011                [Page 15]

Internet-Draft                 WebDAV Sync                  October 2010


   >> Response <<


   HTTP/1.1 207 Multi-Status
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D="DAV:">
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00001-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:response>
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00002-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:response>
     <D:response>
       <D:href
   >http://webdav.example.com/home/cyrusdaboo/</D:href>
       <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
       <D:error><D:number-of-matches-within-limits/></D:error>
     </D:response>
     <D:sync-token>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 April 8, 2011                [Page 16]

Internet-Draft                 WebDAV Sync                  October 2010


   >> Request <<


   REPORT /home/cyrusdaboo/ HTTP/1.1
   Host: webdav.example.com
   Depth: 1
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:sync-collection xmlns:D="DAV:">
     <D:sync-token/>
     <D:limit>
       <D:nresults>1</D:nresults>
     </D:limit>
     <D:prop>
       <D:getetag/>
     </D:prop>
   </D:sync-collection>


   >> Response <<


   HTTP/1.1 207 Multi-Status
   Content-Type: text/xml; charset="utf-8"
   Content-Length: xxxx

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D="DAV:">
     <D:response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00001-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:response>
     <D:response>
       <D:href
   >http://webdav.example.com/home/cyrusdaboo/</D:href>
       <D:status>HTTP/1.1 507 Insufficient Storage</D:status>
       <D:error><D:number-of-matches-within-limits/></D:error>
     </D:response>
     <D:sync-token>1232</D:sync-token>
   </D:multistatus>



Daboo & Quillaud          Expires April 8, 2011                [Page 17]

Internet-Draft                 WebDAV Sync                  October 2010


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>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 April 8, 2011                [Page 18]

Internet-Draft                 WebDAV Sync                  October 2010


   getetag property and for a proprietary property.  The server responds
   with the items currently in the targeted collection.  The current
   synchronization token is also returned.

   The collection /home/cyrusdaboo/collection1/ exists and has one child
   resource which is also reported.  The collection /home/cyrusdaboo/
   collection2/ exists but has no child resources.  The collection
   /home/cyrusdaboo/shared/ is returned with a 405 status indicating
   that a collection exists but it is unable to report on changes within
   it in the scope of the current Depth:infinity report.  Instead the
   client can try a DAV:sync-collection report directly on the
   collection URI.

   >> 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
   >/home/cyrusdaboo/collection1/</D:href>
     <D:propstat>
       <D:prop>
         <D:getetag>"00001-abcd1"</D:getetag>
         <R:bigbox xmlns:R="urn:ns.example.com:boxschema">



Daboo & Quillaud          Expires April 8, 2011                [Page 19]

Internet-Draft                 WebDAV Sync                  October 2010


           <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>
         </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>"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
   >/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>



Daboo & Quillaud          Expires April 8, 2011                [Page 20]

Internet-Draft                 WebDAV Sync                  October 2010


       <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 405 Method Not Allowed</D:status>
     </D:response>
     <D:sync-token>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 text.

   Protected:  MUST be protected because this value is created and
      controlled by the server.

   COPY/MOVE behavior:  This property value is dependent on the final
      state of the destination resource, not the value of the property
      on the source resource.

   Description:  The DAV:sync-token property MUST be defined on all
      resources that support the DAV:sync-collection report.  It
      contains the value of the synchronization token as it would be
      returned by a DAV:sync-collection report on that resource at the
      same point in time.  It SHOULD NOT be returned by a PROPFIND DAV:
      allprop request (as defined in Section 14.2 of [RFC4918]).

   Definition:


   <!ELEMENT sync-token #PCDATA>


5.  XML Element Definitions







Daboo & Quillaud          Expires April 8, 2011                [Page 21]

Internet-Draft                 WebDAV Sync                  October 2010


5.1.  DAV:sync-collection XML Element

   Name:  sync-collection

   Namespace:  DAV:

   Purpose:  WebDAV report used to synchronize data between client and
      server.

   Description:  See Section 3.



   <!ELEMENT sync-collection (sync-token, DAV:limit?, DAV:prop)>

   <!-- DAV:limit defined in RFC 5323, Section 5.17 -->
   <!-- DAV:prop defined in RFC 4918, Section 14.18 -->


5.2.  DAV:sync-token XML Element

   Name:  sync-token

   Namespace:  DAV:

   Purpose:  The synchronization token provided by the server and
      returned by the client.

   Description:  See Section 3.



   <!ELEMENT sync-token CDATA>


5.3.  DAV:multistatus XML Element

   Name:  multistatus

   Namespace:  DAV:

   Purpose:  Extends the DAV:multistatus element to include
      synchronization details.

   Description:  See Section 3.






Daboo & Quillaud          Expires April 8, 2011                [Page 22]

Internet-Draft                 WebDAV Sync                  October 2010


   <!ELEMENT multistatus (DAV:response*, DAV:responsedescription?,
                          sync-token?) >

   <!-- DAV:multistatus originally defined in RFC 4918, Section 14.16
        but overridden here to add the DAV:sync-token element -->
   <!-- DAV:response defined in RFC 4918, Section 14.24 -->
   <!-- DAV:responsedescription defined in RFC 4918, Section 14.25 -->


6.  Security Considerations

   This extension does not introduce any new security concerns than
   those already described in HTTP and WebDAV.

7.  IANA Considerations

   This document does not require any actions on the part of IANA.

8.  Acknowledgments

   The following individuals contributed their ideas and support for
   writing this specification: Bernard Desruisseaux, Mike Douglass, Ciny
   Joy, Andrew McMillan, Julian Reschke, and Wilfredo Sanchez.  We would
   like to thank the Calendaring and Scheduling Consortium for
   facilitating interoperability testing for early implementations of
   this specification.

9.  References

9.1.  Normative References

   [RFC2119]                    Bradner, S., "Key words for use in RFCs
                                to Indicate Requirement Levels", BCP 14,
                                RFC 2119, March 1997.

   [RFC2616]                    Fielding, R., Gettys, J., Mogul, J.,
                                Frystyk, H., Masinter, L., Leach, P.,
                                and T. Berners-Lee, "Hypertext Transfer
                                Protocol -- HTTP/1.1", RFC 2616,
                                June 1999.

   [RFC3744]                    Clemm, G., Reschke, J., Sedlar, E., and
                                J. Whitehead, "Web Distributed Authoring
                                and Versioning (WebDAV)
                                Access Control Protocol", RFC 3744,
                                May 2004.

   [RFC4918]                    Dusseault, L., "HTTP Extensions for Web



Daboo & Quillaud          Expires April 8, 2011                [Page 23]

Internet-Draft                 WebDAV Sync                  October 2010


                                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]       Paoli, J., Yergeau, F., Bray, T.,
                                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>.

9.2.  Informative References

   [I-D.ietf-vcarddav-carddav]  Daboo, C., "vCard Extensions to WebDAV
                                (CardDAV)",
                                draft-ietf-vcarddav-carddav-10 (work in
                                progress), November 2009.

   [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.

Appendix A.  Change History (to be removed prior to publication as an
             RFC)

   Changes in -04:

   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.




Daboo & Quillaud          Expires April 8, 2011                [Page 24]

Internet-Draft                 WebDAV Sync                  October 2010


   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.

   2.  Fixed examples to properly include DAV:status in DAV:propstat

   3.  Switch to using XML conventions text from RFC5323.











Daboo & Quillaud          Expires April 8, 2011                [Page 25]

Internet-Draft                 WebDAV Sync                  October 2010


Authors' Addresses

   Cyrus Daboo
   Apple Inc.
   1 Infinite Loop
   Cupertino, CA  95014
   USA

   EMail: cyrus@daboo.name
   URI:   http://www.apple.com/


   Arnaud Quillaud
   Oracle Corporation
   180, Avenue de l'Europe
   Saint Ismier cedex,   38334
   France

   EMail: arnaud.quillaud@oracle.com
   URI:   http://www.oracle.com/































Daboo & Quillaud          Expires April 8, 2011                [Page 26]


Html markup produced by rfcmarkup 1.109, available from https://tools.ietf.org/tools/rfcmarkup/