// The sync engine: keeps every local Loro doc converged with a peer. Pulls // are cursor-based (per doc, per peer, persisted in sync_state); pushes send // everything committed since the last acknowledged version vector. Both // directions are idempotent, so crashes and races only cost bandwidth. import { VersionVector } from 'loro-crdt'; import * as db from '../data/db'; import { annDocId, ATTEMPTS_DOC, importRemote, openDoc, openedDocs, setOnPersist, WORKSPACE_DOC, } from '../data/loro'; import type { SyncPeer } from './protocol'; import { chunkedUpdates } from './chunk'; // Short on purpose: it only coalesces bursts (e.g. drawing strokes); a page // closed right after an action must still get its last change pushed. const PUSH_DEBOUNCE_MS = 300; let peer: SyncPeer | null = null; let started = false; // Paused while previewing a past revision: the docs are checked out to a // detached historical state, so neither pushing that state nor merging incoming // updates into it is safe. Resumed (with a catch-up sync) on exit. let paused = false; let chain: Promise = Promise.resolve(); let pushTimer: ReturnType | null = null; // Last version vector acknowledged by the peer, kept in memory so the // pagehide beacon (which cannot await IndexedDB) knows what is still unsent. const pushedVVs = new Map(); export function startSync(withPeer: SyncPeer): void { peer = withPeer; if (started) return; started = true; setOnPersist(noteLocalChange); if (typeof window !== 'undefined') { window.addEventListener('online', () => void syncNow()); // A closing page still ships its last local changes, best-effort. window.addEventListener('pagehide', beaconPending); document.addEventListener('visibilitychange', () => { if (document.visibilityState === 'hidden') beaconPending(); }); } void syncNow(); } // Pause/resume around a preview of a past revision. Pausing stops pushes and // pulls; resuming runs a catch-up sync so anything that arrived meanwhile lands. export function pauseSync(): void { paused = true; } export function resumeSync(): void { if (!paused) return; paused = false; void syncNow(); } // Called by the persistence layer after local updates land in IndexedDB. function noteLocalChange(): void { if (!peer || paused) return; if (pushTimer) clearTimeout(pushTimer); pushTimer = setTimeout(() => { pushTimer = null; void syncNow(); }, PUSH_DEBOUNCE_MS); } // Doc ids this replica should converge: its own docs plus whatever the peer // announces (e.g. annotation docs created on another device). async function docIds(remote: { doc_id: string }[]): Promise { const ids = new Set([WORKSPACE_DOC, ATTEMPTS_DOC]); const ws = await openDoc(WORKSPACE_DOC); for (const documentId of ws.getMap('documents').keys()) ids.add(annDocId(documentId)); for (const entry of remote) ids.add(entry.doc_id); return [...ids]; } // Runs are serialized: a call during a run queues exactly one follow-up and // resolves when its own run has finished. export function syncNow(): Promise { const run = chain.then(() => doSync()); chain = run.catch(() => undefined); return run; } async function doSync(): Promise { const p = peer; if (!p || paused) return; try { const remote = await p.manifest(); for (const docId of await docIds(remote)) { await syncDoc(p, docId); } } catch (e) { console.warn('sync failed:', e); } } async function syncDoc(p: SyncPeer, docId: string): Promise { const doc = await openDoc(docId); const stateKey = `${p.name}:${docId}`; const state = (await db.getSyncState(stateKey)) ?? { key: stateKey }; // Pull first: everything the peer has that this cursor hasn't seen. The // cursor only ever advances through pulls, so an interleaved writer between // our pull and push can never be skipped (own updates re-download once, // which the idempotent import absorbs). const { updates, latestSeq } = await p.pull(docId, state.cursor ?? 0); await importRemote(docId, updates); // Push what the peer has not acknowledged yet. An up-to-date doc exports a // non-empty header even with nothing to say, so the skip is decided by // comparing version vectors, not payload sizes. A large backlog is split // into bounded chunks so the server never rejects the whole push for size. const currentVV = doc.oplogVersion().encode(); if (!state.lastPushedVV || !bytesEqual(currentVV, state.lastPushedVV)) { const fromFrontiers = state.lastPushedVV ? doc.vvToFrontiers(VersionVector.decode(state.lastPushedVV)) : undefined; const payloads = chunkedUpdates(doc, fromFrontiers); if (payloads.length) await p.push(docId, payloads); } pushedVVs.set(docId, currentVV); await db.putSyncState({ key: stateKey, cursor: latestSeq, lastPushedVV: currentVV, lastSyncAt: Date.now(), }); } function beaconPending(): void { const p = peer; if (!p?.beacon) return; for (const { docId, doc } of openedDocs()) { const currentVV = doc.oplogVersion().encode(); const acked = pushedVVs.get(docId); if (acked && bytesEqual(currentVV, acked)) continue; const fromFrontiers = acked ? doc.vvToFrontiers(VersionVector.decode(acked)) : undefined; const payloads = chunkedUpdates(doc, fromFrontiers); if (payloads.length) p.beacon(docId, payloads); pushedVVs.set(docId, currentVV); } } function bytesEqual(a: Uint8Array, b: Uint8Array): boolean { if (a.length !== b.length) return false; for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false; return true; } export function resetSyncForTests(): void { peer = null; started = false; chain = Promise.resolve(); pushedVVs.clear(); if (pushTimer) clearTimeout(pushTimer); pushTimer = null; }