TomGitHubStorage class

Containers committed straight into a GitHub repository.

The whole backend rests on one identification: a document's head is the git object sha of its path. That is a content hash, so it changes exactly when the document changes and never when something else in the repository does — which is what makes a per-document compare-and-swap possible on a repository several documents share.

A save is therefore one commit: blobs, one tree over the branch's tree, one commit, one non-forced ref update. GitHub's own refusal to fast-forward a moved branch is the outer CAS; the object-sha check is the inner one that tells "somebody edited this document" from "somebody committed elsewhere in the repo".

Inheritance

Constructors

TomGitHubStorage({required TomTokenSource tokens, GitHubApiClient clientFactory(String secret)?, DateTime clock()?, TomDiagnostics diagnostics = const TomNullDiagnostics(), TomStorageCache? cache, String commitMessagePrefix = '', GitHubGitIdentity? committer})
A backend that authenticates from tokens on first use (and re-reads them on every request — see authenticate). clientFactory builds the client from the secret; the default reaches api.github.com.
TomGitHubStorage.withClient(GitHubApiClient client, {DateTime clock()?, TomDiagnostics diagnostics = const TomNullDiagnostics(), TomStorageCache? cache, String commitMessagePrefix = '', GitHubGitIdentity? committer})
A backend over an already-authenticated client. For tests and for a caller that obtained a token some other way.

Properties

backoff → TomBackoffPolicy
How long to hold off after a rate limit GitHub stated no instant for.
no setter
cache → TomStorageCache?
The on-disk cache, or null for a backend that remembers only for the session.
final
cacheSizes → ({int authorities, int defaultBranches, int emptyRepos, int evictionsRemembered, int snapshots, int treeEntries})
What this client is currently holding, for the tests that assert it is bounded.
no setter
commitMessagePrefix → String
Put before the commit messages this backend writes itself — save <name>, delete <name>, initialize repository — so an application can name itself in the repository's history (myapp: save notes.yaml). A message the caller passes to commit is used as it is.
final
committer → GitHubGitIdentity?
Who the commits of commit and delete name as author and committer, e.g. a device (bigbeast <bigbeast@tsm.invalid>); null leaves both to GitHub, which records the token's owner. The README commit that bootstraps an empty repository goes through the contents API and is always the token owner's.
final
diagnostics → TomDiagnostics
Where cache evictions are reported. A discard unless a composition root binds one.
final
hashCode → int
The hash code for this object.
no setterinherited
jitterSource ↔ double Function()
Samples the backoff jitter, in [0, 1). Injectable for tests.
getter/setter pair
maxCachedTreeEntries ↔ int
How much tree _snapshots may hold, counted in entries across every cached branch.
getter/setter pair
maxObjectBytes → int?
The largest a single path in a TomChangeset may be, or null when the backend imposes no limit of its own.
no setteroverride
refLagWatch ↔ Duration
How long after refReplicaWindow has passed a write is still remembered, for reporting only.
getter/setter pair
refReplicaWindow ↔ Duration
How long a landed write out-ranks a ref read that contradicts it.
getter/setter pair
requestCounts → ({int notModified, int requests})
What this backend's own HTTP client has spent, and how much of it was free.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
thrashWindow ↔ Duration
How soon after its eviction a branch has to be wanted again for that to count as thrash rather than housekeeping.
getter/setter pair

Methods

adoptBackoff(TomBackoffPolicy policy) → void
Adopts how long to hold off after a rate limit that stated no instant.
override
authenticate() → Future<void>
Resolves the credential, lazily and on every request.
cacheMetaScope(String location) → List<String>?
github/<owner>/<repo>: tree listings and the default branch are kept per repository, so a location naming a folder answers its repository. Parsed leniently, because a location may name the repository root (github:owner/repo), which is no document locator.
override
close() → void
override
commit(String locator, TomChangeset changeset, {String? expectedHead, String? message, TomCommitProgressSink? onProgress}) → Future<String>
Applies changeset atomically, refusing the write if the container has moved away from expectedHead.
override
delete(String locator) → Future<void>
Removes the whole container.
override
handles(String locator) → bool
Whether this backend owns locator's scheme.
override
headOf(String locator) → Future<String?>
The current revision of the container, or null when it does not exist.
override
headsOf(Iterable<String> locators) → Future<Map<String, String?>>
Groups locators by repository and branch so every open document on one branch is answered from a single snapshot — and, when nothing has moved, from a single conditional request that costs no rate-limit quota.
override
list(String locator) → Future<List<TomStorageEntry>>
Entries directly inside the container at locator.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
readBlobAt(TomGitHubLocator loc, String locator, String path, String sha) → Future<Uint8List>
One blob, refused when what the tree holds is a Git-LFS pointer.
readBundle(String locator) → Future<TomBundleMedium>
A medium that fetches a member when it is asked for.
override
readBytes(String locator) → Future<Uint8List>
The bytes of the single-file artifact at locator.
override
resetRequestCounts() → void
Zero the tally, to measure one stretch of traffic.
toString() → String
A string representation of this object.
inherited
withinPass<T>(Future<T> body()) → Future<T>
Runs body as one pass: a stretch of work whose reads may share what the pass has already established about the remote.
override

Operators

operator ==(Object other) → bool
The equality operator.
inherited

Constants

defaultThrashWindow → const Duration
Five minutes: a sync loop's default poll interval, as the stand-in for one tick.
host → const String
The host TomTokenSource is asked for a credential under.
maxBlobBytes → const int
The largest blob the git-data API accepts, measured rather than read off documentation — 41,820,160 B was accepted and 41,943,040 B (exactly 40 MiB) was refused with a 422, so the ceiling is at 40 MiB and the last accepted size is the one worth naming.