idnits 2.17.1 draft-daboo-webdav-sync-08.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 (January 30, 2012) is 4469 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: August 2, 2012 Oracle 6 January 30, 2012 8 Collection Synchronization for WebDAV 9 draft-daboo-webdav-sync-08 11 Abstract 13 This specification defines an extension to Web Distributed Authoring 14 and Versioning (WebDAV) that allows efficient synchronization of the 15 contents of a WebDAV collection. 17 Editorial Note (To be removed by RFC Editor before publication) 19 Please send comments to the Distributed Authoring and Versioning 20 (WebDAV) working group at , which may be 21 joined by sending a message with subject "subscribe" to 22 . Discussions of the WEBDAV 23 working group are archived at 24 . 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on August 2, 2012. 43 Copyright Notice 45 Copyright (c) 2012 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 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 This document may contain material from IETF Documents or IETF 59 Contributions published or made publicly available before November 60 10, 2008. The person(s) controlling the copyright in some of this 61 material may not have granted the IETF Trust the right to allow 62 modifications of such material outside the IETF Standards Process. 63 Without obtaining an adequate license from the person(s) controlling 64 the copyright in such materials, this document may not be modified 65 outside the IETF Standards Process, and derivative works of it may 66 not be created outside the IETF Standards Process, except to format 67 it for publication as an RFC or to translate it into languages other 68 than English. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 73 2. Conventions Used in This Document . . . . . . . . . . . . . . 4 74 3. WebDAV Synchronization . . . . . . . . . . . . . . . . . . . . 5 75 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 76 3.2. DAV:sync-collection Report . . . . . . . . . . . . . . . . 6 77 3.3. Depth behavior . . . . . . . . . . . . . . . . . . . . . . 8 78 3.4. Types of Changes Reported on Initial Synchronization . . . 9 79 3.5. Types of Changes Reported on Subsequent 80 Synchronizations . . . . . . . . . . . . . . . . . . . . . 9 81 3.5.1. Changed Member . . . . . . . . . . . . . . . . . . . . 10 82 3.5.2. Removed Member . . . . . . . . . . . . . . . . . . . . 10 83 3.6. Truncation of Results . . . . . . . . . . . . . . . . . . 11 84 3.7. Limiting Results . . . . . . . . . . . . . . . . . . . . . 12 85 3.8. Example: Initial DAV:sync-collection Report . . . . . . . 12 86 3.9. Example: DAV:sync-collection Report with Token . . . . . . 14 87 3.10. Example: Initial DAV:sync-collection Report with 88 Truncation . . . . . . . . . . . . . . . . . . . . . . . . 16 89 3.11. Example: Initial DAV:sync-collection Report with Limit . . 17 90 3.12. Example: DAV:sync-collection Report with Unsupported 91 Limit . . . . . . . . . . . . . . . . . . . . . . . . . . 19 92 3.13. Example: DAV:sync-level set to infinite, initial 93 DAV:sync-collection Report . . . . . . . . . . . . . . . . 20 94 4. DAV:sync-token Property . . . . . . . . . . . . . . . . . . . 23 95 5. DAV:sync-token Use with If Header . . . . . . . . . . . . . . 23 96 5.1. Example: If Pre-Condition with PUT . . . . . . . . . . . . 23 97 5.2. Example: If Pre-Condition with MKCOL . . . . . . . . . . . 24 98 6. XML Element Definitions . . . . . . . . . . . . . . . . . . . 25 99 6.1. DAV:sync-collection XML Element . . . . . . . . . . . . . 25 100 6.2. DAV:sync-token XML Element . . . . . . . . . . . . . . . . 25 101 6.3. DAV:sync-level XML Element . . . . . . . . . . . . . . . . 26 102 6.4. DAV:multistatus XML Element . . . . . . . . . . . . . . . 26 103 7. Security Considerations . . . . . . . . . . . . . . . . . . . 26 104 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 105 9. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 106 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 27 107 10.1. Normative References . . . . . . . . . . . . . . . . . . . 27 108 10.2. Informative References . . . . . . . . . . . . . . . . . . 28 109 Appendix A. Backwards Compatible Handling of Depth . . . . . . . 28 110 Appendix B. Example of a Client Synchronization Approach . . . . 28 111 Appendix C. Change History (to be removed prior to 112 publication as an RFC) . . . . . . . . . . . . . . . 30 114 1. Introduction 116 WebDAV [RFC4918] defines the concept of 'collections' which are 117 hierarchical groupings of WebDAV resources on an HTTP [RFC2616] 118 server. Collections can be of arbitrary size and depth (i.e., 119 collections within collections). WebDAV clients that cache resource 120 content need a way to synchronize that data with the server (i.e., 121 detect what has changed and update their cache). This can currently 122 be done using a WebDAV PROPFIND request on a collection to list all 123 members of a collection along with their DAV:getetag property values, 124 which allows the client to determine which were changed, added or 125 deleted. However, this does not scale well to large collections as 126 the XML response to the PROPFIND request will grow with the 127 collection size. 129 This specification defines a new WebDAV report that results in the 130 server returning to the client only information about those member 131 URLs that were added or deleted, or whose mapped resources were 132 changed, since a previous execution of the report on the collection. 134 Additionally, a new property is added to collection resources that is 135 used to convey a "synchronization token" that is guaranteed to change 136 when the collection's member URLs or their mapped resources have 137 changed. 139 2. Conventions Used in This Document 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in [RFC2119]. 145 This document uses XML DTD fragments ([W3C.REC-xml-20081126], Section 146 3.2) as a purely notational convention. WebDAV request and response 147 bodies cannot be validated by a DTD due to the specific extensibility 148 rules defined in Section 17 of [RFC4918] and due to the fact that all 149 XML elements defined by this specification use the XML namespace name 150 "DAV:". In particular: 152 1. element names use the "DAV:" namespace, 154 2. element ordering is irrelevant unless explicitly stated, 156 3. extension elements (elements not already defined as valid child 157 elements) may be added anywhere, except when explicitly stated 158 otherwise, 160 4. extension attributes (attributes not already defined as valid for 161 this element) may be added anywhere, except when explicitly 162 stated otherwise. 164 When an XML element type in the "DAV:" namespace is referenced in 165 this document outside of the context of an XML fragment, the string 166 "DAV:" will be prefixed to the element type. 168 This document inherits, and sometimes extends, DTD productions from 169 Section 14 of [RFC4918]. 171 3. WebDAV Synchronization 173 3.1. Overview 175 One way to synchronize data between two entities is to use some form 176 of synchronization token. The token defines the state of the data 177 being synchronized at a particular point in time. It can then be 178 used to determine what has changed between one point in time and 179 another. 181 This specification defines a new WebDAV report that is used to enable 182 client-server collection synchronization based on such a token. 184 In order to synchronize the contents of a collection between a server 185 and client, the server provides the client with a synchronization 186 token each time the synchronization report is executed. That token 187 represents the state of the data being synchronized at that point in 188 time. The client can then present that same token back to the server 189 at some later time and the server will return only those items that 190 are new, have changed or were deleted since that token was generated. 191 The server also returns a new token representing the new state at the 192 time the report was run. 194 Typically, the first time a client connects to the server it will 195 need to be informed of the entire state of the collection (i.e., a 196 full list of all member URLs that are currently in the collection). 197 That is done by the client sending an empty token value to the 198 server. This indicates to the server that a full listing is 199 required. 201 As an alternative, the client might choose to do its first 202 synchronization using some other mechanism on the collection (e.g. 203 some other form of batch resource information retrieval such as 204 PROPFIND, SEARCH [RFC5323] , or specialized REPORTs such as those 205 defined in CalDAV [RFC4791] and CardDAV [RFC6352]) and ask for the 206 DAV:sync-token property to be returned. This property (defined in 207 Section 4) contains the same token that can be used later on to issue 208 a DAV:sync-collection report. 210 In some cases a server might only wish to maintain a limited amount 211 of history about changes to a collection. In that situation it will 212 return an error to the client when the client presents a token that 213 is "out of date". At that point the client has to fall back to 214 synchronizing the entire collection by re-running the report request 215 using an empty token value. 217 Typically, a client will use the synchronization report to retrieve 218 the list of changes, and will follow that with requests to retrieve 219 the content of changed resources. It is possible that additional 220 changes to the collection could occur between the time of the 221 synchronization report and resource content retrieval, which could 222 result in an inconsistent view of the collection. When clients use 223 this method of synchronization, they need to be aware that such 224 additional changes could occur, and track them, e.g., by differences 225 between the ETag values returned in the synchronization report and 226 those returned when actually fetching resource content, by using 227 conditional requests as described in Section 5, or repeating the 228 synchronization process until no changes are returned. 230 3.2. DAV:sync-collection Report 232 If the DAV:sync-collection report is implemented by a WebDAV server, 233 then the server MUST list the report in the "DAV:supported-report- 234 set" property on any collection supporting synchronization. 236 To implement the behavior for this report a server needs to keep 237 track of changes to any member URLs and their mapped resources in a 238 collection (as defined in Section 3 of [RFC4918]). This includes 239 noting the addition of new member URLs, changes to the mapped 240 resources of existing member URLs, and removal of member URLs. The 241 server will track each change and provide a synchronization "token" 242 to the client that describes the state of the server at a specific 243 point in time. This "token" is returned as part of the response to 244 the "sync-collection" report. Clients include the last token they 245 got from the server in the next "sync-collection" report that they 246 execute and the server provides the changes from the previous state, 247 represented by the token, to the current state, represented by the 248 new token returned. 250 The synchronization token itself MUST be treated as an "opaque" 251 string by the client - i.e., the actual string data has no specific 252 meaning or syntax. However, the token MUST be a valid URI to allow 253 its use in an If pre-condition request header (see Section 5). For 254 example, a simple implementation of such a token could be a numeric 255 counter that counts each change as it occurs and relates that change 256 to the specific object that changed. The numeric value could be 257 appended to a "base" URI to form the valid sync-token. 259 Marshalling: 261 The request URI MUST identify a collection. The request body MUST 262 be a DAV:sync-collection XML element (see Section 6.1), which MUST 263 contain one DAV:sync-token XML element, one DAV:sync-level 264 element, and one DAV:prop XML element, and MAY contain a DAV:limit 265 XML element. 267 This report is only defined when the Depth header has value "0"; 268 other values result in a 400 (Bad Request) error response. Note 269 that [RFC3253], Section 3.6, states that if the Depth header is 270 not present, it defaults to a value of "0". 272 The response body for a successful request MUST be a DAV: 273 multistatus XML element, which MUST contain one DAV:sync-token 274 element in addition to one DAV:response element for each member 275 URL that was added, has had its mapped resource changed, or was 276 deleted since the last synchronization operation as specified by 277 the DAV:sync-token provided in the request. A given member URL 278 MUST appear only once in the response. In the case where multiple 279 member URLs of the request-URI are mapped to the same resource, if 280 the resource is changed, each member URL MUST be returned in the 281 response. 283 The content of each DAV:response element differs depending on how 284 the member was altered: 286 For members that have changed (i.e., are new or have had their 287 mapped resource modified) the DAV:response MUST contain at 288 least one DAV:propstat element and MUST NOT contain any DAV: 289 status element. 291 For members that have been removed, the DAV:response MUST 292 contain one DAV:status with a value set to '404 Not Found' and 293 MUST NOT contain any DAV:propstat element. 295 For members that are collections and are unable to support the 296 DAV:sync-collection report, the DAV:response MUST contain one 297 DAV:status with a value set to '403 Forbidden', a DAV:error 298 containing DAV:supported-report or DAV:sync-traversal-supported 299 (see Section 3.3 for which is appropriate), and MUST NOT 300 contain any DAV:propstat element. 302 The conditions under which each type of change can occur is 303 further described in Section 3.5. 305 Preconditions: 307 (DAV:valid-sync-token): The DAV:sync-token element value MUST be a 308 valid token previously returned by the server for the collection 309 targeted by the request-URI. Servers might need to invalidate 310 tokens previously returned to clients. Doing so will cause the 311 clients to fall back to doing full synchronization using the 312 report, though that will not require clients to download resources 313 that are already cached and have not changed. Even so, servers 314 MUST limit themselves to invalidating tokens only when absolutely 315 necessary. Specific reasons include: 317 * Servers might be unable to maintain all of the change data for 318 a collection due to storage or performance reasons. e.g., 319 servers might only be able to maintain up to 3 weeks worth of 320 changes to a collection, or only up to 10,000 total changes, or 321 not wish to maintain changes for a deleted collection. 323 * Change to server implementation: servers might be upgraded to a 324 new implementation that tracks the history in a different 325 manner and thus previous synchronization history is no longer 326 valid. 328 Postconditions: 330 (DAV:number-of-matches-within-limits): The number of changes 331 reported in the response must fall within the client specified 332 limit. This condition might be triggered if a client requests a 333 limit on the number of responses (as per Section 3.7) but the 334 server is unable to truncate the result set at or below that 335 limit. 337 3.3. Depth behavior 339 Servers MUST support only Depth:0 behavior with the DAV:sync- 340 collection report. i.e., the report targets only the collection being 341 synchronized in a single request. However, clients do need to 342 "scope" the synchronization to different levels within that 343 collection, specifically immediate children (level "1") and all 344 children at any depth (level "infinite"). To specify which level to 345 use, clients MUST include a DAV:sync-level XML element in the 346 request. 348 o When the client specifies the DAV:sync-level XML element with a 349 value of "1", only appropriate internal member URLs (immediate 350 children) of the collection specified as the request URI are 351 reported. 353 o When the client specifies the DAV:sync-level XML element with a 354 value of "infinite", all appropriate member URLs of the collection 355 specified as the request URI are reported, provided child 356 collections themselves also support the DAV:sync-collection 357 report. 359 o DAV:sync-token values returned by the server are not specific to 360 the value of the DAV:sync-level XML element used in the request. 361 As such clients MAY use a DAV:sync-token value from a request with 362 one DAV:sync-level XML element value for a similar request with a 363 different DAV:sync-level XML element value, however the utility of 364 this is limited. 366 Note that when a server supports DAV:sync-level XML element with a 367 value of "infinite", it might not be possible to synchronize some 368 child collections within the collection targeted by the report. When 369 this occurs, the server MUST include a DAV:response element for the 370 child collection with status 403 (Forbidden). The 403 response MUST 371 be sent once, when the collection is first reported to the client. 372 In addition, the server MUST include a DAV:error element in the DAV: 373 response element, indicating one of two possible causes for this: 375 The DAV:sync-collection report is not supported at all on the 376 child collection. The DAV:error element MUST contain the DAV: 377 supported-report element. 379 The server is unwilling to report results for the child collection 380 when a DAV:sync-collection report with the DAV:sync-level XML 381 element set to "infinite" is executed on a parent resource. This 382 might happen when, for example, the synchronization state of the 383 collection resource is controlled by another sub-system. In such 384 cases clients can perform the DAV:sync-collection report directly 385 on the child collection instead. The DAV:error element MUST 386 contain the DAV:sync-traversal-supported element. 388 3.4. Types of Changes Reported on Initial Synchronization 390 When the DAV:sync-collection request contains an empty DAV:sync-token 391 element, the server MUST return all member URLs of the collection 392 (taking account of the DAV:sync-level XML element value as per 393 Section 3.3, and optional truncation of results set as per 394 Section 3.6) and it MUST NOT return any removed member URLs. All 395 types of member (collection or non-collection) MUST be reported. 397 3.5. Types of Changes Reported on Subsequent Synchronizations 399 When the DAV:sync-collection request contains a valid value for the 400 DAV:sync-token element, two types of member URL state changes can be 401 returned (changed or removed). This section defines what triggers 402 each of these to be returned. It also clarifies the case where a 403 member URL might have undergone multiple changes between two 404 synchronization report requests. In all cases, the DAV:sync-level 405 XML element value as per Section 3.3, and optional truncation of 406 results set as per Section 3.6, are taken into account by the server. 408 3.5.1. Changed Member 410 A member URL MUST be reported as changed if it has been newly mapped 411 as a member of the target collection since the request sync-token was 412 generated (e.g., when a new resource has been created as a child of 413 the collection). For example, this includes member URLs that have 414 been newly mapped as the result of a COPY, MOVE, BIND [RFC5842], or 415 REBIND [RFC5842] request. All types of member URL (collection or 416 non-collection) MUST be reported. 418 In the case where a mapping between a member URL and the target 419 collection was removed, then a new mapping with the same URI created, 420 the member URL MUST be reported as changed and MUST NOT be reported 421 as removed. 423 A member URL MUST be reported as changed if its mapped resource's 424 entity tag value (defined in Section 3.11 of [RFC2616]) has changed 425 since the request sync-token was generated. 427 A member URL MAY be reported as changed if the user issuing the 428 request was granted access to this member URL, due to access control 429 changes. 431 Collection member URLs MUST be returned as changed if they are mapped 432 to an underlying resource (i.e., entity body) and if the entity tag 433 associated with that resource changes. There is no guarantee that 434 changes to members of a collection will result in a change in any 435 entity tag of that collection, so clients cannot rely on a series of 436 reports using the DAV:sync-level XML element value set to "1" at 437 multiple levels to track all changes within a collection. Instead 438 DAV:sync-level XML element with a value of "infinite" has to be used. 440 3.5.2. Removed Member 442 A member MUST be reported as removed if its mapping under the target 443 collection has been removed since the request sync-token was 444 generated, and it has not been re-mapped since it was removed. For 445 example, this includes members that have been unmapped as the result 446 of a MOVE, UNBIND [RFC5842], or REBIND [RFC5842] operation. This 447 also includes collection members that have been removed, including 448 ones that themselves do not support the DAV:sync-collection report. 450 If a member was added (and its mapped resource possibly modified), 451 then removed between two synchronization report requests, it MUST be 452 reported as removed. This ensures that a client that adds a member 453 is informed of the removal of the member, if the removal occurs 454 before the client has had a chance to execute a synchronization 455 report. 457 A member MAY be reported as removed if the user issuing the request 458 no longer has access to this member, due to access control changes. 460 For a report with the DAV:sync-level XML element value set to 461 "infinite", where a collection is removed, the server MUST NOT report 462 the removal of any members of the removed collection. Clients MUST 463 assume that if a collection is reported as being removed, then all 464 members of that collection have also been removed. 466 3.6. Truncation of Results 468 A server MAY limit the number of member URLs in a response, for 469 example, to limit the amount of work expended in processing a 470 request, or as the result of an explicit limit set by the client. If 471 the result set is truncated, the response MUST use status code 207, 472 return a DAV:multistatus response body, and indicate a status of 507 473 (Insufficient Storage) for the request URI. That DAV:response 474 element SHOULD include a DAV:error element with the DAV:number-of- 475 matches-within-limits precondition, as defined in [RFC3744] (Section 476 9.2). DAV:response elements for all the changes being reported are 477 also included. 479 When truncation occurs, the DAV:sync-token value returned in the 480 response MUST represent the correct state for the partial set of 481 changes returned. That allows the client to use the returned DAV: 482 sync-token to fetch the next set of changes. In this way the client 483 can effectively "page" through the entire set of changes in a 484 consistent manner. 486 Clients MUST handle the 507 status on the request-URI in the response 487 to the report. 489 For example, consider a server that records changes using a strictly 490 increasing integer to represent a "revision number" and uses that 491 quantity as the DAV:sync-token value (appropriately encoded as a 492 URI). Assume the last DAV:sync-token used by the client was 493 "http://example.com/sync/10", and since then 15 additional changes to 494 different resources have occurred. If the client executes a DAV: 495 sync-collection request with a DAV:sync-token of 496 "http://example.com/sync/10", without a limit the server would return 497 15 DAV:response elements and a DAV:sync-token with value 498 "http://example.com/sync/25". But if the server choose to limit 499 responses to at most 10 changes, then it would return only 10 DAV: 500 response elements and a DAV:sync-token with value 501 "http://example.com/sync/20", together with an additional DAV: 502 response element for the request-URI with a status code of 507. 503 Subsequently, the client can re-issue the request with the DAV:sync- 504 token value returned from the server and fetch the remaining 5 505 changes. 507 3.7. Limiting Results 509 A client can limit the number of results returned by the server 510 through use of the DAV:limit element ([RFC5323], Section 5.17) in the 511 request body. This is useful when clients have limited space or 512 bandwidth for the results. If a server is unable to truncate the 513 result at or below the requested number, then it MUST fail the 514 request with a DAV:number-of-matches-within-limits post-condition 515 error. When the results can be correctly limited by the server, the 516 server MUST follow the rules above for indicating a result set 517 truncation to the client. 519 3.8. Example: Initial DAV:sync-collection Report 521 In this example, the client is making its first synchronization 522 request to the server, so the DAV:sync-token element in the request 523 is empty. It also asks for the DAV:getetag property and for a 524 proprietary property. The server responds with the items currently 525 in the targeted collection. The current synchronization token is 526 also returned. 528 >> Request << 530 REPORT /home/cyrusdaboo/ HTTP/1.1 531 Host: webdav.example.com 532 Depth: 0 533 Content-Type: text/xml; charset="utf-8" 534 Content-Length: xxxx 536 537 538 539 1 540 541 542 543 544 545 >> Response << 547 HTTP/1.1 207 Multi-Status 548 Content-Type: text/xml; charset="utf-8" 549 Content-Length: xxxx 551 552 553 554 http://webdav.example.com/home/cyrusdaboo/test.doc 556 557 558 "00001-abcd1" 559 560 Box type A 561 562 563 HTTP/1.1 200 OK 564 565 566 567 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 569 570 571 "00002-abcd1" 572 573 HTTP/1.1 200 OK 574 575 576 577 578 579 HTTP/1.1 404 Not Found 580 581 582 583 http://webdav.example.com/home/cyrusdaboo/calendar.ics 585 586 587 "00003-abcd1" 588 589 HTTP/1.1 200 OK 590 591 592 593 594 595 HTTP/1.1 404 Not Found 596 597 598 http://example.com/ns/sync/1234 599 601 3.9. Example: DAV:sync-collection Report with Token 603 In this example, the client is making a synchronization request to 604 the server and is using the DAV:sync-token element returned from the 605 last report it ran on this collection. The server responds, listing 606 the items that have been added, changed or removed. The (new) 607 current synchronization token is also returned. 609 >> Request << 611 REPORT /home/cyrusdaboo/ HTTP/1.1 612 Host: webdav.example.com 613 Content-Type: text/xml; charset="utf-8" 614 Content-Length: xxxx 616 617 618 http://example.com/ns/sync/1234 619 1 620 621 622 623 624 625 >> Response << 627 HTTP/1.1 207 Multi-Status 628 Content-Type: text/xml; charset="utf-8" 629 Content-Length: xxxx 631 632 633 634 http://webdav.example.com/home/cyrusdaboo/file.xml 636 637 638 "00004-abcd1" 639 640 HTTP/1.1 200 OK 641 642 643 644 645 646 HTTP/1.1 404 Not Found 647 648 649 650 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 652 653 654 "00002-abcd2" 655 656 HTTP/1.1 200 OK 657 658 659 660 661 662 HTTP/1.1 404 Not Found 663 664 665 666 http://webdav.example.com/home/cyrusdaboo/test.doc 668 HTTP/1.1 404 Not Found 669 670 http://example.com/ns/sync/1238 671 673 3.10. Example: Initial DAV:sync-collection Report with Truncation 675 In this example, the client is making its first synchronization 676 request to the server, so the DAV:sync-token element in the request 677 is empty. It also asks for the DAV:getetag property. The server 678 responds with the items currently in the targeted collection, but 679 truncated at two items. The synchronization token for the truncated 680 result set is returned. 682 >> Request << 684 REPORT /home/cyrusdaboo/ HTTP/1.1 685 Host: webdav.example.com 686 Depth: 0 687 Content-Type: text/xml; charset="utf-8" 688 Content-Length: xxxx 690 691 692 693 1 694 695 696 697 698 >> Response << 700 HTTP/1.1 207 Multi-Status 701 Content-Type: text/xml; charset="utf-8" 702 Content-Length: xxxx 704 705 706 707 http://webdav.example.com/home/cyrusdaboo/test.doc 709 710 711 "00001-abcd1" 712 713 HTTP/1.1 200 OK 714 715 716 717 http://webdav.example.com/home/cyrusdaboo/vcard.vcf 719 720 721 "00002-abcd1" 722 723 HTTP/1.1 200 OK 724 725 726 727 http://webdav.example.com/home/cyrusdaboo/ 729 HTTP/1.1 507 Insufficient Storage 730 731 732 http://example.com/ns/sync/1233 733 735 3.11. Example: Initial DAV:sync-collection Report with Limit 737 In this example, the client is making its first synchronization 738 request to the server, so the DAV:sync-token element in the request 739 is empty. It requests a limit of 1 for the responses returned by the 740 server. It also asks for the DAV:getetag property. The server 741 responds with the items currently in the targeted collection, but 742 truncated at one item. The synchronization token for the truncated 743 result set is returned. 745 >> Request << 747 REPORT /home/cyrusdaboo/ HTTP/1.1 748 Host: webdav.example.com 749 Depth: 0 750 Content-Type: text/xml; charset="utf-8" 751 Content-Length: xxxx 753 754 755 756 1 757 758 1 759 760 761 762 763 764 >> Response << 766 HTTP/1.1 207 Multi-Status 767 Content-Type: text/xml; charset="utf-8" 768 Content-Length: xxxx 770 771 772 773 http://webdav.example.com/home/cyrusdaboo/test.doc 775 776 777 "00001-abcd1" 778 779 HTTP/1.1 200 OK 780 781 782 783 http://webdav.example.com/home/cyrusdaboo/ 785 HTTP/1.1 507 Insufficient Storage 786 787 788 http://example.com/ns/sync/1232 789 791 3.12. Example: DAV:sync-collection Report with Unsupported Limit 793 In this example, the client is making a synchronization request to 794 the server with a valid DAV:sync-token element value. It requests a 795 limit of 100 for the responses returned by the server. It also asks 796 for the DAV:getetag property. The server is unable to limit the 797 results to the maximum specified by the client, so it responds with a 798 507 status code and appropriate post-condition error code. 800 >> Request << 802 REPORT /home/cyrusdaboo/ HTTP/1.1 803 Host: webdav.example.com 804 Depth: 0 805 Content-Type: text/xml; charset="utf-8" 806 Content-Length: xxxx 808 809 810 http://example.com/ns/sync/1232 811 1 812 813 100 814 815 816 817 818 820 >> Response << 822 HTTP/1.1 507 Insufficient Storage 823 Content-Type: text/xml; charset="utf-8" 824 Content-Length: xxxx 826 827 828 829 831 3.13. Example: DAV:sync-level set to infinite, initial DAV:sync- 832 collection Report 834 In this example, the client is making its first synchronization 835 request to the server, so the DAV:sync-token element in the request 836 is empty, and it is using DAV:sync-level set to "infinite". It also 837 asks for the DAV:getetag property and for a proprietary property. 838 The server responds with the items currently in the targeted 839 collection. The current synchronization token is also returned. 841 The collection /home/cyrusdaboo/collection1/ exists and has one child 842 resource which is also reported. The collection /home/cyrusdaboo/ 843 collection2/ exists but has no child resources. The collection 844 /home/cyrusdaboo/shared/ is returned with a 403 status indicating 845 that a collection exists but it is unable to report on changes within 846 it in the scope of the current DAV:sync-level "infinite" report. 847 Instead the client can try a DAV:sync-collection report directly on 848 the collection URI. 850 >> Request << 852 REPORT /home/cyrusdaboo/ HTTP/1.1 853 Host: webdav.example.com 854 Depth: 0 855 Content-Type: text/xml; charset="utf-8" 856 Content-Length: xxxx 858 859 860 861 infinite 862 863 864 865 866 868 >> Response << 870 HTTP/1.1 207 Multi-Status 871 Content-Type: text/xml; charset="utf-8" 872 Content-Length: xxxx 874 875 876 877 /home/cyrusdaboo/collection1/ 878 879 880 "00001-abcd1" 881 882 Box type A 883 884 885 HTTP/1.1 200 OK 886 887 888 889 /home/cyrusdaboo/collection1/test.doc 890 891 892 "00001-abcd1" 893 894 Box type A 895 896 897 HTTP/1.1 200 OK 898 899 900 901 /home/cyrusdaboo/collection2/ 902 903 904 905 906 HTTP/1.1 404 Not Found 907 908 909 910 911 912 HTTP/1.1 404 Not Found 913 914 915 916 /home/cyrusdaboo/calendar.ics 917 918 919 "00003-abcd1" 920 921 HTTP/1.1 200 OK 922 923 924 925 926 927 HTTP/1.1 404 Not Found 928 929 930 931 /home/cyrusdaboo/shared/ 932 HTTP/1.1 403 Forbidden 933 934 935 http://example.com/ns/sync/1234 936 938 4. DAV:sync-token Property 940 Name: sync-token 942 Namespace: DAV: 944 Purpose: Contains the value of the synchronization token as it would 945 be returned by a DAV:sync-collection report. 947 Value: Any valid URI. 949 Protected: MUST be protected because this value is created and 950 controlled by the server. 952 COPY/MOVE behavior: This property value is dependent on the final 953 state of the destination resource, not the value of the property 954 on the source resource. 956 Description: The DAV:sync-token property MUST be defined on all 957 resources that support the DAV:sync-collection report. It 958 contains the value of the synchronization token as it would be 959 returned by a DAV:sync-collection report on that resource at the 960 same point in time. It SHOULD NOT be returned by a PROPFIND DAV: 961 allprop request (as defined in Section 14.2 of [RFC4918]). 963 Definition: 965 967 969 5. DAV:sync-token Use with If Header 971 WebDAV provides an If pre-condition header that allows for "state 972 tokens" to be used as pre-conditions on HTTP requests (as defined in 973 Section 10.4 of [RFC4918]). This specification allows the DAV:sync- 974 token value to be used as one such token in an If header. By using 975 this, clients can ensure requests only complete when there have been 976 no changes to the content of a collection, by virtue of an un-changed 977 DAV:sync-token value. Servers MUST support use of DAV:sync-token 978 values in If request headers. 980 5.1. Example: If Pre-Condition with PUT 982 In this example, the client has already used the DAV:sync-collection 983 report to synchronize the collection /home/cyrusdaboo/collection/. 985 Now it wants to add a new resource to the collection, but only if 986 there have been no other changes since the last synchronization. 987 Note, that because the DAV:sync-token is defined on the collection 988 and not on the resource targeted by the request, the If header value 989 needs to use the "Resource_Tag" construct for the header syntax to 990 correctly identify that the supplied state token refers to the 991 collection resource. 993 >> Request << 995 PUT /home/cyrusdaboo/collection/newresource.txt HTTP/1.1 996 Host: webdav.example.com 997 If: 998 () 999 Content-Type: text/plain; charset="utf-8" 1000 Content-Length: xxxx 1002 Some content here... 1004 >> Response << 1006 HTTP/1.1 201 Created 1008 5.2. Example: If Pre-Condition with MKCOL 1010 In this example, the client has already used the DAV:sync-collection 1011 report to synchronize the collection /home/cyrusdaboo/collection/. 1012 Now it wants to add a new collection to the collection, but only if 1013 there have been no other changes since the last synchronization. 1014 Note, that because the DAV:sync-token is defined on the collection 1015 and not on the resource targeted by the request, the If header value 1016 needs to use the "Resource_Tag" construct for the header syntax to 1017 correctly identify that the supplied state token refers to the 1018 collection resource. In this case the request fails as another 1019 change has occurred to the collection corresponding to the supplied 1020 DAV:sync-token. 1022 >> Request << 1024 MKCOL /home/cyrusdaboo/collection/child/ HTTP/1.1 1025 Host: webdav.example.com 1026 If: 1027 () 1029 >> Response << 1031 HTTP/1.1 412 Pre-condition Failed 1033 6. XML Element Definitions 1035 6.1. DAV:sync-collection XML Element 1037 Name: sync-collection 1039 Namespace: DAV: 1041 Purpose: WebDAV report used to synchronize data between client and 1042 server. 1044 Description: See Section 3. 1046 1048 1049 1051 6.2. DAV:sync-token XML Element 1053 Name: sync-token 1055 Namespace: DAV: 1057 Purpose: The synchronization token provided by the server and 1058 returned by the client. 1060 Description: See Section 3. 1062 1064 1066 6.3. DAV:sync-level XML Element 1068 Name: sync-level 1070 Namespace: DAV: 1072 Purpose: Indicates the "scope" of the synchronization report 1073 request. 1075 Description: See Section 3.3. 1077 1079 1081 6.4. DAV:multistatus XML Element 1083 Name: multistatus 1085 Namespace: DAV: 1087 Purpose: Extends the DAV:multistatus element to include 1088 synchronization details. 1090 Description: See Section 3. 1092 1095 1097 1098 1100 7. Security Considerations 1102 This extension does not introduce any new security concerns than 1103 those already described in HTTP and WebDAV. 1105 8. IANA Considerations 1107 This document does not require any actions on the part of IANA. 1109 9. Acknowledgments 1111 The following individuals contributed their ideas and support for 1112 writing this specification: Bernard Desruisseaux, Werner Donne, Mike 1113 Douglass, Ciny Joy, Andrew McMillan, Julian Reschke, and Wilfredo 1114 Sanchez. We would like to thank the Calendaring and Scheduling 1115 Consortium for facilitating interoperability testing for early 1116 implementations of this specification. 1118 10. References 1120 10.1. Normative References 1122 [RFC2119] Bradner, S., "Key words for use in RFCs to 1123 Indicate Requirement Levels", BCP 14, 1124 RFC 2119, March 1997. 1126 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, 1127 H., Masinter, L., Leach, P., and T. Berners- 1128 Lee, "Hypertext Transfer Protocol -- 1129 HTTP/1.1", RFC 2616, June 1999. 1131 [RFC3253] Clemm, G., Amsden, J., Ellison, T., Kaler, 1132 C., and J. Whitehead, "Versioning Extensions 1133 to WebDAV 1134 (Web Distributed Authoring and Versioning)", 1135 RFC 3253, March 2002. 1137 [RFC3744] Clemm, G., Reschke, J., Sedlar, E., and J. 1138 Whitehead, "Web Distributed Authoring and 1139 Versioning (WebDAV) Access Control Protocol", 1140 RFC 3744, May 2004. 1142 [RFC4918] Dusseault, L., "HTTP Extensions for Web 1143 Distributed Authoring and Versioning 1144 (WebDAV)", RFC 4918, June 2007. 1146 [RFC5323] Reschke, J., Reddy, S., Davis, J., and A. 1147 Babich, "Web Distributed Authoring and 1148 Versioning (WebDAV) SEARCH", RFC 5323, 1149 November 2008. 1151 [W3C.REC-xml-20081126] Yergeau, F., Paoli, J., Sperberg-McQueen, C., 1152 Maler, E., and T. Bray, "Extensible Markup 1153 Language (XML) 1.0 (Fifth Edition)", World 1154 Wide Web Consortium Recommendation REC-xml- 1155 20081126, November 2008, 1156 . 1158 10.2. Informative References 1160 [RFC4791] Daboo, C., Desruisseaux, B., and L. 1161 Dusseault, "Calendaring Extensions to WebDAV 1162 (CalDAV)", RFC 4791, March 2007. 1164 [RFC5842] Clemm, G., Crawford, J., Reschke, J., and J. 1165 Whitehead, "Binding Extensions to Web 1166 Distributed Authoring and Versioning 1167 (WebDAV)", RFC 5842, April 2010. 1169 [RFC6352] Daboo, C., "CardDAV: vCard Extensions to Web 1170 Distributed Authoring and Versioning 1171 (WebDAV)", RFC 6352, August 2011. 1173 Appendix A. Backwards Compatible Handling of Depth 1175 In prior draft versions of this specification the Depth request 1176 header was used instead of the DAV:sync-level element to indicate the 1177 "scope" of the synchronization request. Servers that wish to be 1178 backwards compatible with clients conforming to the older 1179 specification should do the following: if a DAV:sync-level element is 1180 not present in the request body, use the Depth header value as the 1181 equivalent value for the missing DAV:sync-level element. 1183 Appendix B. Example of a Client Synchronization Approach 1185 This appendix gives an example of how a client might accomplish 1186 collection synchronization using the WebDAV sync report defined in 1187 this specification. Note that this is provided purely as an example, 1188 and is not meant to be treated as a normative "algorithm" for client 1189 synchronization. 1191 This examples assumes a WebDAV client interacting with a WebDAV 1192 server supporting the sync report. The client keeps a local cache of 1193 resources in a targeted collection, "/collection/". Local changes 1194 are assumed to not occur. The client is only tracking changes to the 1195 immediate children of the collection resource. 1197 ** Initial State ** 1199 The client starts out with an empty local cache. 1201 The client starts out with no DAV:sync-token stored for 1202 "/collection/". 1204 ** Initial Synchronization ** 1206 The client issues a sync report request to the server with an 1207 empty DAV:sync-token element, and DAV:sync-level set to "1". The 1208 request asks for the server to return the DAV:getetag WebDAV 1209 property for each resource it reports. 1211 The server returns a response containing the list of current 1212 resources (with their associated DAV:getetag properties) as well 1213 as a new DAV:sync-token value. 1215 The client associates the new DAV:sync-token value with the 1216 collection. 1218 For each reported resource, the client creates a set of (resource 1219 path, DAV:getetag) tuples. 1221 For each tuple, the client issues an HTTP GET request to the 1222 server to retrieve its content, and updates the (resource path, 1223 DAV:getetag) entry in its local cache for that resource with the 1224 ETag response header value returned in the GET request. 1226 ** Routine Synchronization ** 1228 The client issues a sync report request to the server with the 1229 DAV:sync-token set to the current cached value from the last sync, 1230 and DAV:sync-level set to "1". The request asks for the server to 1231 return the DAV:getetag WebDAV property for each resource it 1232 reports. 1234 The server returns a response containing the list of changes as 1235 well as a new DAV:sync-token value. 1237 The client associates the new DAV:sync-token value with the 1238 collection. 1240 * Process Removed Resources * 1242 For each resource reported with a 404 response status, the client 1243 removes the corresponding resource from its local cache. 1245 * Process Resources * 1247 For each remaining reported resource, the client creates a new set 1248 of (resource path, DAV:getetag) tuples. 1250 The client then determines which resources are in the new set but 1251 not in the current cache, and which resources are in the new set 1252 and the current cache but have a different DAV:getetag value. For 1253 each of those, the client issues an HTTP GET request to the server 1254 to retrieve the resource content, and updates the (resource path, 1255 DAV:getetag) entry in its local cache for that resource with the 1256 ETag response header value returned in the GET request. 1258 Appendix C. Change History (to be removed prior to publication as an 1259 RFC) 1261 Changes in -08: 1263 1. Updated CardDAV reference. 1265 2. IETF LC: changed valid-sync-token description to use MUST for 1266 limiting server invalidation to only necessary cases and 1267 simplified the set of allowed cases. 1269 3. IETF LC: added example of a simple client synchronization 1270 strategy. 1272 Changes in -07: 1274 1. Updated CardDAV reference. 1276 2. IETF LC: expanded acronym in abstract. 1278 3. IETF LC: member URI -> member URL. 1280 4. IETF LC: Clarified limit example to indicate 15 changes are to 1281 different resources. 1283 5. IETF LC: Removed unnecessary DAV: prefix in !ELEMENT DTD 1284 fragments. 1286 6. IETF LC: Changed from using Depth header to DAV:sync-level 1287 element. 1289 7. Apps Review: Clarified that pre-condition applies to request- 1290 URI. 1292 8. GenArt: Clarified that "mapped" implies addition of a resource 1293 in first paragraph of 3.5.1. 1295 9. IESG: Clarified meaning of "opaque" to refer to client treatment 1296 of sync-token. 1298 10. IESG: BIND is now informative again. 1300 11. IESG: Removed paragraph from Security Considerations that was 1301 already covered by WebDAV considerations. 1303 12. IESG: Created a list of allowed reasons for server sync-token 1304 invalidation. 1306 Changes in -06: 1308 1. Changed the 405 error into a 403 with a DAV:error element. 1310 2. Stated more clearly that both depth:1 and depth:infinity must be 1311 supported. 1313 3. Tied up sync-token as URI changes. 1315 4. Made BIND a normative reference. 1317 5. Take into account REBIND. 1319 6. Reworked text to more accurately make the distinction between 1320 member URIs and resources, which should clarify the interaction 1321 with extensions like BIND. 1323 Changes in -05: 1325 1. Added option to use DAV:sync-token as an If pre-condition state 1326 token. 1328 2. DAV:sync-token value now required to be a URI so it can be used 1329 in the If header. 1331 Changes in -04: 1333 1. Depth:infinity support added. 1335 2. Collection resources are now reported as changed if they have a 1336 valid entity tag associated with them. 1338 Changes in -03: 1340 1. Changed D:propstat to D:prop in marshalling. 1342 2. Added request for dead property in examples. 1344 3. Made D:prop mandatory in request so that D:response always 1345 contains at least one D:propstat as per WebDAV definition. 1347 4. Removed DAV:status from response when resource is created/ 1348 modified, thus allowing to get rid of DAV:sync-response in favor 1349 of a regular DAV:response. As a consequence, there is no longer 1350 any difference in the report between created and modified 1351 resources. 1353 5. Resource created, then removed between 2 sync MUST be returned as 1354 removed. 1356 6. Added ability for server to truncate results and indicate such to 1357 the client. 1359 7. Added ability for client to request the server to limit the 1360 result set. 1362 Changes in -02: 1364 1. Added definition of sync-token WebDAV property. 1366 2. Added references to SEARCH, CalDAV, CardDAV as alternative ways 1367 to first synchronize a collection. 1369 3. Added section defining under which condition each state change 1370 (new, modified, removed) should be reported. Added reference to 1371 BIND. 1373 4. Incorporated feedback from Julian Reschke and Ciny Joy. 1375 5. More details on the use of the DAV:valid-sync-token precondition. 1377 Changes in -01: 1379 1. Updated to 4918 reference. 1381 2. Fixed examples to properly include DAV:status in DAV:propstat 1383 3. Switch to using XML conventions text from RFC5323. 1385 Authors' Addresses 1387 Cyrus Daboo 1388 Apple Inc. 1389 1 Infinite Loop 1390 Cupertino, CA 95014 1391 USA 1393 EMail: cyrus@daboo.name 1394 URI: http://www.apple.com/ 1396 Arnaud Quillaud 1397 Oracle Corporation 1398 180, Avenue de l'Europe 1399 Saint Ismier cedex, 38334 1400 France 1402 EMail: arnaud.quillaud@oracle.com 1403 URI: http://www.oracle.com/