commit method

  1. @override
Future<String> commit(
  1. String locator,
  2. TomChangeset changeset, {
  3. String? expectedHead,
  4. String? message,
  5. TomCommitProgressSink? onProgress,
})
override

Applies changeset atomically, refusing the write if the container has moved away from expectedHead.

Pass a null expectedHead to create a container that does not exist yet; a backend MUST fail with TomCasConflictException if one does. Returns the new head.

onProgress, when given, receives TomCommitProgress as the changeset's objects go up — before each and after the last. It is optional on both sides: a caller need not ask, and a backend whose save is effectively instantaneous need not report. Silence from a backend is therefore not a failure to implement it; it is the honest answer for a local filesystem write.

Implementation

@override
Future<String> commit(
  String locator,
  TomChangeset changeset, {
  String? expectedHead,
  String? message,
  // Deliberately unused: a local save is a handful of `writeAsBytesSync`
  // calls and is over before a frame renders, so reporting progress through
  // it would be inventing a wait to display. The port makes the sink
  // optional for exactly this backend.
  TomCommitProgressSink? onProgress,
}) async {
  tomGuardChangeset(locator, changeset, this);
  final directory = !changeset.isSingleFile;
  if (directory && Directory(locator).existsSync()) {
    final dir = Directory(locator);
    _recover(dir);
    _sweep(dir);
  } else if (!directory) {
    final stray = File('$locator$tempSuffix');
    if (stray.existsSync()) stray.deleteSync();
  }
  final actualHead = await headOf(locator);
  if (actualHead != expectedHead) {
    throw TomCasConflictException(
      locator,
      expectedHead: expectedHead,
      actualHead: actualHead,
    );
  }
  if (changeset.isEmpty) return actualHead ?? TomStorage.emptyHead;

  if (!directory) {
    final before = _modifiedTimes([locator]);
    await _clockPast(before);
    // One file is one rename, which the filesystem already makes atomic.
    final temp = _stage({locator: changeset.containerBytes});
    File(temp.keys.single).renameSync(locator);
    _advancePast(before);
    return (await headOf(locator))!;
  }

  final dir = Directory(locator)..createSync(recursive: true);
  final before = _modifiedTimes([
    for (final relative in changeset.writes.keys) p.join(dir.path, relative),
  ]);
  await _clockPast(before);
  final staged = _stage({
    for (final entry in changeset.writes.entries)
      p.join(dir.path, entry.key): entry.value,
  });
  try {
    probe?.call(TomLocalCommitStep.staged);
    _recordIntent(dir, staged, changeset.deletes);
  } catch (_) {
    // Before the commit point: the container is untouched, and the temps
    // are all that has to go.
    _discard(staged.keys);
    rethrow;
  }
  // Past the commit point a failure is not undone. The intent stays, and
  // the next access to the container finishes what it records.
  probe?.call(TomLocalCommitStep.recorded);
  _applyIntent(dir);
  _advancePast(before);
  return (await headOf(locator))!;
}