Module: chum-sync

This module connects two ONE instances and synchronizes (transfers) all objects accessible by one instance to the other. The exchange is bidirectional. When the synchronization is finished a Chum object is written by both sides with a log of the exchange.

Limitations

Changes to group memberships performed while a Chum is active are ignored. The Chum uses the group memberships it finds when the exchange is initialized.

Writes to storage while a synchronization is running may or may not influence it depending on mode and on timing. For example, in mode "keepRunning = false" (see below) the list of all Access objects accessible by the given person (by ID hash) are calculated at the start. If an Access object is for an ID hash, i.e. for all versions of a versioned object, any new versions written while the synchronization is running may be transferred (or not) depending on if the object was written before that particular object was transferred or after. In mode "keepRunning = true" it will be transferred for certain if the write-operation occurs before the synchronization is explicitly ended.

keepRunning = false

The Chum synchronizes all currently accessible objects and then exits.

Note that there is no locking, the behavior if the application continues to write to storage depends on what it writes and on timing, if it modifies access settings that would be relevant to the currently connected remote ONE instance. We do not wish to disable (or queue) all write requests while a synchronization is running, since this may take quite a long time. We also don't want to incur the cost of checking if any writes are relevant. We think it is easy (easier, cheaper) for the application to be programmed in such a way that continued writing to ONE storage while an exchange is running has no undesirable consequences.

keepRunning = true

The Chum performs a full synchronization and then keeps the connection open and keeps synchronizing any objects as they become available and accessible. Only when the synchronization is explicitly ended are the final Chum log objects written by both sides. It will not lose any relevant writes because immediately after the initial calculation of accessible Access objects (which point to the accessible objects) the code starts watching what ONE objects are written and, if relevant, adds them to the collection of accessible hashes unknown with those found through the originally started full synchronization.

While there is no sharp distinction between objects (hashes) found through the request for a full synchronization and those found while watching new objects being written there is a "full synchronization achieved" status. It is achieved when the objects reachable through all Access objects found initially (not through monitoring ongoing storage writes) have all been processed (hashes collected, sent to the remote instance, processed and then acknowledged by the remote instance). It is significant because there is a timestamp given to the remote instance when it makes its request. "Full synchronization" means that all objects accessible at that point have been processed. The timestamp can then be used by the remote instance to only ask for objects created after that timestamp.