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,
  TomCommitProgressSink? onProgress,
}) async {
  // Guarded as every backend's commit is, so a double that is given a
  // ceiling refuses an oversized object the way a real backend does.
  tomGuardChangeset(locator, changeset, this);
  final until = rateLimitedUntil;
  if (until != null) {
    throw TomRateLimitException(locator, kind: rateLimitKind, resetAt: until);
  }
  if (writesFail) {
    throw TomUnreachableException(locator, 'device is offline');
  }
  final actual = remote.headOf(locator);
  if (actual != expectedHead) {
    throw TomCasConflictException(
      locator,
      expectedHead: expectedHead,
      actualHead: actual,
    );
  }
  onCommit?.call();
  if (changeset.isEmpty) return actual ?? TomStorage.emptyHead;
  return remote.apply(locator, changeset, message);
}