Collection Synchronization for WebDAV

One way to synchronize data between two entities is to use some form of synchronization token. The token defines the state of the data being synchronized at a particular point in time. It can then be used to determine what has changed since one point in time and another. This specification defines a new WebDAV report that is used to enable client-server collection synchronization based on such a token. In order to synchronize the contents of a collection between a server and client, the server provides the client with a synchronization token each time the synchronization report is executed. That token represents the state of the data being synchronized at that point in time. The client can then present that same token back to the server at some later time and the server will return only those items that are new, have changed or were deleted since that token was generated. The server also returns a new token representing the new state at the time the report was run. Typically the first time a client connects to the server it will need to be informed of the entire state of the collection (i.e., a full list of all resources that are currently contained in the collection). That is done by the client sending an empty token value to the server. This indicates to the server that a full listing is required. As an alternative, the client may choose to do its first synchronization using some other mechanism on the collection (e.g. some other form of batch resource information retrieval such as PROPFIND, SEARCH , or specialized REPORTs such as those defined in CalDAV and CardDAV ) and ask for the DAV:sync-token property to be returned. This property (defined in ) contains the same token that can be used later on to issue a DAV:sync-collection report. In some cases a server may only wish to maintain a limited amount of history about changes to a collection. In that situation it will return an error to the client when the client presents a token that is "out of date". At that point the client has to fall back to synchronizing the entire collection by re-running the report request using an empty token value.

This specification defines the DAV:sync-collection report. If this report is implemented by a WebDAV server, then the server MUST list the report in the "DAV:supported-report-set" property on any collection supporting synchronization. To implement the behavior for this report a server needs to keep track of changes to any resources in a collection. This includes noting the addition of new resources, changes to existing resources and removal of resources. Only internal members of the collection (as defined in ) are to be considered. The server will track each change and provide a synchronization "token" to the client that describes the state of the server at a specific point in time. This "token" is returned as part of the response to the "sync-collection" report. Clients include the last token they got from the server in the next "sync-collection" report that they execute and the server provides the changes from the previous state, represented by the token, to the current state, represented by the new token returned. The synchronization token itself is an "opaque" string - i.e., the actual string data has no specific meaning or syntax. A simple implementation of such a token would be a numeric counter that counts each change as it occurs and relates that change to the specific object that changed. Marshalling: The request URI MUST identify a collection. The request body MUST be a DAV:sync-collection XML element (see ), which MUST contain one DAV:sync-token XML element, and one DAV:prop XML element. The request MUST include a Depth header with a value of "1". The response body for a successful request MUST be a DAV:multistatus XML element, which MUST contain one DAV:sync-token element in addition to one DAV:response element for each resource that was created, has changed or been deleted since the last synchronization operation as specified by the DAV:sync-token provided in the request. A given resource MUST appear only once in the response. The content of each DAV:response element differs depending on how the resource was altered: For resources that have changed (i.e. are new or have been modified) the DAV:response MUST contain at least one DAV:propstat element and MUST NOT contain any DAV:status element. For resources that have been removed, the DAV:response MUST contain one DAV:status with a value set to '404 Not Found' and MUST NOT contain any DAV:propstat element. The conditions under which each type of change may occur is further described in . Preconditions: (DAV:valid-sync-token): The DAV:sync-token element value MUST map to a valid token previously returned by the server. A token may become invalid as the result of being "out of date" (out of the range of change history maintained by the server), or for other reasons (e.g. collection deleted, then recreated, ACL changes, etc...). Postconditions: (DAV:number-of-matches-within-limits): The number of changes reported in the response must fall within the client specified limit. This condition might be triggered if a client requests a limit on the number of responses (as per ) but the server is unable to truncate the result set at or below that limit.

When the DAV:sync-collection request does not contain a sync-token, the server MUST return all internal members of the collection and it MUST NOT return any removed resource.

When the DAV:sync-collection request contains a valid sync-token, two types of resource state changes can be returned (changed or removed). This section defines what triggers each of these to be returned. It also clarifies the case where a resource may have undergone multiple changes in between two synchronizations.

A resource MUST be reported as changed if it has been mapped directly under the target collection since the request sync token was generated. This includes resources that have been mapped as the result of a COPY, MOVE or BIND () operation. This also includes collection resources that have been created. In the case where a mapping between a resource and the target collection was removed, then a new mapping with the same URI created, the new resource MUST be reported as changed while the old resource MUST NOT be reported as removed. For example, if a resource was deleted, then recreated using the same URI, it should be reported as a changed resource only. A resource MUST be reported as changed if its entity tag value (defined in ) has changed since the request sync token was generated. A resource MAY be reported as changed if the user issuing the request was granted access to this resource, due to access control changes. Collection resources MUST NOT be returned as changed, except in the case stated above. Instead clients are expected to synchronize changes in child collection resources on an individual basis.

A resource MUST be reported as removed if its mapping under the target collection has been removed since the request sync token was generated, and it has not been re-mapped since it was removed. This includes resources that have been unmapped as the result of a MOVE or UNBIND () operation. This also includes collection resources that have been removed. If a resource was created (and possibly modified), then removed in between two synchronizations, it MUST be reported as removed. A resource MAY be reported as removed if the user issuing the request no longer has access to this resource, due to access control changes.

A server MAY limit the number of resources in a response, for example, to limit the amount of work expended in processing a request, or as the result of an explicit limit set by the client. If the result set is truncated, the response MUST use status code 207, return a DAV:multistatus response body, and indicate a status of 507 (Insufficient Storage) for the request URI. That DAV:response element SHOULD include a DAV:error element with the DAV:number-of-matches-within-limits precondition, as defined in (Section 9.2). DAV:response elements for all the changes being reported are also included. When truncation occurs, the DAV:sync-token value returned in the response MUST represent the correct state for the partial set of changes returned. That allows the client to use the returned DAV:sync-token to fetch the next set of changes. In this way the client can effectively "page" through the entire set of changes in a consistent manner. Clients MUST handle the 507 status on the request-URI in the response to the report. For example, consider a server that records changes using a monotonically increasing integer to represent a "revision number" and uses that quantity as the DAV:sync-token value. Assume the last DAV:sync-token used by the client was "10", and since then 20 additional changes have occurred. If the client executes a DAV:sync-collection request with a DAV:sync-token of "10", without a limit the server would return 20 DAV:response elements and a DAV:sync-token with value "30". But if the server choose to limit responses to at most 10 changes, then it would return only 10 DAV:response elements and a DAV:sync-token with value "20", together with an addition DAV:response element for the request-URI with a status code of 507. Subsequently, the client can re-issue the request with the DAV:sync-token value returned from the server and fetch the remaining 10 changes.

A client can limit the number of results returned by the server through use of the DAV:limit element (, Section 5.17) in the request body. This is useful when clients have limited space or bandwidth for the results. If a server is unable to truncate the result at or below the requested number, then it MUST fail the request with a DAV:number-of-matches-within-limits post-condition error. When the results can be correctly limited by the server, the server MUST follow the rules above for indicating a result set truncation to the client.

In this example, the client is making its first synchronization request to the server, so the DAV:sync-token element in the request is empty. It also asks for the DAV:getetag property and for a proprietary property. The server responds with the items currently in the targeted collection. The current synchronization token is also returned.

>> Request <<

]]>

>> Response << http://webdav.example.com/home/cyrusdaboo/test.doc "00001-abcd1" Box type A HTTP/1.1 200 OK http://webdav.example.com/home/cyrusdaboo/vcard.vcf "00002-abcd1" HTTP/1.1 200 OK HTTP/1.1 404 Not Found http://webdav.example.com/home/cyrusdaboo/calendar.ics "00003-abcd1" HTTP/1.1 200 OK HTTP/1.1 404 Not Found

1234

]]>

In this example, the client is making a synchronization request to the server and is using the DAV:sync-token element returned from the last report it ran on this collection. The server responds, listing the items that have been added, changed or removed. The (new) current synchronization token is also returned.

>> Request <<

1234

]]>

>> Response << http://webdav.example.com/home/cyrusdaboo/file.xml "00004-abcd1" HTTP/1.1 200 OK HTTP/1.1 404 Not Found http://webdav.example.com/home/cyrusdaboo/vcard.vcf "00002-abcd2" HTTP/1.1 200 OK HTTP/1.1 404 Not Found http://webdav.example.com/home/cyrusdaboo/test.doc HTTP/1.1 404 Not Found

1238

]]>

In this example, the client is making its first synchronization request to the server, so the DAV:sync-token element in the request is empty. It also asks for the DAV:getetag property. The server responds with the items currently in the targeted collection, but truncated at two items. The synchronization token for the truncated result set is returned.

>> Request <<

]]>

>> Response << http://webdav.example.com/home/cyrusdaboo/test.doc "00001-abcd1" HTTP/1.1 200 OK http://webdav.example.com/home/cyrusdaboo/vcard.vcf "00002-abcd1" HTTP/1.1 200 OK http://webdav.example.com/home/cyrusdaboo/ HTTP/1.1 507 Insufficient Storage

1233

]]>

In this example, the client is making its first synchronization request to the server, so the DAV:sync-token element in the request is empty. It requests a limit of 1 for the responses returned by the server. It also asks for the DAV:getetag property. The server responds with the items currently in the targeted collection, but truncated at one item. The synchronization token for the truncated result set is returned.

>> Request <<

]]>

>> Response << http://webdav.example.com/home/cyrusdaboo/test.doc "00001-abcd1" HTTP/1.1 200 OK http://webdav.example.com/home/cyrusdaboo/ HTTP/1.1 507 Insufficient Storage

1232

]]>

In this example, the client is making a synchronization request to the server with a valid DAV:sync-token element value. It requests a limit of 100 for the responses returned by the server. It also asks for the DAV:getetag property. The server is unable to limit the results to the maximum specified by the client, so it responds with a 507 status code and appropriate post-condition error code.

>> Request <<

1232

100 ]]>

>> Response <<

]]>