commit method
Future<String>
commit(
- String locator,
- TomChangeset changeset, {
- String? expectedHead,
- String? message,
- 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;
});
}