idnits 2.17.1 draft-daboo-webdav-sync-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 (October 5, 2010) is 4952 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: 1 error (**), 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 A. Quillaud 5 Expires: April 8, 2011 Oracle 6 October 5, 2010 8 Collection Synchronization for WebDAV 9 draft-daboo-webdav-sync-04 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 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). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 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 This Internet-Draft will expire on April 8, 2011. 42 Copyright Notice 44 Copyright (c) 2010 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 This document may contain material from IETF Documents or IETF 58 Contributions published or made publicly available before November 59 10, 2008. The person(s) controlling the copyright in some of this 60 material may not have granted the IETF Trust the right to allow 61 modifications of such material outside the IETF Standards Process. 62 Without obtaining an adequate license from the person(s) controlling 63 the copyright in such materials, this document may not be modified 64 outside the IETF Standards Process, and derivative works of it may 65 not be created outside the IETF Standards Process, except to format 66 it for publication as an RFC or to translate it into languages other 67 than English. 69 Table of Contents 71 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 72 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 73 3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5 74 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 75 3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6 76 3.3. Depth behavior . . . . . . . . . . . . . . . . . . . . . . 7 77 3.4. Types of Changes Reported on Initial Synchronization . . . 8 78 3.5. Types of Changes Reported on Subsequent 79 Synchronizations . . . . . . . . . . . . . . . . . . . . . 8 80 3.5.1. Changed Resource . . . . . . . . . . . . . . . . . . . 8 81 3.5.2. Removed Resource . . . . . . . . . . . . . . . . . . . 9 82 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 9 83 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 10 84 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 11 85 3.9. Example: DAV:sync-collection Report with Token . . . . . . 12 86 3.10. Example: Initial DAV:sync-collection Report with 87 Truncation . . . . . . . . . . . . . . . . . . . . . . . . 15 88 3.11. Example: Initial DAV:sync-collection Report with Limit . . 16 89 3.12. Example: DAV:sync-collection Report with Unsupported 90 Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 18 91 3.13. Example: Depth:infinity initial DAV:sync-collection 92 Report . . . . . . . . . . . . . . . . . . . . . . . . . . 18 93 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 21 94 5. XML Element Definitions . . . . . . . . . . . . . . . . . . . 21 95 5.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 22 96 5.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 22 97 5.3. DAV:multistatus XML Element . . . . . . . . . . . . . . . 22 98 6. Security Considerations . . . . . . . . . . . . . . . . . . . 23 99 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 23 100 8. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 23 101 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23 102 9.1. Normative References . . . . . . . . . . . . . . . . . . . 23 103 9.2. Informative References . . . . . . . . . . . . . . . . . . 24 104 Appendix A. Change History (to be removed prior to 105 publication as an RFC) . . . . . . . . . . . . . . . 24 107 1. Introduction 109 WebDAV [RFC4918] defines the concept of 'collections' which are 110 hierarchical groupings of WebDAV resources on an HTTP [RFC2616] 111 server. Collections can be of arbitrary size and depth (i.e., 112 collections within collections). WebDAV clients that cache resource 113 content need a way to synchronize that data with the server (i.e., 114 detect what has changed and update their cache). This can currently 115 be done using a WebDAV PROPFIND request on a collection to list all 116 members of a collection along with their DAV:getetag property values, 117 which allows the client to determine which resources were changed, 118 added or deleted. However, this does not scale well to large 119 collections as the XML response to the PROPFIND request will grow 120 with the collection size. 122 This specification defines a new WebDAV report that results in the 123 server returning to the client only information about those resources 124 which have changed, are new or were deleted since a previous 125 execution of the report on the collection. 127 Additionally, a new property is added to collection resources that is 128 used to convey a "synchronization token" that is guaranteed to change 129 when resources within the collection have changed. 131 2. Conventions Used in This Document 133 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 134 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 135 document are to be interpreted as described in [RFC2119]. 137 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 138 3.2) as a purely notational convention. WebDAV request and response 139 bodies cannot be validated by a DTD due to the specific extensibility 140 rules defined in Section 17 of [RFC4918] and due to the fact that all 141 XML elements defined by this specification use the XML namespace name 142 "DAV:". In particular: 144 1. element names use the "DAV:" namespace, 146 2. element ordering is irrelevant unless explicitly stated, 148 3. extension elements (elements not already defined as valid child 149 elements) may be added anywhere, except when explicitly stated 150 otherwise, 152 4. extension attributes (attributes not already defined as valid for 153 this element) may be added anywhere, except when explicitly 154 stated otherwise. 156 When an XML element type in the "DAV:" namespace is referenced in 157 this document outside of the context of an XML fragment, the string 158 "DAV:" will be prefixed to the element type. 160 This document inherits, and sometimes extends, DTD productions from 161 Section 14 of [RFC4918]. 163 3. WebDAV Synchronization 165 3.1. Overview 167 One way to synchronize data between two entities is to use some form 168 of synchronization token. The token defines the state of the data 169 being synchronized at a particular point in time. It can then be 170 used to determine what has changed since one point in time and 171 another. 173 This specification defines a new WebDAV report that is used to enable 174 client-server collection synchronization based on such a token. 176 In order to synchronize the contents of a collection between a server 177 and client, the server provides the client with a synchronization 178 token each time the synchronization report is executed. That token 179 represents the state of the data being synchronized at that point in 180 time. The client can then present that same token back to the server 181 at some later time and the server will return only those items that 182 are new, have changed or were deleted since that token was generated. 183 The server also returns a new token representing the new state at the 184 time the report was run. 186 Typically, the first time a client connects to the server it will 187 need to be informed of the entire state of the collection (i.e., a 188 full list of all resources that are currently contained in the 189 collection). That is done by the client sending an empty token value 190 to the server. This indicates to the server that a full listing is 191 required. 193 As an alternative, the client might choose to do its first 194 synchronization using some other mechanism on the collection (e.g. 195 some other form of batch resource information retrieval such as 196 PROPFIND, SEARCH [RFC5323], or specialized REPORTs such as those 197 defined in CalDAV [RFC4791] and CardDAV [I-D.ietf-vcarddav-carddav]) 198 and ask for the DAV:sync-token property to be returned. This 199 property (defined in Section 4) contains the same token that can be 200 used later on to issue a DAV:sync-collection report. 202 In some cases a server might only wish to maintain a limited amount 203 of history about changes to a collection. In that situation it will 204 return an error to the client when the client presents a token that 205 is "out of date". At that point the client has to fall back to 206 synchronizing the entire collection by re-running the report request 207 using an empty token value. 209 3.2. DAV:sync-collection Report 211 If the DAV:sync-collection report is implemented by a WebDAV server, 212 then the server MUST list the report in the "DAV:supported-report- 213 set" property on any collection supporting synchronization. 215 To implement the behavior for this report a server needs to keep 216 track of changes to any member resources in a collection (as defined 217 in Section 3 of [RFC4918]). This includes noting the addition of new 218 resources, changes to existing resources and removal of resources. 219 The server will track each change and provide a synchronization 220 "token" to the client that describes the state of the server at a 221 specific point in time. This "token" is returned as part of the 222 response to the "sync-collection" report. Clients include the last 223 token they got from the server in the next "sync-collection" report 224 that they execute and the server provides the changes from the 225 previous state, represented by the token, to the current state, 226 represented by the new token returned. 228 The synchronization token itself is an "opaque" string - i.e., the 229 actual string data has no specific meaning or syntax. For example, a 230 simple implementation of such a token could be a numeric counter that 231 counts each change as it occurs and relates that change to the 232 specific object that changed. 234 Marshalling: 236 The request URI MUST identify a collection. The request body MUST 237 be a DAV:sync-collection XML element (see Section 5.1), which MUST 238 contain one DAV:sync-token XML element, and one DAV:prop XML 239 element, and MAY contain a DAV:limit XML element. 241 The request MUST include a Depth header with a value of "1" or 242 "infinity". 244 The response body for a successful request MUST be a DAV: 245 multistatus XML element, which MUST contain one DAV:sync-token 246 element in addition to one DAV: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. A given resource MUST appear only once 250 in the response. 252 The content of each DAV:response element differs depending on how 253 the resource was altered: 255 For resources that have changed (i.e., are new or have been 256 modified) the DAV:response MUST contain at least one DAV: 257 propstat element and MUST NOT contain any DAV:status element. 259 For resources that have been removed, the DAV:response MUST 260 contain one DAV:status with a value set to '404 Not Found' and 261 MUST NOT contain any DAV:propstat element. 263 For child collection resources that are unable to support the 264 DAV:sync-collection report, the DAV:response MUST contain one 265 DAV:status with a value set to '405 Method Not Allowed' and 266 MUST NOT contain any DAV:propstat element. 268 The conditions under which each type of change can occur is 269 further described in Section 3.5. 271 Preconditions: 273 (DAV:valid-sync-token): The DAV:sync-token element value MUST map 274 to a valid token previously returned by the server. A token may 275 become invalid as the result of being "out of date" (out of the 276 range of change history maintained by the server), or for other 277 reasons (e.g. collection deleted, then recreated, access control 278 changes, etc...). 280 Postconditions: 282 (DAV:number-of-matches-within-limits): The number of changes 283 reported in the response must fall within the client specified 284 limit. This condition might be triggered if a client requests a 285 limit on the number of responses (as per Section 3.7) but the 286 server is unable to truncate the result set at or below that 287 limit. 289 3.3. Depth behavior 291 The DAV:sync-collection report supports both Depth:1 and Depth: 292 infinity request headers. 294 o When the client specifies Depth:1, only additions, changes or 295 removals of immediate children of the collection specified as the 296 request URI are reported. 298 o When the client specifies Depth:infinity, additions, changes or 299 removals of any child resource of the collection specified as the 300 request URI are reported, provided child collections themselves 301 also support the DAV:sync-collection report. 303 o DAV:sync-token values returned by the server are not specific to 304 the value of the Depth header used in the request. As such 305 clients MAY use a DAV:sync-token value from a request with one 306 Depth value for a similar request with a different Depth value, 307 however the utility of this is limited. 309 Note that when a server supports Depth:infinity reports, it might not 310 be possible to synchronize some child collections within the 311 collection targeted by the report. In such cases the server is 312 REQUIRED to return a DAV:response with status '405 Method Not 313 Allowed' to inform the client that alternative methods have to be 314 used to synchronize the contents of those collections. The 405 315 response MUST be sent once, when the collection is first reported to 316 the client. 318 3.4. Types of Changes Reported on Initial Synchronization 320 When the DAV:sync-collection request contains an empty DAV:sync-token 321 element, the server MUST return all members of the collection (taking 322 account of Depth header requirements as per Section 3.3, and optional 323 truncation of results set as per Section 3.6) and it MUST NOT return 324 any removed resources. All types of resource (collection or non- 325 collection) MUST be reported. 327 3.5. Types of Changes Reported on Subsequent Synchronizations 329 When the DAV:sync-collection request contains a valid value for the 330 DAV:sync-token element, two types of resource state changes can be 331 returned (changed or removed). This section defines what triggers 332 each of these to be returned. It also clarifies the case where a 333 resource may have undergone multiple changes between two 334 synchronization report requests. In all cases, the Depth header 335 requirements as per Section 3.3, and optional truncation of results 336 set as per Section 3.6, are taken into account by the server. 338 3.5.1. Changed Resource 340 A resource MUST be reported as changed if it has been mapped as an 341 member of the target collection since the request sync-token was 342 generated. This includes resources that have been mapped as the 343 result of a COPY, MOVE or BIND [RFC5842] request. All types of 344 resource (collection or non-collection) MUST be reported. 346 In the case where a mapping between a resource and the target 347 collection was removed, then a new mapping with the same URI created, 348 the new resource MUST be reported as changed while the old resource 349 MUST NOT be reported as removed. For example, if a resource was 350 deleted, then recreated using the same URI, it should be reported as 351 a changed resource only. 353 A resource MUST be reported as changed if its entity tag value 354 (defined in Section 3.11 of [RFC2616]) has changed since the request 355 sync-token was generated. 357 A resource MAY be reported as changed if the user issuing the request 358 was granted access to this resource, due to access control changes. 360 Collection resources MUST be returned as changed if they have an 361 entity tag associated with them and that entity tag changes. There 362 is no guarantee that changes to members of a collection will result 363 in a change in any entity tag of that collection, so clients cannot 364 rely on a series of Depth:1 reports at multiple levels to track all 365 changes within a collection. Instead Depth:infinity has to be used. 367 3.5.2. Removed Resource 369 A resource MUST be reported as removed if its mapping under the 370 target collection has been removed since the request sync-token was 371 generated, and it has not been re-mapped since it was removed. This 372 includes resources that have been unmapped as the result of a MOVE or 373 UNBIND [RFC5842] operation. This also includes collection resources 374 that have been removed, including ones that themselves do not support 375 the DAV:sync-collection report. 377 If a resource was created (and possibly modified), then removed 378 between two synchronization report requests, it MUST be reported as 379 removed. This ensures that a client that creates a resource is 380 informed of the removal of the resource, if the removal occurs before 381 the client has had a chance to request a synchronization report. 383 A resource MAY be reported as removed if the user issuing the request 384 no longer has access to this resource, due to access control changes. 386 For a Depth:infinity report where a collection is removed, the server 387 MUST NOT report the removal of any resources that are members of the 388 removed collection. Clients MUST assume that if a collection is 389 reported as being removed, then all internal members of that 390 collection have also been removed. 392 3.6. Truncation of Results 394 A server MAY limit the number of resources in a response, for 395 example, to limit the amount of work expended in processing a 396 request, or as the result of an explicit limit set by the client. If 397 the result set is truncated, the response MUST use status code 207, 398 return a DAV:multistatus response body, and indicate a status of 507 399 (Insufficient Storage) for the request URI. That DAV:response 400 element SHOULD include a DAV:error element with the DAV:number-of- 401 matches-within-limits precondition, as defined in [RFC3744] (Section 402 9.2). DAV:response elements for all the changes being reported are 403 also included. 405 When truncation occurs, the DAV:sync-token value returned in the 406 response MUST represent the correct state for the partial set of 407 changes returned. That allows the client to use the returned DAV: 408 sync-token to fetch the next set of changes. In this way the client 409 can effectively "page" through the entire set of changes in a 410 consistent manner. 412 Clients MUST handle the 507 status on the request-URI in the response 413 to the report. 415 For example, consider a server that records changes using a 416 monotonically increasing integer to represent a "revision number" and 417 uses that quantity as the DAV:sync-token value. Assume the last DAV: 418 sync-token used by the client was "10", and since then 15 additional 419 changes have occurred. If the client executes a DAV:sync-collection 420 request with a DAV:sync-token of "10", without a limit the server 421 would return 15 DAV:response elements and a DAV:sync-token with value 422 "25". But if the server choose to limit responses to at most 10 423 changes, then it would return only 10 DAV:response elements and a 424 DAV:sync-token with value "20", together with an addition DAV: 425 response element for the request-URI with a status code of 507. 426 Subsequently, the client can re-issue the request with the DAV:sync- 427 token value returned from the server and fetch the remaining 5 428 changes. 430 3.7. Limiting Results 432 A client can limit the number of results returned by the server 433 through use of the DAV:limit element ([RFC5323], Section 5.17) in the 434 request body. This is useful when clients have limited space or 435 bandwidth for the results. If a server is unable to truncate the 436 result at or below the requested number, then it MUST fail the 437 request with a DAV:number-of-matches-within-limits post-condition 438 error. When the results can be correctly limited by the server, the 439 server MUST follow the rules above for indicating a result set 440 truncation to the client. 442 3.8. Example: Initial DAV:sync-collection Report 444 In this example, the client is making its first synchronization 445 request to the server, so the DAV:sync-token element in the request 446 is empty. It also asks for the DAV:getetag property and for a 447 proprietary property. The server responds with the items currently 448 in the targeted collection. The current synchronization token is 449 also returned. 451 >> Request << 453 REPORT /home/cyrusdaboo/ HTTP/1.1 454 Host: webdav.example.com 455 Depth: 1 456 Content-Type: text/xml; charset="utf-8" 457 Content-Length: xxxx 459 460 461 462 463 464 465 466 468 >> Response << 470 HTTP/1.1 207 Multi-Status 471 Content-Type: text/xml; charset="utf-8" 472 Content-Length: xxxx 474 475 476 477 http://webdav.example.com/home/cyrusdaboo/test.doc 479 480 481 "00001-abcd1" 482 483 Box type A 484 485 486 HTTP/1.1 200 OK 488 489 490 491 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 493 494 495 "00002-abcd1" 496 497 HTTP/1.1 200 OK 498 499 500 501 502 503 HTTP/1.1 404 Not Found 504 505 506 507 http://webdav.example.com/home/cyrusdaboo/calendar.ics 509 510 511 "00003-abcd1" 512 513 HTTP/1.1 200 OK 514 515 516 517 518 519 HTTP/1.1 404 Not Found 520 521 522 1234 523 525 3.9. Example: DAV:sync-collection Report with Token 527 In this example, the client is making a synchronization request to 528 the server and is using the DAV:sync-token element returned from the 529 last report it ran on this collection. The server responds, listing 530 the items that have been added, changed or removed. The (new) 531 current synchronization token is also returned. 533 >> Request << 535 REPORT /home/cyrusdaboo/ HTTP/1.1 536 Host: webdav.example.com 537 Depth: 1 538 Content-Type: text/xml; charset="utf-8" 539 Content-Length: xxxx 541 542 543 1234 544 545 546 547 548 549 >> Response << 551 HTTP/1.1 207 Multi-Status 552 Content-Type: text/xml; charset="utf-8" 553 Content-Length: xxxx 555 556 557 558 http://webdav.example.com/home/cyrusdaboo/file.xml 560 561 562 "00004-abcd1" 563 564 HTTP/1.1 200 OK 565 566 567 568 569 570 HTTP/1.1 404 Not Found 571 572 573 574 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 576 577 578 "00002-abcd2" 579 580 HTTP/1.1 200 OK 581 582 583 584 585 586 HTTP/1.1 404 Not Found 587 588 589 590 http://webdav.example.com/home/cyrusdaboo/test.doc 592 HTTP/1.1 404 Not Found 593 594 1238 595 597 3.10. Example: Initial DAV:sync-collection Report with Truncation 599 In this example, the client is making its first synchronization 600 request to the server, so the DAV:sync-token element in the request 601 is empty. It also asks for the DAV:getetag property. The server 602 responds with the items currently in the targeted collection, but 603 truncated at two items. The synchronization token for the truncated 604 result set is returned. 606 >> Request << 608 REPORT /home/cyrusdaboo/ HTTP/1.1 609 Host: webdav.example.com 610 Depth: 1 611 Content-Type: text/xml; charset="utf-8" 612 Content-Length: xxxx 614 615 616 617 618 619 620 621 >> Response << 623 HTTP/1.1 207 Multi-Status 624 Content-Type: text/xml; charset="utf-8" 625 Content-Length: xxxx 627 628 629 630 http://webdav.example.com/home/cyrusdaboo/test.doc 632 633 634 "00001-abcd1" 635 636 HTTP/1.1 200 OK 637 638 639 640 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 642 643 644 "00002-abcd1" 645 646 HTTP/1.1 200 OK 647 648 649 650 http://webdav.example.com/home/cyrusdaboo/ 652 HTTP/1.1 507 Insufficient Storage 653 654 655 1233 656 658 3.11. Example: Initial DAV:sync-collection Report with Limit 660 In this example, the client is making its first synchronization 661 request to the server, so the DAV:sync-token element in the request 662 is empty. It requests a limit of 1 for the responses returned by the 663 server. It also asks for the DAV:getetag property. The server 664 responds with the items currently in the targeted collection, but 665 truncated at one item. The synchronization token for the truncated 666 result set is returned. 668 >> Request << 670 REPORT /home/cyrusdaboo/ HTTP/1.1 671 Host: webdav.example.com 672 Depth: 1 673 Content-Type: text/xml; charset="utf-8" 674 Content-Length: xxxx 676 677 678 679 680 1 681 682 683 684 685 687 >> Response << 689 HTTP/1.1 207 Multi-Status 690 Content-Type: text/xml; charset="utf-8" 691 Content-Length: xxxx 693 694 695 696 http://webdav.example.com/home/cyrusdaboo/test.doc 698 699 700 "00001-abcd1" 701 702 HTTP/1.1 200 OK 703 704 705 706 http://webdav.example.com/home/cyrusdaboo/ 708 HTTP/1.1 507 Insufficient Storage 709 710 711 1232 712 714 3.12. Example: DAV:sync-collection Report with Unsupported Limit 716 In this example, the client is making a synchronization request to 717 the server with a valid DAV:sync-token element value. It requests a 718 limit of 100 for the responses returned by the server. It also asks 719 for the DAV:getetag property. The server is unable to limit the 720 results to the maximum specified by the client, so it responds with a 721 507 status code and appropriate post-condition error code. 723 >> Request << 725 REPORT /home/cyrusdaboo/ HTTP/1.1 726 Host: webdav.example.com 727 Depth: 1 728 Content-Type: text/xml; charset="utf-8" 729 Content-Length: xxxx 731 732 733 1232 734 735 100 736 737 738 739 740 742 >> Response << 744 HTTP/1.1 507 Insufficient Storage 745 Content-Type: text/xml; charset="utf-8" 746 Content-Length: xxxx 748 749 750 751 753 3.13. Example: Depth:infinity initial DAV:sync-collection Report 755 In this example, the client is making its first synchronization 756 request to the server, so the DAV:sync-token element in the request 757 is empty, and it is using Depth:infinity. It also asks for the DAV: 759 getetag property and for a proprietary property. The server responds 760 with the items currently in the targeted collection. The current 761 synchronization token is also returned. 763 The collection /home/cyrusdaboo/collection1/ exists and has one child 764 resource which is also reported. The collection /home/cyrusdaboo/ 765 collection2/ exists but has no child resources. The collection 766 /home/cyrusdaboo/shared/ is returned with a 405 status indicating 767 that a collection exists but it is unable to report on changes within 768 it in the scope of the current Depth:infinity report. Instead the 769 client can try a DAV:sync-collection report directly on the 770 collection URI. 772 >> Request << 774 REPORT /home/cyrusdaboo/ HTTP/1.1 775 Host: webdav.example.com 776 Depth: 1 777 Content-Type: text/xml; charset="utf-8" 778 Content-Length: xxxx 780 781 782 783 784 785 786 787 789 >> Response << 791 HTTP/1.1 207 Multi-Status 792 Content-Type: text/xml; charset="utf-8" 793 Content-Length: xxxx 795 796 797 798 /home/cyrusdaboo/collection1/ 800 801 802 "00001-abcd1" 803 804 Box type A 805 806 807 HTTP/1.1 200 OK 808 809 810 811 /home/cyrusdaboo/collection1/test.doc 813 814 815 "00001-abcd1" 816 817 Box type A 818 819 820 HTTP/1.1 200 OK 821 822 823 824 /home/cyrusdaboo/collection2/ 826 827 828 "00002-abcd1" 829 830 HTTP/1.1 200 OK 831 832 833 834 835 836 HTTP/1.1 404 Not Found 837 838 839 840 /home/cyrusdaboo/calendar.ics 842 843 844 "00003-abcd1" 845 846 HTTP/1.1 200 OK 847 848 849 850 851 852 HTTP/1.1 404 Not Found 853 854 855 856 /home/cyrusdaboo/shared/ 858 HTTP/1.1 405 Method Not Allowed 859 860 1234 861 863 4. DAV:sync-token Property 865 Name: sync-token 867 Namespace: DAV: 869 Purpose: Contains the value of the synchronization token as it would 870 be returned by a DAV:sync-collection report. 872 Value: Any text. 874 Protected: MUST be protected because this value is created and 875 controlled by the server. 877 COPY/MOVE behavior: This property value is dependent on the final 878 state of the destination resource, not the value of the property 879 on the source resource. 881 Description: The DAV:sync-token property MUST be defined on all 882 resources that support the DAV:sync-collection report. It 883 contains the value of the synchronization token as it would be 884 returned by a DAV:sync-collection report on that resource at the 885 same point in time. It SHOULD NOT be returned by a PROPFIND DAV: 886 allprop request (as defined in Section 14.2 of [RFC4918]). 888 Definition: 890 892 5. XML Element Definitions 893 5.1. DAV:sync-collection XML Element 895 Name: sync-collection 897 Namespace: DAV: 899 Purpose: WebDAV report used to synchronize data between client and 900 server. 902 Description: See Section 3. 904 906 907 909 5.2. DAV:sync-token XML Element 911 Name: sync-token 913 Namespace: DAV: 915 Purpose: The synchronization token provided by the server and 916 returned by the client. 918 Description: See Section 3. 920 922 5.3. DAV:multistatus XML Element 924 Name: multistatus 926 Namespace: DAV: 928 Purpose: Extends the DAV:multistatus element to include 929 synchronization details. 931 Description: See Section 3. 933 936 938 939 941 6. Security Considerations 943 This extension does not introduce any new security concerns than 944 those already described in HTTP and WebDAV. 946 7. IANA Considerations 948 This document does not require any actions on the part of IANA. 950 8. Acknowledgments 952 The following individuals contributed their ideas and support for 953 writing this specification: Bernard Desruisseaux, Mike Douglass, Ciny 954 Joy, Andrew McMillan, Julian Reschke, and Wilfredo Sanchez. We would 955 like to thank the Calendaring and Scheduling Consortium for 956 facilitating interoperability testing for early implementations of 957 this specification. 959 9. References 961 9.1. Normative References 963 [RFC2119] Bradner, S., "Key words for use in RFCs 964 to Indicate Requirement Levels", BCP 14, 965 RFC 2119, March 1997. 967 [RFC2616] Fielding, R., Gettys, J., Mogul, J., 968 Frystyk, H., Masinter, L., Leach, P., 969 and T. Berners-Lee, "Hypertext Transfer 970 Protocol -- HTTP/1.1", RFC 2616, 971 June 1999. 973 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and 974 J. Whitehead, "Web Distributed Authoring 975 and Versioning (WebDAV) 976 Access Control Protocol", RFC 3744, 977 May 2004. 979 [RFC4918] Dusseault, L., "HTTP Extensions for Web 980 Distributed Authoring and Versioning 981 (WebDAV)", RFC 4918, June 2007. 983 [RFC5323] Reschke, J., Reddy, S., Davis, J., and 984 A. Babich, "Web Distributed Authoring 985 and Versioning (WebDAV) SEARCH", 986 RFC 5323, November 2008. 988 [W3C.REC-xml-20081126] Paoli, J., Yergeau, F., Bray, T., 989 Sperberg-McQueen, C., and E. Maler, 990 "Extensible Markup Language (XML) 1.0 991 (Fifth Edition)", World Wide Web 992 Consortium Recommendation REC-xml- 993 20081126, November 2008, . 996 9.2. Informative References 998 [I-D.ietf-vcarddav-carddav] Daboo, C., "vCard Extensions to WebDAV 999 (CardDAV)", 1000 draft-ietf-vcarddav-carddav-10 (work in 1001 progress), November 2009. 1003 [RFC4791] Daboo, C., Desruisseaux, B., and L. 1004 Dusseault, "Calendaring Extensions to 1005 WebDAV (CalDAV)", RFC 4791, March 2007. 1007 [RFC5842] Clemm, G., Crawford, J., Reschke, J., 1008 and J. Whitehead, "Binding Extensions to 1009 Web Distributed Authoring and Versioning 1010 (WebDAV)", RFC 5842, April 2010. 1012 Appendix A. Change History (to be removed prior to publication as an 1013 RFC) 1015 Changes in -04: 1017 1. Depth:infinity support added. 1019 2. Collection resources are now reported as changed if they have a 1020 valid entity tag associated with them. 1022 Changes in -03: 1024 1. Changed D:propstat to D:prop in marshalling. 1026 2. Added request for dead property in examples. 1028 3. Made D:prop mandatory in request so that D:response always 1029 contains at least one D:propstat as per WebDAV definition. 1031 4. Removed DAV:status from response when resource is created/ 1032 modified, thus allowing to get rid of DAV:sync-response in favor 1033 of a regular DAV:response. As a consequence, there is no longer 1034 any difference in the report between created and modified 1035 resources. 1037 5. Resource created, then removed between 2 sync MUST be returned as 1038 removed. 1040 6. Added ability for server to truncate results and indicate such to 1041 the client. 1043 7. Added ability for client to request the server to limit the 1044 result set. 1046 Changes in -02: 1048 1. Added definition of sync-token WebDAV property. 1050 2. Added references to SEARCH, CalDAV, CardDAV as alternative ways 1051 to first synchronize a collection. 1053 3. Added section defining under which condition each state change 1054 (new, modified, removed) should be reported. Added reference to 1055 BIND. 1057 4. Incorporated feedback from Julian Reschke and Ciny Joy. 1059 5. More details on the use of the DAV:valid-sync-token precondition. 1061 Changes in -01: 1063 1. Updated to 4918 reference. 1065 2. Fixed examples to properly include DAV:status in DAV:propstat 1067 3. Switch to using XML conventions text from RFC5323. 1069 Authors' Addresses 1071 Cyrus Daboo 1072 Apple Inc. 1073 1 Infinite Loop 1074 Cupertino, CA 95014 1075 USA 1077 EMail: cyrus@daboo.name 1078 URI: http://www.apple.com/ 1080 Arnaud Quillaud 1081 Oracle Corporation 1082 180, Avenue de l'Europe 1083 Saint Ismier cedex, 38334 1084 France 1086 EMail: arnaud.quillaud@oracle.com 1087 URI: http://www.oracle.com/