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 {
  tomGuardChangeset(locator, changeset, this);
  final loc = await _locate(locator);
  // Force a refresh: a stale snapshot would let a lost race through.
  _snapshots.remove(loc.repoKey);
  var snapshot = await _snapshot(loc);

  if (snapshot == null && _emptyRepos.contains(loc.repoSlug)) {
    // Give the repository its first commit *before* uploading anything: in a
    // repository with no commits, every git-data write is refused, so the
    // save would otherwise fail on its first blob.
    await _bootstrapRepository(loc);
    _snapshots.remove(loc.repoKey);
    snapshot = await _snapshot(loc);
  }

  final actualHead = snapshot?.objectShaFor(loc.path);
  if (actualHead != expectedHead) {
    throw TomCasConflictException(
      locator,
      expectedHead: expectedHead,
      actualHead: actualHead,
    );
  }
  if (changeset.isEmpty) return actualHead ?? TomStorage.emptyHead;

  // Reported before each object and once more after the last, so a reader
  // learns *what* is in flight and how large it is, not only how much has
  // landed. The two matter separately: a twelve-object changeset moves the
  // bar twelve times, and a one-object changeset near the blob ceiling moves
  // it not at all — and for that one, naming the object is the whole of the
  // difference between "hung" and "sending 41.8 MB".
  var bytesDone = 0;
  var objectsDone = 0;
  final bytesTotal = changeset.writes.values.fold<int>(
    0,
    (sum, bytes) => sum + bytes.length,
  );
  final objectsTotal = changeset.writes.length;

  final entries = <GitHubTreeEntry>[];
  // What this save uploaded, by the sha GitHub gave it — stored once the
  // commit has landed, so the next read of what was just written round-trips
  // nothing.
  final written = <String, ({String path, Uint8List bytes})>{};
  for (final write in changeset.writes.entries) {
    final path = write.key == TomChangeset.containerPath
        ? loc.path
        : '${loc.path}/${write.key}';
    onProgress?.call(
      TomCommitProgress(
        bytesCompleted: bytesDone,
        bytesTotal: bytesTotal,
        objectsCompleted: objectsDone,
        objectsTotal: objectsTotal,
        currentPath: write.key,
        currentBytes: write.value.length,
      ),
    );
    final sha = await _wrap(
      locator,
      'upload $path',
      () => _api.git.createBlob(
        owner: loc.owner,
        repo: loc.repo,
        bytes: write.value,
      ),
    );
    bytesDone += write.value.length;
    objectsDone++;
    entries.add(GitHubTreeEntry(path: path, sha: sha));
    written[sha] = (path: path, bytes: write.value);
  }
  // `currentPath` drops to null while the tree, commit and ref steps run.
  // That is not "done" — the ref has not moved — and a reader that renders
  // it as "finishing" is telling the truth.
  onProgress?.call(
    TomCommitProgress(
      bytesCompleted: bytesDone,
      bytesTotal: bytesTotal,
      objectsCompleted: objectsDone,
      objectsTotal: objectsTotal,
    ),
  );
  for (final delete in changeset.deletes) {
    entries.add(GitHubTreeEntry.deletion('${loc.path}/$delete'));
  }

  return _wrap(locator, 'commit', () async {
    final tree = await _api.git.createTree(
      owner: loc.owner,
      repo: loc.repo,
      entries: entries,
      baseTreeSha: snapshot?.treeSha,
    );
    final commit = await _api.git.createCommit(
      owner: loc.owner,
      repo: loc.repo,
      message: message ?? '${commitMessagePrefix}save ${_basename(loc.path)}',
      treeSha: tree.sha,
      parentShas: [if (snapshot != null) snapshot.commitSha],
      author: committer,
      committer: committer,
    );
    try {
      if (snapshot == null) {
        await _api.git.createRef(
          owner: loc.owner,
          repo: loc.repo,
          ref: loc.refName,
          sha: commit.sha,
        );
      } else {
        await _api.git.updateRef(
          owner: loc.owner,
          repo: loc.repo,
          ref: loc.refName,
          sha: commit.sha,
        );
      }
      _recordAuthority(loc, commit.sha, tree.sha, snapshot?.commitSha);
    } on GitHubValidationException {
      // The branch moved between our read and this update — GitHub refused
      // the non-fast-forward. Not necessarily *our* document (the object-sha
      // check passed), but our commit is now unreachable, so the caller
      // re-reads, merges and retries, exactly as for any other lost race.
      _snapshots.remove(loc.repoKey);
      final head = (await _snapshot(loc))?.objectShaFor(loc.path);
      throw TomCasConflictException(
        locator,
        expectedHead: expectedHead,
        actualHead: head,
      );
    }
    // The branch now points at `commit`, and we know both it and the tree
    // beneath it — so the new head is a fact we hold, not one to go and
    // fetch. Re-reading the ref would cost three requests *and* make the
    // answer depend on GitHub serving our own write straight back to us,
    // which it does not promise: under concurrent traffic on a repository
    // the ref read can still answer with the commit we just replaced, and a
    // head that has not moved is indistinguishable from a save that did
    // nothing. The tree is fetched by sha instead, and a sha is content —
    // that read cannot be stale.
    final full = await _api.git.getTree(
      owner: loc.owner,
      repo: loc.repo,
      sha: tree.sha,
      recursive: true,
    );
    if (full.truncated) {
      throw TomStorageException(
        locator,
        'The repository tree is too large for a single listing; this backend '
        'cannot resolve document paths in it',
      );
    }
    // No ETag, because we never read the ref: the next poll of this branch
    // pays one full read. That is once per write, against a write that has
    // just cost several requests anyway — and that read is exactly the one
    // a replica can answer with the commit we just replaced, which is why
    // the write is also recorded as an authority above.
    final landed = _TreeSnapshot(
      commitSha: commit.sha,
      treeSha: tree.sha,
      tree: full,
    );
    _snapshots[loc.repoKey] = landed;
    await _remember(loc, landed);
    for (final blob in written.entries) {
      await cache?.writeBlob(
        blob.key,
        blob.value.bytes,
        opaque: _isOpaque(blob.value.path),
        owner: locator,
      );
    }
    final head = landed.objectShaFor(loc.path);
    if (head == null) {
      throw TomStorageException(
        locator,
        'The commit landed but left nothing at ${loc.path}',
      );
    }
    return head;
  });
}