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
-
- Object
- TomStorage
- TomGitHubStorage
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
tokenson first use (and re-reads them on every request — see authenticate).clientFactorybuilds the client from the secret; the default reachesapi.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
_snapshotsmay 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
changesetatomically, refusing the write if the container has moved away fromexpectedHead.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
bodyas 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.