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 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
    • sync state (CTag/sync-token) of the collection has changed since last sync, or
    • Collection Synchronization is not being 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 remote resources (only names and ETags) using PROPFIND or REPORT (see above)
  3. Compare local and remote resources: determine which resources have been
    • added remotely → will be downloaded and created locally
    • updated remotely → will be downloaded and updated locally
    • set "present remotely" flag for all received resources
  4. Process remote changes: download remote resources
    • in bunches of max. 10 contacts at once using GET (for single contacts) or REPORT addressbook-multiget or
    • in bunches of max. 20 events/tasks at once using GET (for single resources) or REPORT calendar-multiget and
    • insert them into the respective local storage
  5. Locally delete all resources which are not flagged as "present remotely"
  6. Post-processing: clean up empty contact groups etc.
  7. Save sync state (CTag/sync-token)

Sync algorithm: Collection Synchronization

TODO

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 DAVdroid 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. DAVdroid 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 DAVdroid handles such conflicts:

  • DAVdroid 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.
  • DAVdroid 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.

Error handling

When an error has occured, DAVdroid does not continue synchronization of the respective collection to avoid data loss and inconsistent synchronization states. DAVdroid uses two facilities to report synchronization errors:

  1. DAVdroid can show Android notifications with an error message. You can tap those notifications to get debug information that can be shared over email. Sometimes, notification actions like "View local item" (views the local item which is related to the error) or "Retry" may be available.
  2. DAVdroid can report success or error states back to the Android sync framework that calls DAVdroid. On errors, Android settings / Accounts will shown the DAVdroid account as "currently experiencing problems" (see screenshots).

DAVdroid sync error notifications will disappear automatically as soon as they don't apply anymore.

In case of soft errors like I/O errors (for instance, when there has been a problem with the network connection), DAVdroid uses notifications with minimum priority. Those notifications are shown when notifications are viewed, but don't appear in the notification bar, because in most cases they're only temporary and don't need attention. However, if such a notification appears all the time, you may need to investigate.

Last updated: 27 Jun 2018