Collection Synchronization for Web Distributed Authoring and Versioning (WebDAV)
Extracted elements (26)
Clients cannot rely on a series of sync-level '1' reports at multiple collection levels to track all changes, because changes to members of a collection do not necessarily change the collection's own ETag. A sync-level 'infinite' report must be used instead for complete tracking.
The DAV:sync-token is scoped to the collection resource, not the individual request-URI in conditional operations, requiring clients to use the 'Resource_Tag' construct in If headers to correctly identify which resource the token refers to.
The sync token is required to be a valid URI (not just an opaque string) specifically to enable its use in WebDAV If precondition headers, which require state tokens to be URI-formatted. This allows clients to perform conditional operations that atomically check collection state.
Prior draft versions of this specification used the Depth request header instead of the DAV:sync-level element to indicate synchronization scope. Servers wishing backwards compatibility with such clients should fall back to using the Depth header value when DAV:sync-level is absent from the request body.
A member MUST be reported as removed if its mapping under the target collection has been removed and has not been remapped. If a member was added and then removed between two sync requests, it MUST be reported as removed.
A member URL MUST be reported as changed if it has been newly mapped since the request sync-token was generated, or if its mapped resource's ETag value has changed since the request sync-token was generated.
Clients MUST handle the 507 status on the request-URI in the response to the DAV:sync-collection report, using the returned sync-token to fetch subsequent pages of changes.
For changed members, the DAV:response MUST contain at least one DAV:propstat element and MUST NOT contain any DAV:status element. For removed members, the DAV:response MUST contain one DAV:status set to '404 Not Found' and MUST NOT contain any DAV:propstat element.
For sync-level 'infinite', when a collection is removed the server MUST NOT report the removal of any members of the removed collection; clients MUST assume all members of a removed collection are also removed.
If a server is unable to truncate the result at or below the client-specified DAV:limit value, it MUST fail the request with a DAV:number-of-matches-within-limits postcondition error.
If the DAV:sync-collection report is implemented by a WebDAV server, the server MUST list the report in the DAV:supported-report-set property on any collection that supports synchronization.
Servers MUST limit themselves to invalidating sync tokens only when absolutely necessary, such as storage/performance constraints or server implementation changes. Invalidation forces clients to perform a full re-synchronization.
Servers MUST support only Depth:0 behavior with the DAV:sync-collection report. Clients MUST include a DAV:sync-level XML element with value '1' (immediate children) or 'infinite' (all descendants) to specify scope.
Servers MUST support use of DAV:sync-token values in If request headers, allowing clients to condition operations on the collection's sync state having not changed since their last synchronization.
The DAV:sync-token property MUST be protected (server-controlled), and SHOULD NOT be returned by a PROPFIND DAV:allprop request.
The request-URI MUST identify a collection. The request body MUST be a DAV:sync-collection XML element containing one DAV:sync-token, one DAV:sync-level, one DAV:prop, and optionally one DAV:limit element. This report is only defined when Depth header is '0'.
The response body for a successful request MUST be a DAV:multistatus XML element containing one DAV:sync-token element plus one DAV:response for each member URL added, changed, or deleted. A given member URL MUST appear only once in the response.
The synchronization token MUST be treated as an opaque string by the client, but MUST be a valid URI to allow its use in an If precondition request header.
When a URL mapping was removed and then a new mapping with the same URI was created, the member URL MUST be reported as changed and MUST NOT be reported as removed.
When results are truncated, the response MUST use status 207, return a DAV:multistatus body, and indicate status 507 (Insufficient Storage) for the request-URI. The returned DAV:sync-token MUST represent the correct state for the partial set of changes returned, allowing clients to page through changes.
When sync-level is 'infinite' and a child collection cannot support sync, the server MUST include a DAV:response for that collection with status 403 Forbidden, sent once when first reported. The DAV:error MUST contain either DAV:supported-report or DAV:sync-traversal-supported.
When the DAV:sync-collection request contains an empty DAV:sync-token, the server MUST return all member URLs of the collection and MUST NOT return any removed member URLs.
The DAV:sync-token property contains the current synchronization token for a collection, equal to the value returned by a DAV:sync-collection report at the same point in time. It MUST be defined on all collections supporting the sync report.
This extension does not introduce any new security concerns beyond those already described in HTTP and WebDAV. Existing HTTP and WebDAV security mechanisms apply.
The DAV:multistatus element is extended to include an optional DAV:sync-token child element in the response, in addition to the standard response, responsedescription children inherited from RFC 4918.
The DAV:sync-collection request element has the structure: (sync-token, sync-level, limit?, prop), where sync-token is a URI or empty string, sync-level is '1' or 'infinite', and prop specifies requested properties.