idnits 2.17.1 draft-daboo-webdav-sync-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (March 9, 2009) is 5526 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft Apple, Inc. 4 Intended status: Standards Track March 9, 2009 5 Expires: September 10, 2009 7 Collection Synchronization for WebDAV 8 draft-daboo-webdav-sync-01 10 Status of This Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. This document may contain material 14 from IETF Documents or IETF Contributions published or made publicly 15 available before November 10, 2008. The person(s) controlling the 16 copyright in some of this material may not have granted the IETF 17 Trust the right to allow modifications of such material outside the 18 IETF Standards Process. Without obtaining an adequate license from 19 the person(s) controlling the copyright in such materials, this 20 document may not be modified outside the IETF Standards Process, and 21 derivative works of it may not be created outside the IETF Standards 22 Process, except to format it for publication as an RFC or to 23 translate it into languages other than English. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF), its areas, and its working groups. Note that 27 other groups may also distribute working documents as Internet- 28 Drafts. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/ietf/1id-abstracts.txt. 38 The list of Internet-Draft Shadow Directories can be accessed at 39 http://www.ietf.org/shadow.html. 41 This Internet-Draft will expire on September 10, 2009. 43 Copyright Notice 45 Copyright (c) 2009 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents in effect on the date of 50 publication of this document (http://trustee.ietf.org/license-info). 51 Please review these documents carefully, as they describe your rights 52 and restrictions with respect to this document. 54 Abstract 56 This specification defines an extension to WebDAV that allows 57 efficient synchronization of the contents of a WebDAV collection. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 63 3. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 4. WebDAV Synchronization REPORT . . . . . . . . . . . . . . . . 4 65 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 4.2. REPORT defined . . . . . . . . . . . . . . . . . . . . . . 5 67 4.3. Example: Initial DAV:sync-collection REPORT . . . . . . . 7 68 4.4. Example: DAV:sync-collection Report with token . . . . . . 9 69 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 10 70 5.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 10 71 5.1.1. DAV:sync-token XML Element . . . . . . . . . . . . . . 11 72 5.1.2. DAV:multistatus XML Element . . . . . . . . . . . . . 11 73 5.1.3. DAV:sync-response XML Element . . . . . . . . . . . . 12 74 6. Security Considerations . . . . . . . . . . . . . . . . . . . 12 75 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 76 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 12 77 9. Normative References . . . . . . . . . . . . . . . . . . . . . 12 78 Appendix A. Change History (to be removed prior to 79 publication as an RFC) . . . . . . . . . . . . . . . 13 81 1. Introduction 83 WebDAV [RFC4918] defines the concept of 'collections' which are 84 hierarchical groupings of WebDAV resources on an HTTP [RFC2616] 85 server. Collections can be of arbitrary size and depth (i.e., 86 collections within collections). WebDAV clients that cache resource 87 content need a way to synchronize that data with the server (i.e., 88 detect what has changed and update their cache). This can currently 89 be done using a WebDAV PROPFIND request on a collection to list all 90 members of a collection along with their HTTP ETag values, which 91 allows the client to determine which resources were changed, added or 92 deleted. However this does not scale well to large collections as 93 the XML response to the PROPFIND response will grow with the 94 collection size. 96 This specification defines a new WebDAV REPORT that results in the 97 server returning to the client only information about those resources 98 which have changed, are new or were deleted since a previous 99 execution of the REPORT on the collection. 101 Additionally, a new property is added to collection resources that is 102 used to convey a "synchronization token" that is guaranteed to change 103 when the contents of the collection have changed. 105 2. Conventions Used in This Document 107 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 108 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 109 document are to be interpreted as described in [RFC2119]. 111 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 112 3.2) as a purely notational convention. WebDAV request and response 113 bodies cannot be validated by a DTD due to the specific extensibility 114 rules defined in Section 17 of [RFC4918] and due to the fact that all 115 XML elements defined by this specification use the XML namespace name 116 "DAV:". In particular: 118 1. element names use the "DAV:" namespace, 120 2. element ordering is irrelevant unless explicitly stated, 122 3. extension elements (elements not already defined as valid child 123 elements) may be added anywhere, except when explicitly stated 124 otherwise, 126 4. extension attributes (attributes not already defined as valid for 127 this element) may be added anywhere, except when explicitly 128 stated otherwise. 130 When an XML element type in the "DAV:" namespace is referenced in 131 this document outside of the context of an XML fragment, the string 132 "DAV:" will be prefixed to the element type. 134 This document inherits, and sometimes extends, DTD productions from 135 Section 14 of [RFC4918]. 137 3. Open Issues 139 1. Should we try and discriminate between changes to the body of a 140 resource and changes to the properties? 142 2. If we indicate a property change, should we return the list of 143 properties that changed on each resource (propnames NOT values)? 145 3. Should we provide a way to indicate that a 'new' resource is new 146 in the collection as a result of a COPY or MOVE from another 147 location, as opposed to being created? 149 4. Should we provide a way to indicate that a 'deleted' resource was 150 removed from the collection as a result of a MOVE to another 151 location, as opposed to being actually deleted? 153 5. How should ACLs be handled? e.g. a resource is visible to a user 154 at one point in time, then its privilege is removed. 155 Should the resource be marked as having been deleted when next 156 synchronized? 158 6. Do we want a special indicator for a resource that was deleted 159 and then re-created, as opposed to just indicating that the 160 resource was 'changed'? 162 4. WebDAV Synchronization REPORT 164 4.1. Overview 166 One way to synchronize data between two entities is to use some form 167 of synchronization token. This defines the state of the data being 168 synchronized at a particular point in time. That token can then be 169 used to determine what has changed since one point in time and 170 another. 172 HTTP already defines a synchronization token in the form of an entity 173 tag which is attached to a resource. However, the entity tag is not 174 always required to be 'strong' and thus cannot be relied on 175 absolutely as a valid synchronization indicator. In addition, there 176 is no concept of an entity tag for a collection's contents. 178 The is specification defines a new WebDAV REPORT that is used to 179 enable client-server collection synchronization. 181 In order to synchronize the contents of a collection between a server 182 and client, the server provides the client with a synchronization 183 token each time the synchronization REPORT is executed. That token 184 represents the state of the data being synchronized at that point in 185 time. The client can then present that same token back to the server 186 at some later time and the server will return only those items that 187 are new, have changed or were deleted since that token was generated. 188 The server also returns a new token representing the new state at the 189 time the REPORT was run. 191 Typically the first time a client connects to the server it will need 192 to be informed of the entire state of the collection (i.e., a full 193 list of all resources that are currently contained in the 194 collection). That is done by the client sending an empty token value 195 to the server. This indicates to the server that a full listing is 196 required. 198 In some cases a server may only wish to maintain a limited amount of 199 history about changes to a collection. In that situation it will 200 return an error to the client when the client presents a token that 201 is "out of date". At that point the client has to fall back to 202 synchronizing the entire collection by re-running the report request 203 using an empty token value. 205 4.2. REPORT defined 207 This specification defines the DAV:sync-collection REPORT. 209 If this REPORT is implemented by a WebDAV server, then the server 210 MUST list the REPORT in the "DAV:supported-report-set" property on 211 any collection supporting synchronization. If the report is not 212 available, clients MUST NOT attempt to execute one. 214 To implement the behavior for this REPORT a server needs to keep 215 track of changes to any resources in a collection. This includes 216 noting the addition of new resources, changes to existing resources 217 and removal of resources (where "removal" could be the result of a 218 DELETE or MOVE WebDAV request). The server will track each change 219 and provide a synchronization "token" to the client that describes 220 the state of the server at a specific point in time. This "token" is 221 returned as part of the response to the "sync-collection" report. 222 Clients include the last token they got from the server in the next 223 "sync-collection" report that they execute and the server provides 224 the changes from the previous state represented by the token to the 225 current state, represented by the new token returned. 227 The synchronization token itself is an "opaque" string - i.e., the 228 actual string data has no specific meaning or syntax. A simple 229 implementation of such a token would be a numeric counter that counts 230 each change as it occurs and relates that change to the specific 231 object that changed. 233 Marshalling: 235 The request URI MUST be a collection. The "Depth" header MUST be 236 ignored by the server and SHOULD NOT be sent by the client. The 237 request body MUST be a DAV:sync-collection XML element (see 238 Section 5.1, which MUST contain one DAV:sync-token XML element, 239 and optionally a DAV:propstat XML element. 241 The response body for a successful request MUST be a DAV: 242 multistatus XML element, which MUST contain one DAV:sync-token 243 element in addition to any DAV:sync-response elements. 245 The response body for a successful DAV:sync-collection REPORT 246 request MUST contain a DAV:sync-response element for each resource 247 that was created, has changed or been deleted since the last 248 synchronization operation as specified by the DAV:sync-token 249 provided in the request. 251 The DAV:status element in each DAV:sync-response element is used 252 to indicate how the resource may have changed: 254 A status code of '201 Created' is used to indicate resources 255 that are new. 257 A status code of '200 OK' is used to indicate resources that 258 have changed. 260 A status code of '404 Not Found' is used to indicate resources 261 that have been removed. 263 Preconditions: 265 (DAV:valid-sync-token): The DAV:sync-token element value MUST map 266 to a valid token previously returned by the server; 268 Postconditions: 270 None. 272 4.3. Example: Initial DAV:sync-collection REPORT 274 In this example, the client is making its first synchronization 275 request to the server, so the DAV:sync-token element in the request 276 is empty, and it also asks for the DAV:getetag property. The server 277 responds with the items currently in the targeted collection 278 (indicating that they are 'new' via the '201 Created' status code). 279 The current synchronization token is also returned. 281 >> Request << 283 REPORT /home/cyrusdaboo/ HTTP/1.1 284 Host: webdav.example.com 285 Content-Type: text/xml; charset="utf-8" 286 Content-Length: xxxx 288 289 290 291 292 293 294 295 >> Response << 297 HTTP/1.1 207 Multi-Status 298 Content-Type: text/xml; charset="utf-8" 299 Content-Length: xxxx 301 302 303 304 http://webdav.example.com/home/cyrusdaboo/test.doc 306 HTTP/1.1 201 Created 307 308 309 "00001-abcd1" 310 311 HTTP/1.1 200 OK 312 313 314 315 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 317 HTTP/1.1 201 Created 318 319 320 "00002-abcd1" 321 322 HTTP/1.1 200 OK 323 324 325 326 http://webdav.example.com/home/cyrusdaboo/calendar.ics 328 HTTP/1.1 201 Created 329 330 331 "00003-abcd1" 332 333 HTTP/1.1 200 OK 334 335 336 1234 337 339 4.4. Example: DAV:sync-collection Report with token 341 In this example, the client is making a synchronization request to 342 the server and is using the DAV:sync-token element returned from the 343 last report it ran on this collection. The server responds listing 344 the items that have been added, changed or removed. The (new) 345 current synchronization token is also returned. 347 >> Request << 349 REPORT /home/cyrusdaboo/ HTTP/1.1 350 Host: webdav.example.com 351 Content-Type: text/xml; charset="utf-8" 352 Content-Length: xxxx 354 355 356 1234 357 358 359 360 361 >> Response << 363 HTTP/1.1 207 Multi-Status 364 Content-Type: text/xml; charset="utf-8" 365 Content-Length: xxxx 367 368 369 370 http://webdav.example.com/home/cyrusdaboo/file.xml 372 HTTP/1.1 201 Created 373 374 375 "00004-abcd1" 376 377 HTTP/1.1 200 OK 378 379 380 381 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 383 HTTP/1.1 200 OK 384 385 386 "00002-abcd2" 387 388 HTTP/1.1 200 OK 389 390 391 392 http://webdav.example.com/home/cyrusdaboo/test.doc 394 HTTP/1.1 404 Not Found 395 396 1238 397 399 5. XML Element Definitions 401 5.1. DAV:sync-collection XML Element 402 Name: sync-collection 404 Namespace: DAV: 406 Purpose: WebDAV report used to synchronize data between client and 407 server. 409 Description: See Section 4. 411 413 5.1.1. DAV:sync-token XML Element 415 Name: sync-token 417 Namespace: DAV: 419 Purpose: The synchronization token provided by the server and 420 returned by the client. 422 Description: See Section 4. 424 426 5.1.2. DAV:multistatus XML Element 428 Name: multistatus 430 Namespace: DAV: 432 Purpose: Extends the DAV:multistatus element to include 433 synchronization details. 435 Description: See Section 4. 437 441 5.1.3. DAV:sync-response XML Element 443 Name: sync-response 445 Namespace: DAV: 447 Purpose: Contains the synchronization results returned by the 448 server. 450 Description: See Section 4. 452 454 6. Security Considerations 456 This extension does not introduce any new security concerns than 457 those already described in HTTP and WebDAV. 459 7. IANA Considerations 461 This document does not require any actions on the part of IANA. 463 8. Acknowledgments 465 The following individuals contributed their ideas and support for 466 writing this specification: Bernard Desruisseaux, Mike Douglass, 467 Arnaud Quillaud, and Julian Reschke. 469 9. Normative References 471 [RFC2119] Bradner, S., "Key words for use in RFCs to 472 Indicate Requirement Levels", BCP 14, 473 RFC 2119, March 1997. 475 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, 476 H., Masinter, L., Leach, P., and T. Berners- 477 Lee, "Hypertext Transfer Protocol -- 478 HTTP/1.1", RFC 2616, June 1999. 480 [RFC4918] Dusseault, L., "HTTP Extensions for Web 481 Distributed Authoring and Versioning 482 (WebDAV)", RFC 4918, June 2007. 484 [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., Sperberg- 485 McQueen, C., and E. Maler, "Extensible Markup 486 Language (XML) 1.0 (Fifth Edition)", World 487 Wide Web Consortium Recommendation REC-xml- 488 20081126, November 2008, 489 . 491 Appendix A. Change History (to be removed prior to publication as an 492 RFC) 494 Changes in -01: 496 1. Updated to 4918 reference. 498 2. Fixed examples to properly include DAV:status in DAV:propstat 500 3. Switch to using XML conventions text from RFC5323. 502 Author's Address 504 Cyrus Daboo 505 Apple Inc. 506 1 Infinite Loop 507 Cupertino, CA 95014 508 USA 510 EMail: cyrus@daboo.name 511 URI: http://www.apple.com/