todo-app/lib/sync/sync_service.dart
Krzysztof kuhy Rudnicki ea216d4a59
Some checks are pending
dependency freshness / dependencies on newest stable (push) Waiting to run
file-length / file length <= 250 lines (push) Waiting to run
md-naming / markdown naming convention (push) Waiting to run
release-apk / release (APK) (push) Waiting to run
repo-contract / repo contract (push) Waiting to run
Sync pulls peers at once, off the UI thread
The board reported a 3.9 s sync.run spinner on the Pixel (todo:0c575b891b).
Eight ~2 MB peer logs were fetched, parsed on the UI isolate and merged one
by one, each merge rewriting the whole local store; a device without a
GitHub token still mirrored to GitHub (404s); settings and analytics waited
for the note sync.

Now changed peers download together, logs over 64 KB parse on an isolate
(inline on web), peers merge into one local write, the revision map and
listing share a round trip, the mirror is skipped without a token, and
settings/analytics run alongside the notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 11:25:22 +01:00

219 lines
8.3 KiB
Dart

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<String> 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/<nodeId>.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<SyncResult> 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<Object>([
if (stateStore == null)
Future.value(const <String, String>{})
else
_revisions(remote),
remote.listDirectory(notesDir),
], eagerError: true);
final remoteRevs = reads[0] as Map<String, String>;
final names = reads[1] as List<String>;
final seenRevs = <String, String>{};
// 1. Pull: every other device's log that changed since we merged it.
var skippedUnchanged = 0;
final changed = <String>[];
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 = <String>[];
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<Map<String, String>> _revisions(RemoteStore remote) async {
if (remote is! BulkMapReader) return const {};
return await (remote as BulkMapReader).getStringMap(revsDir);
}
}