idnits 2.17.1 draft-daboo-webdav-sync-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (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 (November 18, 2009) is 5273 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) == Outdated reference: A later version (-27) exists of draft-ietf-webdav-bind-26 Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 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 A. Quillaud 5 Expires: May 22, 2010 Sun Microsystems 6 November 18, 2009 8 Collection Synchronization for WebDAV 9 draft-daboo-webdav-sync-02 11 Abstract 13 This specification defines an extension to WebDAV that allows 14 efficient synchronization of the contents of a WebDAV collection. 16 Editorial Note (To be removed by RFC Editor before publication) 18 Please send comments to the Distributed Authoring and Versioning 19 (WebDAV) working group at , which may be 20 joined by sending a message with subject "subscribe" to 21 . Discussions of the WEBDAV 22 working group are archived at 23 . 25 Status of This Memo 27 This Internet-Draft is submitted to IETF in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF), its areas, and its working groups. Note that 32 other groups may also distribute working documents as Internet- 33 Drafts. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 The list of current Internet-Drafts can be accessed at 41 http://www.ietf.org/ietf/1id-abstracts.txt. 43 The list of Internet-Draft Shadow Directories can be accessed at 44 http://www.ietf.org/shadow.html. 46 This Internet-Draft will expire on May 22, 2010. 48 Copyright Notice 49 Copyright (c) 2009 IETF Trust and the persons identified as the 50 document authors. All rights reserved. 52 This document is subject to BCP 78 and the IETF Trust's Legal 53 Provisions Relating to IETF Documents 54 (http://trustee.ietf.org/license-info) in effect on the date of 55 publication of this document. Please review these documents 56 carefully, as they describe your rights and restrictions with respect 57 to this document. Code Components extracted from this document must 58 include Simplified BSD License text as described in Section 4.e of 59 the Trust Legal Provisions and are provided without warranty as 60 described in the BSD License. 62 This document may contain material from IETF Documents or IETF 63 Contributions published or made publicly available before November 64 10, 2008. The person(s) controlling the copyright in some of this 65 material may not have granted the IETF Trust the right to allow 66 modifications of such material outside the IETF Standards Process. 67 Without obtaining an adequate license from the person(s) controlling 68 the copyright in such materials, this document may not be modified 69 outside the IETF Standards Process, and derivative works of it may 70 not be created outside the IETF Standards Process, except to format 71 it for publication as an RFC or to translate it into languages other 72 than English. 74 Table of Contents 76 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 77 2. Conventions Used in This Document . . . . . . . . . . . . . . 3 78 3. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 4 79 4. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 4 80 4.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 4 81 4.2. DAV:sync-collection report . . . . . . . . . . . . . . . . 5 82 4.3. Types of changes reported . . . . . . . . . . . . . . . . 7 83 4.3.1. New resource . . . . . . . . . . . . . . . . . . . . . 7 84 4.3.2. Modified resource . . . . . . . . . . . . . . . . . . 7 85 4.3.3. Removed resource . . . . . . . . . . . . . . . . . . . 7 86 4.4. Example: Initial DAV:sync-collection REPORT . . . . . . . 8 87 4.5. Example: DAV:sync-collection Report with token . . . . . . 10 88 5. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 11 89 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 12 90 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 12 91 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 12 92 6.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 13 93 6.4. DAV:sync-response XML Element . . . . . . . . . . . . . . 13 94 7. Security Considerations . . . . . . . . . . . . . . . . . . . 14 95 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 96 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 14 97 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 98 10.1. Normative References . . . . . . . . . . . . . . . . . . . 14 99 10.2. Informative References . . . . . . . . . . . . . . . . . . 14 100 Appendix A. Change History (to be removed prior to 101 publication as an RFC) . . . . . . . . . . . . . . . 15 103 1. Introduction 105 WebDAV [RFC4918] defines the concept of 'collections' which are 106 hierarchical groupings of WebDAV resources on an HTTP [RFC2616] 107 server. Collections can be of arbitrary size and depth (i.e., 108 collections within collections). WebDAV clients that cache resource 109 content need a way to synchronize that data with the server (i.e., 110 detect what has changed and update their cache). This can currently 111 be done using a WebDAV PROPFIND request on a collection to list all 112 members of a collection along with their DAV:getetag property values, 113 which allows the client to determine which resources were changed, 114 added or deleted. However, this does not scale well to large 115 collections as the XML response to the PROPFIND request will grow 116 with the collection size. 118 This specification defines a new WebDAV report that results in the 119 server returning to the client only information about those resources 120 which have changed, are new or were deleted since a previous 121 execution of the report on the collection. 123 Additionally, a new property is added to collection resources that is 124 used to convey a "synchronization token" that is guaranteed to change 125 when resources within the collection have changed. 127 2. Conventions Used in This Document 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 134 3.2) as a purely notational convention. WebDAV request and response 135 bodies cannot be validated by a DTD due to the specific extensibility 136 rules defined in Section 17 of [RFC4918] and due to the fact that all 137 XML elements defined by this specification use the XML namespace name 138 "DAV:". In particular: 140 1. element names use the "DAV:" namespace, 142 2. element ordering is irrelevant unless explicitly stated, 144 3. extension elements (elements not already defined as valid child 145 elements) may be added anywhere, except when explicitly stated 146 otherwise, 148 4. extension attributes (attributes not already defined as valid for 149 this element) may be added anywhere, except when explicitly 150 stated otherwise. 152 When an XML element type in the "DAV:" namespace is referenced in 153 this document outside of the context of an XML fragment, the string 154 "DAV:" will be prefixed to the element type. 156 This document inherits, and sometimes extends, DTD productions from 157 Section 14 of [RFC4918]. 159 3. Open Issues 161 1. We are extending the multistatus response element in a 162 significant way. The DAV:sync-response differs from a regular 163 DAV:response because, in the case of a created or modified 164 resource, it contains both a DAV:status (201 for created, 200 for 165 modified) and a DAV:propstat. The DAV:response on the other hand 166 contains either a DAV:status or a DAV:propstat but not both. 167 Shall we define a DAV:multisyncstatus response element instead of 168 overloading DAV:multistatus ? 170 2. Do clients really need to be notified that a resource was created 171 versus modified ? They should be able to figure that out by 172 looking at the state of their current cache. If this information 173 is not necessary, the response would not need to contain a DAV: 174 status along with the DAV:propstat. This would allow the use of 175 a regular multistatus (simply extended with a sync-token 176 element). 178 4. WebDAV Synchronization 180 4.1. Overview 182 One way to synchronize data between two entities is to use some form 183 of synchronization token. The token defines the state of the data 184 being synchronized at a particular point in time. It can then be 185 used to determine what has changed since one point in time and 186 another. 188 This specification defines a new WebDAV report that is used to enable 189 client-server collection synchronization based on such a token. 191 In order to synchronize the contents of a collection between a server 192 and client, the server provides the client with a synchronization 193 token each time the synchronization report is executed. That token 194 represents the state of the data being synchronized at that point in 195 time. The client can then present that same token back to the server 196 at some later time and the server will return only those items that 197 are new, have changed or were deleted since that token was generated. 198 The server also returns a new token representing the new state at the 199 time the report was run. 201 Typically the first time a client connects to the server it will need 202 to be informed of the entire state of the collection (i.e., a full 203 list of all resources that are currently contained in the 204 collection). That is done by the client sending an empty token value 205 to the server. This indicates to the server that a full listing is 206 required. As an alternative, the client may choose to do its first 207 synchronization using some other mechanism on the collection (e.g. 208 some other form of batch resource information retrieval such as 209 PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those 210 defined in CalDAV [RFC4791] and CardDAV [I-D.ietf-vcarddav-carddav]) 211 and ask for the DAV:sync-token property to be returned. This 212 property (defined in Section 5) contains the same token that can be 213 used later on to issue a DAV:sync-collection report. 215 In some cases a server may only wish to maintain a limited amount of 216 history about changes to a collection. In that situation it will 217 return an error to the client when the client presents a token that 218 is "out of date". At that point the client has to fall back to 219 synchronizing the entire collection by re-running the report request 220 using an empty token value. ACL changes may also cause a token to 221 become invalid. 223 4.2. DAV:sync-collection report 225 This specification defines the DAV:sync-collection report. 227 If this report is implemented by a WebDAV server, then the server 228 MUST list the report in the "DAV:supported-report-set" property on 229 any collection supporting synchronization. 231 To implement the behavior for this report a server needs to keep 232 track of changes to any resources in a collection. This includes 233 noting the addition of new resources, changes to existing resources 234 and removal of resources (where "removal" could be the result of a 235 DELETE or MOVE WebDAV request). Only internal members of the 236 collection (as defined in [RFC4918]) are to be considered. The 237 server will track each change and provide a synchronization "token" 238 to the client that describes the state of the server at a specific 239 point in time. This "token" is returned as part of the response to 240 the "sync-collection" report. Clients include the last token they 241 got from the server in the next "sync-collection" report that they 242 execute and the server provides the changes from the previous state, 243 represented by the token, to the current state, represented by the 244 new token returned. 246 The synchronization token itself is an "opaque" string - i.e., the 247 actual string data has no specific meaning or syntax. A simple 248 implementation of such a token would be a numeric counter that counts 249 each change as it occurs and relates that change to the specific 250 object that changed. 252 Marshalling: 254 The request URI MUST be a collection. The request body MUST be a 255 DAV:sync-collection XML element (see Section 6.1), which MUST 256 contain one DAV:sync-token XML element, and optionally a DAV: 257 propstat XML element. 259 The request MUST include a Depth header with a value of "1". 261 The response body for a successful request MUST be a DAV: 262 multistatus XML element, which MUST contain one DAV:sync-token 263 element in addition to any DAV:sync-response elements. 265 The response body for a successful DAV:sync-collection report 266 request MUST contain a DAV:sync-response element for each resource 267 that was created, has changed or been deleted since the last 268 synchronization operation as specified by the DAV:sync-token 269 provided in the request. A given resource MUST appear only once 270 in the response. 272 The DAV:status element in each DAV:sync-response element is used 273 to indicate how the resource may have changed: 275 A status code of '201 Created' is used to indicate resources 276 that are new. 278 A status code of '200 OK' is used to indicate resources that 279 have changed. 281 A status code of '404 Not Found' is used to indicate resources 282 that have been removed. 284 The conditions under which each type of change may occur is 285 further described in Section 4.3. 287 Preconditions: 289 (DAV:valid-sync-token): The DAV:sync-token element value MUST map 290 to a valid token previously returned by the server. A token may 291 become invalid as the result of being "out of date" (out of the 292 range of change history maintained by the server), or for other 293 reasons (e.g. collection deleted, then recreated, ACL changes, 294 etc...). 296 Postconditions: 298 None. 300 4.3. Types of changes reported 302 Three types of resource state changes can be returned by the DAV: 303 sync-collection report (new, modified, removed). This section 304 further defines under which condition each of them shall be used. It 305 also clarifies the case where a resource may have undergone multiple 306 changes in between two synchronizations. 308 4.3.1. New resource 310 A resource MUST be reported as new if it has been mapped directly 311 under the target collection since the request sync token was 312 generated. This includes resources that have been mapped as the 313 result of a COPY, MOVE or BIND ([I-D.ietf-webdav-bind]) operation. 314 This also includes collection resources that have been created. 316 In the case where a mapping between a resource and the target 317 collection was removed, then a new mapping with the same URI created, 318 the new resource MUST be reported as new, while the old resource MUST 319 NOT be reported as removed. For example, if a resource was deleted, 320 then recreated using the same URI, it should be reported as a new 321 resource only. 323 A resource MAY be reported as new if the user issuing the request was 324 granted access to this resource, due to access control changes. 326 4.3.2. Modified resource 328 A resource MUST be reported as modified if it is not reported as new 329 and if its entity tag value (defined in [RFC2616]) has changed since 330 the request sync token was generated. In other words, the new 331 resource change indicator takes precedence over the modified resource 332 change indicator. 334 Collection resources MUST NOT be returned as modified. Instead 335 clients are expected to synchronize changes in child collection 336 resources on an individual basis. 338 4.3.3. Removed resource 340 A resource MUST be reported as removed if its mapping under the 341 target collection has been removed since the request sync token was 342 generated, and it has not been re-mapped since it was removed. This 343 includes resources that have been unmapped as the result of a MOVE or 344 UNBIND ([I-D.ietf-webdav-bind]) operation. This also includes 345 collection resources that have been removed. 347 If a resource was created (and possibly modified), then removed in 348 between two synchronizations, it MUST NOT be reported as new, 349 modified or removed. 351 A resource MAY be reported as removed if the user issuing the request 352 has no longer access to this resource, due to access control changes. 354 4.4. Example: Initial DAV:sync-collection REPORT 356 In this example, the client is making its first synchronization 357 request to the server, so the DAV:sync-token element in the request 358 is empty. It also asks for the DAV:getetag property. The server 359 responds with the items currently in the targeted collection 360 (indicating that they are 'new' via the '201 Created' status code). 361 The current synchronization token is also returned. 363 >> Request << 365 REPORT /home/cyrusdaboo/ HTTP/1.1 366 Host: webdav.example.com 367 Depth: 1 368 Content-Type: text/xml; charset="utf-8" 369 Content-Length: xxxx 371 372 373 374 375 376 377 378 >> Response << 380 HTTP/1.1 207 Multi-Status 381 Content-Type: text/xml; charset="utf-8" 382 Content-Length: xxxx 384 385 386 387 http://webdav.example.com/home/cyrusdaboo/test.doc 389 HTTP/1.1 201 Created 390 391 392 "00001-abcd1" 393 394 HTTP/1.1 200 OK 395 396 397 398 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 400 HTTP/1.1 201 Created 401 402 403 "00002-abcd1" 404 405 HTTP/1.1 200 OK 406 407 408 409 http://webdav.example.com/home/cyrusdaboo/calendar.ics 411 HTTP/1.1 201 Created 412 413 414 "00003-abcd1" 415 416 HTTP/1.1 200 OK 417 418 419 1234 420 422 4.5. Example: DAV:sync-collection Report with token 424 In this example, the client is making a synchronization request to 425 the server and is using the DAV:sync-token element returned from the 426 last report it ran on this collection. The server responds listing 427 the items that have been added, changed or removed. The (new) 428 current synchronization token is also returned. 430 >> Request << 432 REPORT /home/cyrusdaboo/ HTTP/1.1 433 Host: webdav.example.com 434 Depth: 1 435 Content-Type: text/xml; charset="utf-8" 436 Content-Length: xxxx 438 439 440 1234 441 442 443 444 445 >> Response << 447 HTTP/1.1 207 Multi-Status 448 Content-Type: text/xml; charset="utf-8" 449 Content-Length: xxxx 451 452 453 454 http://webdav.example.com/home/cyrusdaboo/file.xml 456 HTTP/1.1 201 Created 457 458 459 "00004-abcd1" 460 461 HTTP/1.1 200 OK 462 463 464 465 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 467 HTTP/1.1 200 OK 468 469 470 "00002-abcd2" 471 472 HTTP/1.1 200 OK 473 474 475 476 http://webdav.example.com/home/cyrusdaboo/test.doc 478 HTTP/1.1 404 Not Found 479 480 1238 481 483 5. DAV:sync-token Property 485 Name: sync-token 487 Namespace: DAV: 489 Purpose: Contains the value of the synchronization token as it would 490 be returned by a DAV:sync-collection report. 492 Value: Any text. 494 Protected: MUST be protected because this value is created and 495 controlled by the server. 497 COPY/MOVE behavior: This property value is dependent on the final 498 state of the destination resource, not the value of the property 499 on the source resource. 501 Description: The DAV:sync-token property MUST be defined on all 502 resources that support the DAV:sync-collection report. It 503 contains the value of the synchronization token as it would be 504 returned by a DAV:sync-collection report on that resource at the 505 same point in time. It SHOULD NOT be returned by a PROPFIND DAV: 506 allprop request (as defined in [RFC4918]). 508 Definition: 510 512 6. XML Element Definitions 514 6.1. DAV:sync-collection XML Element 516 Name: sync-collection 518 Namespace: DAV: 520 Purpose: WebDAV report used to synchronize data between client and 521 server. 523 Description: See Section 4. 525 527 6.2. DAV:sync-token XML Element 528 Name: sync-token 530 Namespace: DAV: 532 Purpose: The synchronization token provided by the server and 533 returned by the client. 535 Description: See Section 4. 537 539 6.3. DAV:multistatus XML Element 541 Name: multistatus 543 Namespace: DAV: 545 Purpose: Extends the DAV:multistatus element to include 546 synchronization details. 548 Description: See Section 4. 550 554 6.4. DAV:sync-response XML Element 556 Name: sync-response 558 Namespace: DAV: 560 Purpose: Contains the synchronization results returned by the 561 server. 563 Description: See Section 4. 565 567 7. Security Considerations 569 This extension does not introduce any new security concerns than 570 those already described in HTTP and WebDAV. 572 8. IANA Considerations 574 This document does not require any actions on the part of IANA. 576 9. Acknowledgments 578 The following individuals contributed their ideas and support for 579 writing this specification: Bernard Desruisseaux, Mike Douglass, Ciny 580 Joy and Julian Reschke. 582 10. References 584 10.1. Normative References 586 [RFC2119] Bradner, S., "Key words for use in RFCs 587 to Indicate Requirement Levels", BCP 14, 588 RFC 2119, March 1997. 590 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 591 Frystyk, H., Masinter, L., Leach, P., 592 and T. Berners-Lee, "Hypertext Transfer 593 Protocol -- HTTP/1.1", RFC 2616, 594 June 1999. 596 [RFC4918] Dusseault, L., "HTTP Extensions for Web 597 Distributed Authoring and Versioning 598 (WebDAV)", RFC 4918, June 2007. 600 [W3C.REC-xml-20081126] Sperberg-McQueen, C., Yergeau, F., Bray, 601 T., Paoli, J., and E. Maler, "Extensible 602 Markup Language (XML) 1.0 (Fifth 603 Edition)", World Wide Web Consortium 604 Recommendation REC-xml-20081126, 605 November 2008, . 608 10.2. Informative References 610 [I-D.ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to WebDAV 611 (CardDAV)", 612 draft-ietf-vcarddav-carddav-10 (work in 613 progress), November 2009. 615 [I-D.ietf-webdav-bind] Clemm, G., Crawford, J., Reschke, J., 616 and J. Whitehead, "Binding Extensions to 617 Web Distributed Authoring and Versioning 618 (WebDAV)", draft-ietf-webdav-bind-26 619 (work in progress), September 2009. 621 [RFC4791] Daboo, C., Desruisseaux, B., and L. 622 Dusseault, "Calendaring Extensions to 623 WebDAV (CalDAV)", RFC 4791, March 2007. 625 [RFC5323] Reschke, J., Reddy, S., Davis, J., and 626 A. Babich, "Web Distributed Authoring 627 and Versioning (WebDAV) SEARCH", 628 RFC 5323, November 2008. 630 Appendix A. Change History (to be removed prior to publication as an 631 RFC) 633 Changes in -02: 635 1. Added definition of sync-token WebDAV property. 637 2. Added references to SEARCH, CalDAV, CardDAV as alternative ways 638 to first synchronize a collection. 640 3. Added section defining under which condition each state change 641 (new, modified, removed) should be reported. Added reference to 642 BIND. 644 4. Incorporated feedback from Julian Reschke and Ciny Joy. 646 5. More details on the use of the DAV:valid-sync-token precondition. 648 Changes in -01: 650 1. Updated to 4918 reference. 652 2. Fixed examples to properly include DAV:status in DAV:propstat 654 3. Switch to using XML conventions text from RFC5323. 656 Authors' Addresses 658 Cyrus Daboo 659 Apple Inc. 660 1 Infinite Loop 661 Cupertino, CA 95014 662 USA 664 EMail: cyrus@daboo.name 665 URI: http://www.apple.com/ 667 Arnaud Quillaud 668 Sun Microsystems 669 180, Avenue de l'Europe 670 Saint Ismier cedex, 38334 671 France 673 EMail: arnaud.quillaud@sun.com 674 URI: http://www.sun.com/