utils/crdt_sync_dart/lib/src/sync.dart
Krzysztof kuhy Rudnicki 51e562a764 crdt_sync_dart 0.13.0: E2E envelope + migration
Todo: fda71ed1

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-12 08:19:10 +01:00

154 lines
6.3 KiB
Dart

import 'dart:convert';
import 'package:crypto/crypto.dart';
import 'e2e_cipher.dart';
import 'log.dart';
import 'record.dart';
import 'remote_store.dart';
import 'sync_state.dart';
const _defaultFilename = 'log.json';
String revisionOf(String encodedLog) =>
sha256.convert(utf8.encode(encodedLog)).toString();
/// Runs one full sync tick: pull every other device's log, merge, push.
///
/// Pulls from `<pathPrefix>/<other-device-id>/<filename>` for every device
/// directory the remote reports under [pathPrefix], merges each into
/// [localLog] with [mergeLogs], then pushes this device's own merged result
/// to `<pathPrefix>/<deviceId>/<filename>`.
///
/// [encode] serializes a merged log for pushing. [decode] parses a remote
/// device's pushed text back into a log; throwing [FormatException] (bad
/// JSON syntax) or [TypeError] (valid JSON, wrong shape -- e.g. a missing
/// or mistyped field during [Record.fromJson]) is treated as a
/// corrupt/unparsable push, and that device is skipped for this tick
/// rather than aborting the whole sync. Mirrors the Python `sync_log`'s
/// `(ValueError, KeyError, TypeError)` catch for the same reason.
///
/// Pass [stateStore] to enable revision tracking, which skips downloading
/// peers that have not changed and skips pushing a log that has not changed.
/// Without it the tick behaves exactly as it always did: fetch everything,
/// push unconditionally.
///
/// Revisions live at `<revsPath>/<deviceId>` -- one small text node per
/// device, each written only by its owner. Deliberately *not* one shared map
/// per namespace: a whole-map write would erase every other device's entry,
/// after which those peers would look permanently unchanged and never be
/// fetched again. Per-device keys make that failure impossible rather than
/// merely avoided.
///
/// Pass [legacyDeviceId] on a device that has migrated from a fixed role id
/// (`phone`, `pc`, `desktop`) to a persisted uuid: the old path is then
/// treated as this device's own rather than as a peer's, so its
/// pre-migration log is not pulled back and re-merged every tick. Pass null
/// once that path has been reclaimed.
///
/// [onPeerSkipped] reports each peer skipped as unreadable, e.g. an
/// [E2eDecryptError] from a wrong key or an app that needs updating.
Future<Log> syncLog({
required RemoteStore client,
required String deviceId,
required String pathPrefix,
required Log localLog,
required String Function(Log log) encode,
required Log Function(String text) decode,
String filename = _defaultFilename,
String commitMessage = 'crdt_sync: update log',
SyncStateStore? stateStore,
String? revsPath,
String? legacyDeviceId,
void Function(String deviceId, Object error)? onPeerSkipped,
}) async {
final revs = revsPath ?? defaultRevsPath(pathPrefix);
final state = await stateStore?.load() ?? const SyncState();
final remoteRevs = stateStore == null
? const <String, String>{}
: await _remoteRevs(client, revs);
// A set rather than one id: a device that has migrated from a role
// constant to a persisted uuid still owns the log it pushed under the old
// id. Matching only the current id would pull that file back and re-merge
// this device's own pre-migration history as though a peer wrote it.
final ownIds = <String>{deviceId, ?legacyDeviceId};
var mergedLog = Map<String, Record>.from(localLog);
final seenRevs = <String, String>{};
for (final otherDeviceId in await client.listDirectory(pathPrefix)) {
if (ownIds.contains(otherDeviceId)) continue;
final remoteRev = remoteRevs[otherDeviceId];
if (remoteRev != null && remoteRev == state.peerRevs[otherDeviceId]) {
// Unchanged since we last merged it, and that merge is already part of
// localLog -- so the (potentially hundreds of KB) download is pure
// waste. Carry the revision forward so it stays skipped next tick.
seenRevs[otherDeviceId] = remoteRev;
continue;
}
final String? text;
try {
text = await client.getFileText('$pathPrefix/$otherDeviceId/$filename');
} on E2eDecryptError catch (error) {
onPeerSkipped?.call(otherDeviceId, error);
continue;
}
if (text == null) continue;
try {
mergedLog = mergeLogs(mergedLog, decode(text));
} on FormatException catch (error) {
onPeerSkipped?.call(otherDeviceId, error);
continue;
} on TypeError catch (error) {
onPeerSkipped?.call(otherDeviceId, error);
continue;
}
// Only remembered once the merge succeeded: a corrupt push must be
// retried next tick, not marked as seen.
seenRevs[otherDeviceId] = remoteRev ?? revisionOf(text);
}
final encoded = encode(mergedLog);
final rev = revisionOf(encoded);
final unchanged = stateStore != null && rev == state.pushedRev;
if (!unchanged) {
await client.putFileText(
'$pathPrefix/$deviceId/$filename',
encoded,
message: commitMessage,
);
if (stateStore != null) {
// Published after the log, never before: a peer that cached "seen rev
// X" against a log it never received would skip it forever.
await client.putFileText('$revs/$deviceId', rev, message: commitMessage);
}
}
await stateStore?.save(SyncState(pushedRev: rev, peerRevs: seenRevs));
return mergedLog;
}
/// Where revisions live for a given [pathPrefix]: a `revs` sibling of the
/// device directory, e.g. `diet-guard-sync/devices` -> `diet-guard-sync/revs`
/// and `todo-sync/notes` -> `todo-sync/revs`.
String defaultRevsPath(String pathPrefix) {
final cut = pathPrefix.lastIndexOf('/');
return cut < 0 ? '$pathPrefix/revs' : '${pathPrefix.substring(0, cut)}/revs';
}
/// Reads every peer's published revision, cheaply where the backend allows.
///
/// Degrades to an empty map -- meaning "fetch everything", the old behaviour
/// -- on any backend without [BulkMapReader], so correctness never depends on
/// the optimisation being available.
Future<Map<String, String>> _remoteRevs(
RemoteStore client,
String revsPath,
) async {
// A pattern bind rather than `is!` + promotion: BulkMapReader is not a
// subtype of RemoteStore, and Dart only promotes to subtypes of the
// declared type -- so the intersection has to be named explicitly.
if (client case final BulkMapReader reader) {
return reader.getStringMap(revsPath);
}
return const {};
}