TomLocalFileSystemStorage class

Containers on the local filesystem: a file, or a directory of files.

A multi-file changeset is applied all-or-nothing in three steps:

  1. Stage. Every write lands in a .tom-tmp sibling of its target. A failure here removes the temps and leaves the container untouched.
  2. Record. One intent file, intentName, names every rename and every delete the changeset makes. It is written to a temp and renamed into place, so it is either whole or absent — that rename is the commit point.
  3. Apply. The temps are renamed over their targets, the deletes are applied, and the intent is removed.

A crash before step 2 leaves temps beside an unchanged container; they are ignored by every read and swept by the next commit. A crash after it leaves an intent, and every entry point — reads included — finishes the recorded renames and deletes before it looks at the container. So no reader ever sees a half-applied changeset: it sees the old container until the intent exists and the whole new one from then on.

The head token is a digest of the container's own state — for a single file its size and modification time, for a directory the same over every part. It is opaque and only ever compared, which is what makes it interchangeable with a git commit sha. A file's time is read to the millisecond, so a commit writes only once the clock is past the previous time of every file it replaces: two same-size writes inside one millisecond would otherwise leave the head where it was, and a device holding the older head could commit over the newer write.

Inheritance

Constructors

TomLocalFileSystemStorage({TomLocalCommitProbe? probe})
const

Properties

hashCode → int
The hash code for this object.
no setterinherited
maxObjectBytes → int?
The largest a single path in a TomChangeset may be, or null when the backend imposes no limit of its own.
no setterinherited
probe → TomLocalCommitProbe?
Called between the steps of a directory commit — a test's way of failing one midway, as a crash would. Null in every production composition.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited

Methods

adoptBackoff(TomBackoffPolicy policy) → void
Adopts how long to hold off after a rate limit that stated no instant.
inherited
cacheMetaScope(String location) → List<String>?
The meta/ key prefix this backend keeps the records for the storage location location under, or null when it keeps none.
inherited
close() → void
inherited
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
Anything without a <scheme>: prefix. A bare Windows drive letter (C:\…) is a path, not a scheme, so it is deliberately not matched.
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?>>
headOf for several containers at once.
inherited
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
readBundle(String locator) → Future<TomBundleMedium>
A read-through view of the folder, not a copy of it.
override
readBytes(String locator) → Future<Uint8List>
The bytes of the single-file artifact at locator.
override
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.
inherited

Operators

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

Constants

intentName → const String
The recorded intent of a directory commit, inside the container.
lfsRemedy → const String
The remedy here is a different one from the GitHub backend's, and that is the whole reason the sentence is supplied per backend rather than baked into the refusal: on disk a pointer means the working tree was never smudged, which git lfs pull fixes. The diagnosis is identical; what the reader can do about it is not.
tempSuffix → const String
Marks a staged write. Shared with TomDirectoryBundleMedium, so a temp either of them leaves is invisible to the other.