Synchronization

About the actual synchronization process

Synchronization logic

These steps are performed when synchronizing a collection:

  1. Prepare synchronization: prepare local collection, settings etc.
  2. Query capabilities with HTTP PROPFIND:
  3. Process locally deleted resources: if a local resource is flagged as deleted,
    • delete it on the server (HTTP DELETE with If-Match set to last known ETag to avoid deleting resources which have been changed on the server in the meanwhile) and
    • then remove it locally
  4. Upload locally modified ("dirty") resources:
    • Assign a random UID and resource name to new resources; prepare contact group and recurring events, if necessary
    • If no previous ETag of the resource is known (i.e. the resource has not been uploaded yet), use HTTP PUT with If-None-Match: * to avoid overwriting a possibly existing resource with the same name
    • If a previous ETag of the resource is known, use HTTP PUT with If-Match set to last known ETag to avoid overwriting changes which happend on the server in the meanwhile
    • remember returned ETag as last known ETag; otherwise reset last known ETag
  5. Choose sync algorithm (PROPFIND/REPORT vs. Collection Synchronization):
    • CardDAV: use Collection Synchronization if supported by server, PROPFIND otherwise
    • CalDAV events: use Collection Synchronization if supported by server and past time event limit is disabled, REPORT calendar-query otherwise
    • CalDAV tasks: use REPORT calendar-query
  6. Check whether further synchronization is needed. Only continue when:
    • modifications (uploads/deletions) have been sent to the server, or
    • the sync state (CTag/sync-token) of the collection has changed since last sync, or
    • the PROPFIND/REPORT algorithm shall be used and the sync has been initiated manually
  7. Continue with chosen sync algorithm (see below).

Sync algorithm: PROPFIND/REPORT

  1. Unset "present remotely" flag for all resources
  2. List and process remote resources (only names and ETags) using PROPFIND or REPORT (see above)
    • Download resources which have been added/modififed remotely in bunches using GET or REPORT addressbook-multiget/calendar-multiget into the local storage.
    • Set "present remotely" flag for all received resources.
  3. Locally delete all resources which are not flagged as "present remotely"
  4. Post-processing: clean up empty contact groups etc.
  5. Save sync state (CTag/sync-token)

Sync algorithm: Collection Synchronization

  1. Was a previous "initial sync" aborted and is now being continued? → If yes, set "initial sync".
  2. Do we have a previous sync-token? → If no, set "initial sync".
  3. List and process changes since last sync-token (or all records if no previous sync-token is known) using REPORT sync-collection.
    • Download resources which have been added/modififed remotely in bunches using GET or REPORT addressbook-multiget/calendar-multiget into the local storage.
    • Set "present remotely" flag for all received resources.
  4. If the requested sync-token was invalid:
    • forget the sync-token
    • reset "present remotely" flags of all local resources
    • set "initial sync" and continue with 3.
  5. Save sync-token.
  6. Are there further changes on the server (HTTP 507 on collection URL in multiget response)? → If yes, continue with 3.
  7. Only for "initial sync": delete all local resources which are not present remotely.
  8. Post-processing: clean up empty contact groups etc.

Conflict handling

Conflicts occur when different versions of a resource are available and it's ambigous which one shall be used. For instance:

  1. A contact exists on the server and has been synchronized to a mobile phone with DAVx⁵ and to a desktop PC with Gnome Evolution.
  2. You modify the contact with Evolution, which immediately uploads it to the server.
  3. You modify the same contact on your mobile device, too.
  4. DAVx⁵ wants to upload the modified contact and finds that it has been changed on the server in the meanwhile. Now there's a conflict of two different versions of this contact.

How DAVx⁵ handles such conflicts:

  • DAVx⁵ relies on HTTP ETags to determine whether a resource has been changed on the server.
  • The server always wins. If a local resource can't be uploaded or deleted safely because it has been modified on the server in the meanwhile, local changes are discarded and the server version is used.
  • DAVx⁵ doesn't involve the user in resolving conflicts (like asking which version shall be used) because it's supposed to run in the background silently.

Last updated: 05 Jan 2019