import 'package:crdt_sync/crdt_sync.dart'; import 'package:todo/data/note_repository.dart'; import 'package:todo/sync/peer_pull.dart'; /// Outcome of a sync run, for surfacing in the UI. class SyncResult { /// Creates a [SyncResult] from a completed sync run's outcome. const SyncResult({ required this.mergedDevices, required this.pushed, this.skippedFiles = const [], this.skippedUnchanged = 0, this.firebaseConnected = false, this.locked = false, }); /// How many other devices' logs were pulled and merged. final int mergedDevices; /// Whether this device pushed its own log. final bool pushed; /// Whether this run's primary backend was Firebase, rather than GitHub /// alone. Set by the caller ([runSync]), which is the only layer that /// knows which [RemoteStore] it built -- [SyncService] itself is /// deliberately agnostic to what [RemoteStore] it was handed. /// /// Exists so the status line can say so: reporting a plain "Synced" while /// this is false is what made a desktop stuck on GitHub-only look /// identical to one actually reaching Firebase, on a device that had in /// fact never connected. final bool firebaseConnected; /// Peer files that were listed but could not be fetched or decoded /// (vanished, corrupt, or foreign format) and were left out of the merge. /// Surfaced so a device silently dropping out of sync is visible. final List skippedFiles; /// Peers whose logs were skipped because their revision was unchanged. /// /// Distinct from [skippedFiles]: this is the optimisation working, not a /// device dropping out. final int skippedUnchanged; /// True when end-to-end encryption has no usable key on this device, so /// nothing was pulled, merged or pushed. final bool locked; /// Returns a copy with [firebaseConnected] set. [SyncService] never sets /// it -- only [runSync], which is the layer that knows which [RemoteStore] /// it built -- so this is the seam that lets it do that without /// [SyncService] taking on knowledge of Firebase at all. SyncResult withFirebaseConnected({required bool value}) => SyncResult( mergedDevices: mergedDevices, pushed: pushed, skippedFiles: skippedFiles, skippedUnchanged: skippedUnchanged, firebaseConnected: value, locked: locked, ); @override String toString() => 'SyncResult(mergedDevices: $mergedDevices, pushed: $pushed, ' 'firebaseConnected: $firebaseConnected, skippedFiles: $skippedFiles)'; } /// Synchronises a [NoteRepository] with a GitHub repo used as dumb storage. /// /// Design: each device owns exactly one file, `todo-sync/notes/.json`, /// holding its full crdt_sync note [Log]. Because no two devices ever write the /// same file, there are **no git-level merge conflicts**; convergence is the /// CRDT layer's job — pulling every other device's log and [NoteRepository] /// merging it via `mergeLogs` is commutative and idempotent, so repeated syncs /// in any order converge to the same state. /// /// The directory is `notes/` (not the legacy `changesets/`): the on-the-wire /// format changed from a `sqlite_crdt` changeset to a crdt_sync `Log`, so the /// two never share a path and an old client can't misread a new file. class SyncService { /// Creates a [SyncService], optionally overriding [notesDir]. const SyncService({ this.notesDir = 'todo-sync/notes', this.stateStore, this.revsPath, }); /// Directory in the repo under which per-device note-log files live. final String notesDir; /// Remembers each peer's last-seen revision between runs. /// /// Without one, every sync downloads every peer's whole log — four files of /// roughly 150 KB here — whether or not anything changed. With one, an /// unchanged peer costs nothing beyond the shared revision map, which is /// what keeps this inside the Firebase free tier's monthly budget. final SyncStateStore? stateStore; /// Where revisions live, as a sibling of [notesDir]. /// Revision cache directory; null derives it from [notesDir]. final String? revsPath; /// Where peers publish their revisions. String get revsDir => revsPath ?? defaultRevsPath(notesDir); /// Runs a full pull-merge-push cycle. Safe to call repeatedly. /// /// [remote] is any [RemoteStore]: GitHub alone before the cutover, or a /// [MirrorStore] with Firebase primary during it. Swapping backends is a /// change at the call site and nothing more. Future sync(NoteRepository repo, RemoteStore remote) async { final nodeId = repo.nodeId; final ownFileName = '$nodeId.json'; final state = await stateStore?.load() ?? const SyncState(); // Independent reads, so one round trip instead of two. eagerError keeps // the first failure's own type, which callers catch. final reads = await Future.wait([ if (stateStore == null) Future.value(const {}) else _revisions(remote), remote.listDirectory(notesDir), ], eagerError: true); final remoteRevs = reads[0] as Map; final names = reads[1] as List; final seenRevs = {}; // 1. Pull: every other device's log that changed since we merged it. var skippedUnchanged = 0; final changed = []; for (final name in names) { if (name == ownFileName) continue; // our own file; skip it. final peer = peerOf(name); final remoteRev = remoteRevs[peer]; if (remoteRev != null && remoteRev == state.peerRevs[peer]) { // Unchanged since we last merged it, and that merge is already in the // local log -- so the download is pure waste. Carry the revision // forward so it stays skipped next time. seenRevs[peer] = remoteRev; skippedUnchanged++; continue; } changed.add(name); } var merged = 0; final skipped = []; Log? incoming; for (final pulled in await pullPeers( remote, notesDir, changed, remoteRevs, )) { final log = pulled.log; if (log == null) { // A vanished, undecryptable or undecodable peer file must not abort // the sync, but it must not vanish silently either -- that's how a // device drops out of sync unnoticed. Reported, and deliberately not // recorded as seen: a corrupt push must be retried next run. skipped.add(pulled.name); continue; } // Peers merge with each other first (commutative, idempotent), so the // local store is rewritten once rather than once per peer. incoming = incoming == null ? log : mergeLogs(incoming, log); seenRevs[pulled.peer] = pulled.rev!; merged++; } if (incoming != null) await repo.importLog(incoming); // 2. Push: upload our own (now-merged) log under our node id. // putFileText resolves our file's current sha itself. final encoded = logToJson(repo.exportLog()); final revision = revisionOf(encoded); final unchanged = stateStore != null && revision == state.pushedRev; if (!unchanged) { await remote.putFileText( '$notesDir/$ownFileName', encoded, message: 'sync: $nodeId @ ${DateTime.now().toUtc().toIso8601String()}', ); // Published after the log, never before: a peer that cached "seen rev X" // against a log it never received would skip it forever. if (stateStore != null) { await remote.putFileText( '$revsDir/$nodeId', revision, message: 'sync: revision $nodeId', ); } } if (stateStore != null) { await stateStore!.save( SyncState(pushedRev: revision, peerRevs: seenRevs), ); } return SyncResult( mergedDevices: merged, pushed: !unchanged, skippedFiles: skipped, skippedUnchanged: skippedUnchanged, ); } /// Reads every peer's published revision in one request where possible. /// /// Degrades to an empty map — meaning "fetch everything", the old /// behaviour — on a backend without a bulk-map read, so correctness never /// depends on the optimisation being available. Future> _revisions(RemoteStore remote) async { if (remote is! BulkMapReader) return const {}; return await (remote as BulkMapReader).getStringMap(revsDir); } }