search

automerge / automerge-classic

A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.
http://automerge.org/
MIT License
14.75k stars 466 forks source link

generateSyncMessage and initSyncState methods #372

Closed AleCaste closed 3 years ago

AleCaste commented 3 years ago

Hello, any hints about how to use generateSyncMessage and initSyncState methods?

jeffa5 commented 3 years ago

Hi @AleCaste, the sync states are per peer you will communicating with.

When you first connect, create a new sync state with initSyncState. With this you'll want to generate a new sync message using generateSyncMessage and passing in your new sync state. This may give you a message (if things need to be sent) and so forward that to your peer and keep the sync state around. When you receive a message from that peer call receiveSyncMessage with the same sync state and the new message to apply any changes from the peer etc, this may also update the sync state and will return you a new one. Then repeat calling generateSyncMessage and receiveSyncMessage in turn when things arrive and you need to send new messages.

When a peer disconnects you'll probably want to save the sync state with encodeSyncState (I think thats the name) for when they come back online, when they do just decodeSyncState it (this roundtrip encode decode cleans some of the state to help reset the connection) and carry on with generateSyncMessage and receiveSyncMessage.

Happy to try and help with any other hints or more detail with this explanation. Also others may have better explanations and we can draw from these for documentation too.

AleCaste commented 3 years ago

Thanks a lot for your explanations. Very helpful. I also found plenty of details in the pull request for the 3rd sync version: https://github.com/automerge/automerge/pull/339

jeffa5 commented 3 years ago

Great! I'll close this for now but feel free to re-open if there are more questions.

ept commented 3 years ago

Agree with what @jeffa5 has said, just one small addition: if you're using local storage for persistence, you should also encode the sync state to a byte array using encodeSyncState, and store it persistently along with your document. When you restart the app and then reconnect to a peer, restore the sync state for that peer using decodeSyncState. That allows the peers to continue where they left off before the app restart, which makes repeated syncs much more efficient. And note that you need a separate syncState for every peer you're talking to.

Steve-OH commented 3 years ago

Is there a reason that encodeSyncState and decodeSyncState are exposed only on the Backend object and not the Automerge object? It suggests that they're not intended to be used from application-level code.

ept commented 3 years ago

@Steve-OH Good point, we should probably expose those functions on the top-level Automerge object too.