[Docs] [txt|pdf|xml|html] [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                           March 9, 2009
Expires: September 10, 2009


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

Status of This Memo

   This Internet-Draft is submitted to IETF in full conformance with the
   provisions of BCP 78 and BCP 79.  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.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on September 10, 2009.

Copyright Notice

   Copyright (c) 2009 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



Daboo                  Expires September 10, 2009               [Page 1]

Internet-Draft                 WebDAV Sync                    March 2009


   Provisions Relating to IETF Documents in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.

Abstract

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

Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Conventions Used in This Document  . . . . . . . . . . . . . .  3
   3.  Open Issues  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   4.  WebDAV Synchronization REPORT  . . . . . . . . . . . . . . . .  4
     4.1.  Overview . . . . . . . . . . . . . . . . . . . . . . . . .  4
     4.2.  REPORT defined . . . . . . . . . . . . . . . . . . . . . .  5
     4.3.  Example: Initial DAV:sync-collection REPORT  . . . . . . .  7
     4.4.  Example: DAV:sync-collection Report with token . . . . . .  9
   5.  XML Element Definitions  . . . . . . . . . . . . . . . . . . . 10
     5.1.  DAV:sync-collection XML Element  . . . . . . . . . . . . . 10
       5.1.1.  DAV:sync-token XML Element . . . . . . . . . . . . . . 11
       5.1.2.  DAV:multistatus XML Element  . . . . . . . . . . . . . 11
       5.1.3.  DAV:sync-response XML Element  . . . . . . . . . . . . 12
   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 12
   7.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 12
   8.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 12
   9.  Normative References . . . . . . . . . . . . . . . . . . . . . 12
   Appendix A.  Change History (to be removed prior to
                publication as an RFC)  . . . . . . . . . . . . . . . 13




















Daboo                  Expires September 10, 2009               [Page 2]

Internet-Draft                 WebDAV Sync                    March 2009


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 HTTP ETag values, which
   allows the client to determine which resources were changed, added or
   deleted.  However this does not scale well to large collections as
   the XML response to the PROPFIND response will grow with the
   collection size.

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

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

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                  Expires September 10, 2009               [Page 3]

Internet-Draft                 WebDAV Sync                    March 2009


   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.  Open Issues

   1.  Should we try and discriminate between changes to the body of a
       resource and changes to the properties?

   2.  If we indicate a property change, should we return the list of
       properties that changed on each resource (propnames NOT values)?

   3.  Should we provide a way to indicate that a 'new' resource is new
       in the collection as a result of a COPY or MOVE from another
       location, as opposed to being created?

   4.  Should we provide a way to indicate that a 'deleted' resource was
       removed from the collection as a result of a MOVE to another
       location, as opposed to being actually deleted?

   5.  How should ACLs be handled? e.g. a resource is visible to a user
       at one point in time, then its <read> privilege is removed.
       Should the resource be marked as having been deleted when next
       synchronized?

   6.  Do we want a special indicator for a resource that was deleted
       and then re-created, as opposed to just indicating that the
       resource was 'changed'?

4.  WebDAV Synchronization REPORT

4.1.  Overview

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

   HTTP already defines a synchronization token in the form of an entity
   tag which is attached to a resource.  However, the entity tag is not
   always required to be 'strong' and thus cannot be relied on
   absolutely as a valid synchronization indicator.  In addition, there
   is no concept of an entity tag for a collection's contents.




Daboo                  Expires September 10, 2009               [Page 4]

Internet-Draft                 WebDAV Sync                    March 2009


   The is specification defines a new WebDAV REPORT that is used to
   enable client-server collection synchronization.

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

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

   In some cases a server may only wish to maintain a limited amount of
   history about changes to a collection.  In that situation it will
   return an error to the client when the client presents a token that
   is "out of date".  At that point the client has to fall back to
   synchronizing the entire collection by re-running the report request
   using an empty token value.

4.2.  REPORT defined

   This specification defines the DAV:sync-collection REPORT.

   If this REPORT is implemented by a WebDAV server, then the server
   MUST list the REPORT in the "DAV:supported-report-set" property on
   any collection supporting synchronization.  If the report is not
   available, clients MUST NOT attempt to execute one.

   To implement the behavior for this REPORT a server needs to keep
   track of changes to any resources in a collection.  This includes
   noting the addition of new resources, changes to existing resources
   and removal of resources (where "removal" could be the result of a
   DELETE or MOVE WebDAV request).  The server will track each change
   and provide a synchronization "token" to the client that describes
   the state of the server at a specific point in time.  This "token" is
   returned as part of the response to the "sync-collection" report.
   Clients include the last token they got from the server in the next
   "sync-collection" report that they execute and the server provides
   the changes from the previous state represented by the token to the
   current state, represented by the new token returned.



Daboo                  Expires September 10, 2009               [Page 5]

Internet-Draft                 WebDAV Sync                    March 2009


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

   Marshalling:

      The request URI MUST be a collection.  The "Depth" header MUST be
      ignored by the server and SHOULD NOT be sent by the client.  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 optionally a DAV:propstat XML element.

      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 any DAV:sync-response elements.

      The response body for a successful DAV:sync-collection REPORT
      request MUST contain a DAV:sync-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.

      The DAV:status element in each DAV:sync-response element is used
      to indicate how the resource may have changed:

         A status code of '201 Created' is used to indicate resources
         that are new.

         A status code of '200 OK' is used to indicate resources that
         have changed.

         A status code of '404 Not Found' is used to indicate resources
         that have been removed.

   Preconditions:

      (DAV:valid-sync-token): The DAV:sync-token element value MUST map
      to a valid token previously returned by the server;

   Postconditions:

      None.







Daboo                  Expires September 10, 2009               [Page 6]

Internet-Draft                 WebDAV Sync                    March 2009


4.3.  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, and it also asks for the DAV:getetag property.  The server
   responds with the items currently in the targeted collection
   (indicating that they are 'new' via the '201 Created' status code).
   The current synchronization token is also returned.

   >> Request <<


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

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



























Daboo                  Expires September 10, 2009               [Page 7]

Internet-Draft                 WebDAV Sync                    March 2009


   >> Response <<


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

   <?xml version="1.0" encoding="utf-8" ?>
   <D:multistatus xmlns:D="DAV:">
     <D:sync-response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/test.doc</D:href>
     <D:status>HTTP/1.1 201 Created</D:status>
     <D:propstat>
       <D:prop>
         <D:getetag>"00001-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:sync-response>
     <D:sync-response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/vcard.vcf</D:href>
     <D:status>HTTP/1.1 201 Created</D:status>
     <D:propstat>
       <D:prop>
         <D:getetag>"00002-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:sync-response>
     <D:sync-response>
     <D:href
   >http://webdav.example.com/home/cyrusdaboo/calendar.ics</D:href>
     <D:status>HTTP/1.1 201 Created</D:status>
     <D:propstat>
       <D:prop>
         <D:getetag>"00003-abcd1"</D:getetag>
       </D:prop>
       <D:status>HTTP/1.1 200 OK</D:status>
     </D:propstat>
     </D:sync-response>
     <D:sync-token>1234</D:sync-token>
   </D:multistatus>







Daboo                  Expires September 10, 2009               [Page 8]

Internet-Draft                 WebDAV Sync                    March 2009


4.4.  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>1234</D:sync-token>
     <D:prop>
       <D:getetag/>
     </D:prop>
   </D:sync-collection>




























Daboo                  Expires September 10, 2009               [Page 9]

Internet-Draft                 WebDAV Sync                    March 2009


   >> Response <<


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

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


5.  XML Element Definitions

5.1.  DAV:sync-collection XML Element








Daboo                  Expires September 10, 2009              [Page 10]

Internet-Draft                 WebDAV Sync                    March 2009


   Name:  sync-collection

   Namespace:  DAV:

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

   Description:  See Section 4.



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


5.1.1.  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 4.



   <!ELEMENT sync-token CDATA>


5.1.2.  DAV:multistatus XML Element

   Name:  multistatus

   Namespace:  DAV:

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

   Description:  See Section 4.



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





Daboo                  Expires September 10, 2009              [Page 11]

Internet-Draft                 WebDAV Sync                    March 2009


5.1.3.  DAV:sync-response XML Element

   Name:  sync-response

   Namespace:  DAV:

   Purpose:  Contains the synchronization results returned by the
      server.

   Description:  See Section 4.



   <!ELEMENT sync-response (DAV:href, DAV:status, DAV:propstat?)>


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,
   Arnaud Quillaud, and Julian Reschke.

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

   [RFC4918]               Dusseault, L., "HTTP Extensions for Web
                           Distributed Authoring and Versioning
                           (WebDAV)", RFC 4918, June 2007.

   [W3C.REC-xml-20081126]  Paoli, J., Yergeau, F., Bray, T., Sperberg-
                           McQueen, C., and E. Maler, "Extensible Markup



Daboo                  Expires September 10, 2009              [Page 12]

Internet-Draft                 WebDAV Sync                    March 2009


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

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

   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.

Author's Address

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

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

























Daboo                  Expires September 10, 2009              [Page 13]


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