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.


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.



(static, constant) PROTOCOL_VERSION :number

Exchanged at the beginning of the Chum protocol. If versions of im- and exporter of both nodes donÄt match the chum exchange will be aborted with an error.

  • number


(async, static) createChum(options) → {Promise.<ChumApi>}

Name Type Description
options ChumSyncOptions

This function executes a Chum synchronization between two ONE instances and when done stores a new Chum object with a log of what was exchanged.


Resolves with the result of storing the new Chum object.

Type: Promise.<ChumApi>

Type Definitions


  • object
Name Type Attributes Default Description
localPersonId SHA256IdHash

The ID hash of the owner of the local instance the chum is exchanging data with. This does not have to be the main instance but some anonymous ID, so we cannot simply query the instance for the main instance's Person ID

remotePersonId SHA256IdHash

The ID hash of the owner of the remove instance the chum is exchanging data with

chumName string

Name of the Chum

localInstanceName string

Name of local instance

remoteInstanceName string

Name of remote instance

keepRunning boolean <optional>

The connection remains until stopped explicitly

maxNotificationDelay number

When keepRunning is true and the full synchronization is over, what should be the maximum delay between new accessible objects being created and notification events sent to us? The remote instance is going to collect all new accessible hashes and only sends them after waiting for this many milliseconds. If there are a lot of new hashes, exceeding a hard-coded threshold, it sends them right away though. If you require fast notifications about rare new-accessible-object events you can set the delay low (1 ms is the minimum), if it is not urgent you can set the delay higher and let the remote exporter accumulate more hashes. The delay does not have to be higher than a few seconds, because it will make less and less of a difference very quickly with increasing values.