livery.strongroom._store¶
livery.strongroom._store ¶
The local store: objects landed by digest, refs moved by compare-and-swap.
A store is a directory with a root manifest, an objects/ tree, a
refs/ tree and a local index. Objects are immutable and idempotent
to land; refs are the only mutable thing, and every move writes a
record beside the ref under a per-ref lock. The layout is the one in
spec/layout.md; the index under index/ is this implementation's
own and not a format.
Reach for livery.strongroom.Store: create or open, then land
and path for objects, ref and set_ref for names.
Classes:
| Name | Description |
|---|---|
Manifest |
The root manifest: which layout and which algorithm this store speaks. |
Namespace |
A ref namespace and its mutation class. |
Landed |
What a landing produced. |
ScrubReport |
What a scrub found. |
Store |
A local store: |
Functions:
| Name | Description |
|---|---|
now |
The current instant, RFC 3339 in UTC to the second. |
silent |
The default progress sink: report nothing. |
Attributes:
| Name | Type | Description |
|---|---|---|
MANIFEST_NAME |
The root manifest's file name. |
|
LAYOUT_VERSION |
The layout this implementation speaks. |
|
MutationClass |
How a namespace's refs may move; see |
|
ObjectState |
The three states an object name can be in. |
|
MUTATION_CLASSES |
tuple[MutationClass, ...]
|
|
Clock |
Returns the current instant as an RFC 3339 UTC string. |
|
OWNED |
tuple[Namespace, ...]
|
The two namespaces the store declares itself; see |
MutationClass
module-attribute
¶
MutationClass = Literal['write-once', 'monotone', 'volatile']
How a namespace's refs may move; see spec/namespaces.md.
ObjectState
module-attribute
¶
ObjectState = Literal['present', 'absent', 'erased']
The three states an object name can be in.
MUTATION_CLASSES
module-attribute
¶
MUTATION_CLASSES: tuple[MutationClass, ...] = ('write-once', 'monotone', 'volatile')
Clock
module-attribute
¶
Returns the current instant as an RFC 3339 UTC string.
OWNED
module-attribute
¶
The two namespaces the store declares itself; see spec/namespaces.md.
Manifest
dataclass
¶
The root manifest: which layout and which algorithm this store speaks.
Attributes:
| Name | Type | Description |
|---|---|---|
layout |
int
|
the layout version. |
algorithm |
str
|
the one algorithm of this address space. |
Methods:
| Name | Description |
|---|---|
encode |
The manifest's canonical JSON bytes. |
decode |
Decode a manifest, refusing bytes that are not one. |
decode
classmethod
¶
Decode a manifest, refusing bytes that are not one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytes
|
the manifest file's bytes. |
required |
Returns:
| Type | Description |
|---|---|
Manifest
|
The manifest. |
Raises:
| Type | Description |
|---|---|
ManifestError
|
when the bytes are not a manifest. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
Namespace
dataclass
¶
Namespace(name: str, mutation: MutationClass)
A ref namespace and its mutation class.
Attributes:
| Name | Type | Description |
|---|---|---|
name |
str
|
the namespace, lowercase letters, digits and dashes. |
mutation |
MutationClass
|
how its refs may move. |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
__post_init__ ¶
Source code in packages/strongroom/src/livery/strongroom/_store.py
Landed
dataclass
¶
ScrubReport
dataclass
¶
Store ¶
Store(root: Path, algorithm: Algorithm, namespaces: Iterable[Namespace], *, clock: Clock, lock_stale: float, lock_timeout: float, sources: Iterable[Source], offline: bool, progress: Progress)
A local store: objects/ by digest, refs/ by name.
Open one with livery.strongroom.Store.create or
livery.strongroom.Store.open. Every namespace a caller will
write is declared at open with its mutation class; pins/ and
pending/ are declared by the store.
Attributes:
| Name | Type | Description |
|---|---|---|
root |
Path
|
the store's directory. |
algorithm |
Algorithm
|
the address space's algorithm. |
namespaces |
dict[str, Namespace]
|
every declared namespace by name. |
sources |
tuple[Source, ...]
|
the sources consulted in order for an object the local directory lacks. |
offline |
bool
|
whether origin hints are never consulted. |
Methods:
| Name | Description |
|---|---|
create |
Create a store at root and open it. |
open |
Open the store at root. |
object_path |
The path an object of digest lives at, present or not. |
state |
Whether digest is present, absent, or erased here. |
land |
Land bytes as an object, verifying them on the way in. |
put |
Land data and return its name. |
path |
A read-only path to the object, verified on first access. |
read |
The object's bytes, through livery.strongroom.Store.path. |
verify |
Hash the object in full and mark it verified. |
verified_size |
The size this store verified the object at, or None if never. |
objects |
Every object present here, in no particular order. |
scrub |
Hash every object and remove the ones that do not match. |
fetch |
A path to the object, consulting the sources when it is not here. |
fill |
Land digests into the folder tier at target. |
tombstone |
The tombstone under the object's path, or None when there is none. |
write_tombstone |
Write stone under its object's path, in this tier. |
evict |
Remove the object's bytes and its marks; the name is untouched. |
clock |
The current instant, from the clock the store was opened with. |
publish_begin |
Begin a publish: root target under |
publish_commit |
Commit a publish: move the real ref, then drop the pending one. |
retire |
Drop a pending ref deliberately, for a publish that will not commit. |
pendings |
Every pending publish's id, sorted; groups included. |
begin |
Open a group of ref moves: an empty journal under |
add |
Append a move to the group; its manifest roots the target from now on. |
commit |
Apply the group's moves, every one or none, and drop the pending ref. |
group |
The group under |
groups |
Every group that has begun and not committed, sorted by id. |
transaction |
A group under a |
drop_ref |
Remove a volatile ref and its record by compare-and-swap. |
pin |
Root digest under |
unpin |
Drop |
erase |
Erase the object's bytes and keep the fact as a tombstone. |
reachable |
Every object reachable from digest, itself included. |
roots |
Every root: what every ref on disk names, and every live view's tree. |
sweep |
Remove every object no root reaches, and old scratch. |
view |
Fill at from the tree by the cheapest safe rung per entry. |
views |
Every recorded view, live or not, by id. |
view_record |
The record of one view, or None. |
drop_view |
Remove what the view's record lists, and nothing else. |
collect |
Read the declared paths under at back into a tree, landing every object. |
prefetch |
Fetch digest and everything it reaches, for offline use. |
shed |
Evict every local copy source holds, except what a live view needs. |
head |
Whether the HTTP source answers a HEAD for relative. |
ref_path |
The file a ref lives at, present or not. |
ref |
What the ref names, or None when it does not exist. |
record |
The record beside the ref, or None when there is none. |
refs |
Every ref path in the namespace, sorted. |
set_ref |
Move a ref by compare-and-swap, writing its record. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
namespaces
instance-attribute
¶
create
classmethod
¶
create(root: Path, *, algorithm: str = 'sha256', namespaces: Iterable[Namespace] = (), clock: Clock = now, lock_stale: float = 600.0, lock_timeout: float = 30.0, sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent) -> Store
Create a store at root and open it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
the directory; created when missing. |
required |
algorithm
|
str
|
a registry entry's name. |
'sha256'
|
namespaces
|
Iterable[Namespace]
|
the caller's namespaces, each with its class. |
()
|
clock
|
Clock
|
the instant source for records. |
now
|
lock_stale
|
float
|
seconds after which a lock is broken even when its holder looks alive: the pid of a holder that died can belong to another process by then. |
600.0
|
lock_timeout
|
float
|
seconds to wait for a live lock. |
30.0
|
sources
|
Iterable[Source]
|
where to look for an object the store lacks, in order. A folder source is checked now; an HTTP source on first use. |
()
|
offline
|
bool
|
never consult an origin hint. |
False
|
progress
|
Progress
|
where a fetch reports a skipped or refused source; silent by default. |
silent
|
Returns:
| Type | Description |
|---|---|
Store
|
The open store. |
Raises:
| Type | Description |
|---|---|
ManifestError
|
when root already holds a manifest. |
FormatError
|
when the algorithm is not registered. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
open
classmethod
¶
open(root: Path, *, namespaces: Iterable[Namespace] = (), clock: Clock = now, lock_stale: float = 600.0, lock_timeout: float = 30.0, sources: Iterable[Source] = (), offline: bool = False, progress: Progress = silent) -> Store
Open the store at root.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
root
|
Path
|
the store's directory. |
required |
namespaces
|
Iterable[Namespace]
|
the caller's namespaces, each with its class. |
()
|
clock
|
Clock
|
the instant source for records. |
now
|
lock_stale
|
float
|
seconds after which a lock is broken even when its holder looks alive: the pid of a holder that died can belong to another process by then. |
600.0
|
lock_timeout
|
float
|
seconds to wait for a live lock. |
30.0
|
sources
|
Iterable[Source]
|
where to look for an object the store lacks, in order. A folder source is checked now; an HTTP source on first use. |
()
|
offline
|
bool
|
never consult an origin hint. |
False
|
progress
|
Progress
|
where a fetch reports a skipped or refused source; silent by default. |
silent
|
Returns:
| Type | Description |
|---|---|
Store
|
The store. |
Raises:
| Type | Description |
|---|---|
ManifestError
|
when the manifest is missing or malformed, or names a layout or an algorithm this implementation does not speak; or when a folder source's manifest is missing or of another store. |
ValueError
|
when a namespace is declared twice with different classes. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
object_path ¶
The path an object of digest lives at, present or not.
Raises:
| Type | Description |
|---|---|
IntegrityError
|
when the digest is of another algorithm than this store's; one address space, one algorithm. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
state ¶
state(digest: Digest) -> ObjectState
Whether digest is present, absent, or erased here.
Source code in packages/strongroom/src/livery/strongroom/_store.py
land ¶
Land bytes as an object, verifying them on the way in.
The bytes stream through the digest into a .part scratch file
and are moved into place atomically. Landing is idempotent: an
object that already exists is success without a write. Two
writers of the same digest land identical bytes, so no lock is
taken.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source
|
IO[bytes] | bytes
|
the bytes, or a binary stream read to its end. |
required |
expected
|
Digest | None
|
the digest the bytes must have, when known. A mismatch removes the scratch and raises. |
None
|
Returns:
| Type | Description |
|---|---|
Landed
|
The landing. |
Raises:
| Type | Description |
|---|---|
IntegrityError
|
when expected is given and the bytes do not match it. |
ErasedObject
|
when the object was erased here; its tombstone stands until a sweep decides otherwise. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
put ¶
path ¶
A read-only path to the object, verified on first access.
Size is checked against the verified mark on every access; an object without a mark (landed by copy, not by this store) is hashed in full and marked.
Raises:
| Type | Description |
|---|---|
MissingObject
|
when the object is absent. |
ErasedObject
|
when the object was erased. |
IntegrityError
|
when the bytes do not match the name; the object and its mark are removed so a fill lands it again. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
read ¶
The object's bytes, through livery.strongroom.Store.path.
verify ¶
Hash the object in full and mark it verified.
Returns:
| Type | Description |
|---|---|
int
|
The object's size. |
Raises:
| Type | Description |
|---|---|
MissingObject
|
when the object is absent. |
IntegrityError
|
when the bytes do not match; the object and its mark are removed. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
verified_size ¶
The size this store verified the object at, or None if never.
Source code in packages/strongroom/src/livery/strongroom/_store.py
objects ¶
Every object present here, in no particular order.
Source code in packages/strongroom/src/livery/strongroom/_store.py
scrub ¶
scrub() -> ScrubReport
Hash every object and remove the ones that do not match.
Source code in packages/strongroom/src/livery/strongroom/_store.py
fetch ¶
A path to the object, consulting the sources when it is not here.
Sources are consulted in order. A hit is verified on arrival: a copy-policy folder, an HTTP tier and an origin hint land the bytes here; a reference-policy folder answers with a path into the folder and lands nothing. An unreachable source is skipped and reported; a source serving wrong bytes is refused and reported, and the next one consulted. An origin hint is consulted only for its own digest and never when offline.
Returns:
| Type | Description |
|---|---|
Path
|
A read-only path: this store's object, or the folder's |
Path
|
under a reference policy. |
Raises:
| Type | Description |
|---|---|
MissingObject
|
when no source has it. The message names the digest, and when an origin hint was passed over because the store is offline, the URL that would have satisfied it. |
ErasedObject
|
when the object was erased here. |
ManifestError
|
when an HTTP source's manifest is of another store. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
fill ¶
Land digests into the folder tier at target.
The folder becomes a store of this store's algorithm when it is not one already, and afterwards opens as a livery.strongroom.FolderSource that serves every filled digest. Each object is fetched through this store's sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Path
|
the folder; created when missing. |
required |
digests
|
Iterable[Digest]
|
the objects to land there. |
required |
Returns:
| Type | Description |
|---|---|
list[Landed]
|
One landing per digest, in order. |
Raises:
| Type | Description |
|---|---|
ManifestError
|
when target is a store of another layout or algorithm. |
MissingObject
|
when a digest is not obtainable. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
tombstone ¶
The tombstone under the object's path, or None when there is none.
Raises:
| Type | Description |
|---|---|
IntegrityError
|
when the file under the tombstone's name is not a tombstone. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
write_tombstone ¶
write_tombstone(stone: Tombstone) -> None
Write stone under its object's path, in this tier.
Source code in packages/strongroom/src/livery/strongroom/_store.py
evict ¶
evict(digest: Digest) -> None
Remove the object's bytes and its marks; the name is untouched.
Source code in packages/strongroom/src/livery/strongroom/_store.py
publish_begin ¶
Begin a publish: root target under pending/<id> first.
The pending ref is a root while it exists, so a sweep during the publish keeps every object the target names. Nothing removes a pending ref on a clock; a crashed publish is retired deliberately with livery.strongroom.Store.retire.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
Digest
|
the tree or version to publish; present here. |
required |
by
|
Subject
|
who publishes. |
required |
lease
|
float
|
seconds the publish expects to take; recorded in the pending ref's record for whoever retires it. |
3600.0
|
Returns:
| Type | Description |
|---|---|
Pending
|
The pending publish. |
Raises:
| Type | Description |
|---|---|
MissingObject
|
when target is not present here. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
publish_commit ¶
publish_commit(pending_id: str, namespace: str, path: str, *, previous: Digest | None, by: Subject, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> RefRecord
Commit a publish: move the real ref, then drop the pending one.
The move obeys the namespace's mutation class exactly as livery.strongroom.Store.set_ref does.
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when |
RefConflict
|
when the real ref does not name previous, or its class refuses the move. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
retire ¶
Drop a pending ref deliberately, for a publish that will not commit.
Returns:
| Type | Description |
|---|---|
Digest
|
What the pending ref named. |
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when it does not exist. |
GroupHalfApplied
|
when it is a group a commit already applied part of; only a commit finishes it. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
pendings ¶
begin ¶
add ¶
add(group_id: str, namespace: str, path: str, digest: Digest, *, previous: Digest | None, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> Group
Append a move to the group; its manifest roots the target from now on.
The arguments are livery.strongroom.Store.set_ref's. The move is checked at commit, not here; only the target's presence is required now.
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when the group does not exist. |
NotAGroup
|
when |
GroupHalfApplied
|
when a commit already applied part of it. |
MissingObject
|
when digest is not present here. |
RefConflict
|
when the group already moves that ref. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
commit ¶
Apply the group's moves, every one or none, and drop the pending ref.
Holds the maintenance lease and the moved refs' locks for the checks and the moves only. A commit that stopped between two applies is finished by calling this again with the same id.
Returns:
| Type | Description |
|---|---|
tuple[RefRecord, ...]
|
One record per move, in order. |
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when the group does not exist. |
NotAGroup
|
when |
RefConflict
|
when a ref does not name its expected previous or its class refuses the move; nothing moved. |
LockTimeout
|
when the lease or a lock outlasts the timeout. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
group ¶
The group under pending/<group_id>.
Raises:
| Type | Description |
|---|---|
NoSuchPending
|
when it does not exist. |
NotAGroup
|
when it is a single publish's. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
groups ¶
transaction ¶
transaction(*, by: Subject, lease: float = 3600.0) -> AbstractContextManager[Transaction]
A group under a with: record moves, and the exit commits or retires.
with store.transaction(by=me) as tx:
tx.move("tools", "bun@1.3", tree, previous=None)
tx.move("datasets", "corpus/main", version, previous=v1)
records = tx.records
See livery.strongroom.Transaction for what each exit does.
Source code in packages/strongroom/src/livery/strongroom/_store.py
drop_ref ¶
Remove a volatile ref and its record by compare-and-swap.
Raises:
| Type | Description |
|---|---|
RefProtected
|
when the namespace is write-once or monotone. |
RefConflict
|
when the ref does not name previous. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
pin ¶
Root digest under pins/<name>, replacing an earlier pin of that name.
unpin ¶
Drop pins/<name> under the maintenance lease, never beside a sweep.
Returns:
| Type | Description |
|---|---|
Digest
|
What the pin named. |
Raises:
| Type | Description |
|---|---|
RefConflict
|
when the pin does not exist. |
LockTimeout
|
when a sweep holds the lease past the timeout. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
erase ¶
Erase the object's bytes and keep the fact as a tombstone.
The name stays valid in every tree that carries it; a path to the object raises naming this tombstone's reason; landing the bytes again is refused while the tombstone stands. An absent object may be erased too, which refuses its future landing.
Source code in packages/strongroom/src/livery/strongroom/_store.py
reachable ¶
Every object reachable from digest, itself included.
Structured formats are read by shape, never by namespace: a version yields its tree, parents, receipt and attachments, a tree its entries, anything else nothing. An absent or erased digest is yielded and not walked.
Source code in packages/strongroom/src/livery/strongroom/_store.py
roots ¶
Every root: what every ref on disk names, and every live view's tree.
Namespaces are read from disk, not from the declaration at open, so a consumer's refs root its objects whoever opened the store. A ref file that is not a digest roots nothing. A view whose directory is gone is retired here rather than rooted.
Source code in packages/strongroom/src/livery/strongroom/_store.py
sweep ¶
sweep(*, scratch_age: float = 86400.0) -> SweepReport
Remove every object no root reaches, and old scratch.
Runs under the maintenance lease. Pending refs are read again immediately before deleting, so a publish that began during the sweep roots its objects. Tombstones are never removed.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scratch_age
|
float
|
seconds after which an orphaned |
86400.0
|
Returns:
| Type | Description |
|---|---|
SweepReport
|
The report. |
Raises:
| Type | Description |
|---|---|
LockTimeout
|
when another maintenance holds the lease past the timeout. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
view ¶
view(tree: Digest, at: Path, *, writable: bool = False, allow_hardlink: bool = False) -> ViewRecord
Fill at from the tree by the cheapest safe rung per entry.
The ladder is clone, hardlink, link, copy; a rung that refuses once is not tried again for this view. A hardlink is refused into a writable view unless allow_hardlink says the view's consumers never write in place; a link is refused from a writable view. An executable entry never shares an inode or a target's mode. A symlink entry becomes a real symlink where the platform allows, the within-view target's content as a marked copy where it does not, and a parked refusal when the target escapes the view. Blobs are fetched through the sources.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tree
|
Digest
|
the tree to present; fetched if absent here. |
required |
at
|
Path
|
the directory to fill; missing or empty. |
required |
writable
|
bool
|
whether the caller will write in the view. |
False
|
allow_hardlink
|
bool
|
allow hardlinks into a writable view. |
False
|
Returns:
| Type | Description |
|---|---|
ViewRecord
|
The record, listing every path and its rung. The view is a |
ViewRecord
|
root while its directory exists. |
Raises:
| Type | Description |
|---|---|
FileExistsError
|
when at exists and is not an empty directory. |
MissingObject
|
when a blob is obtainable from no source, naming the entry's path. |
ErasedObject
|
when a blob was erased, naming the entry's path and the tombstone's reason. |
FormatError
|
when a path in the tree is over the budget. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
views ¶
views() -> list[ViewRecord]
view_record ¶
view_record(view_id: str) -> ViewRecord | None
drop_view ¶
drop_view(view_id: str) -> DropReport
Remove what the view's record lists, and nothing else.
A path inside the view that the record does not list is left and named; so is a directory that then stays non-empty, the view's root included. A view whose directory is already gone is retired with nothing removed. The record goes either way.
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
when no such view is recorded. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
collect ¶
Read the declared paths under at back into a tree, landing every object.
A declared directory is collected whole; an undeclared path is not read. Names must be portable and paths within the budget.
A blob's executable bit comes from a ladder: a path named in executable is executable on every platform, so one call lands one tree everywhere; otherwise the file mode where it carries the bit; where it does not, the record of the view that made the path, then the platform's reading of a new file, the extension on Windows; otherwise false.
A symlink whose target stays inside at is content, an absolute target recorded as the relative path from the link's directory. One that leaves at is the link rung's own symlink into this store, read through as the blob it presents, when the view's record says so or the target lands under this store's root; any other is refused.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
at
|
Path
|
the directory to read. |
required |
declared
|
Iterable[str]
|
the paths to collect, relative and forward-slashed. |
required |
executable
|
Iterable[str]
|
the paths that are executable, spelled the same. |
()
|
Returns:
| Type | Description |
|---|---|
Tree
|
The root tree, landed here with every subtree. |
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
when a declared path, or a declared executable, is absent. |
FormatError
|
when a name or a symlink target breaks a rule, a symlink escapes at, or a path is over the budget. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
prefetch ¶
Fetch digest and everything it reaches, for offline use.
Returns:
| Type | Description |
|---|---|
list[Digest]
|
Every object fetched, the root first. |
Raises:
| Type | Description |
|---|---|
MissingObject
|
naming the first digest no source answered. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
shed ¶
shed(source: Source) -> ShedReport
Evict every local copy source holds, except what a live view needs.
Holding is checked by existence in a folder, a HEAD on an HTTP source, or the digest an origin hint names; never by trust. The next fetch verifies on arrival, so a lying source costs a named miss and never a wrong byte. Objects a live view reaches through a hardlink or a link are kept.
Source code in packages/strongroom/src/livery/strongroom/_store.py
head ¶
head(source: HttpSource, relative: str) -> bool
Whether the HTTP source answers a HEAD for relative.
Source code in packages/strongroom/src/livery/strongroom/_store.py
ref_path ¶
The file a ref lives at, present or not.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
a declared namespace. |
required |
path
|
str
|
the ref's path within it, forward-slashed; each component is a portable name and none ends in a reserved suffix. |
required |
Raises:
| Type | Description |
|---|---|
UnknownNamespace
|
when the namespace was not declared. |
FormatError
|
when a path component breaks a rule. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
ref ¶
What the ref names, or None when it does not exist.
Raises:
| Type | Description |
|---|---|
RefTampered
|
when the ref and its record disagree, or the record is missing or malformed. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
record ¶
The record beside the ref, or None when there is none.
Raises:
| Type | Description |
|---|---|
RefTampered
|
when the record's bytes are not a record. |
Source code in packages/strongroom/src/livery/strongroom/_store.py
refs ¶
Every ref path in the namespace, sorted.
Source code in packages/strongroom/src/livery/strongroom/_store.py
set_ref ¶
set_ref(namespace: str, path: str, digest: Digest, *, previous: Digest | None, by: Subject, receipt: Digest | None = None, meta: dict[str, Value] | None = None) -> RefRecord
Move a ref by compare-and-swap, writing its record.
The move happens under the ref's lock. The namespace's mutation class is enforced: write-once refuses a second digest and treats the same digest as done; monotone requires the new target to be a version present here whose parents include the current target; volatile needs only the compare-and-swap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
namespace
|
str
|
a declared namespace. |
required |
path
|
str
|
the ref's path. |
required |
digest
|
Digest
|
what the ref names afterwards. |
required |
previous
|
Digest | None
|
what the caller believes it names now; None to create. |
required |
by
|
Subject
|
who moves it. |
required |
receipt
|
Digest | None
|
the receipt of the moving call, if any. |
None
|
meta
|
dict[str, Value] | None
|
the consumer's own object for the record. |
None
|
Returns:
| Type | Description |
|---|---|
RefRecord
|
The record written, or the existing record when a |
RefRecord
|
write-once ref already names digest. |
Raises:
| Type | Description |
|---|---|
RefConflict
|
when the ref does not name previous. |
WriteOnceRefused
|
on a write-once ref that names another digest. |
NotFastForward
|
on a monotone ref whose new target does not descend from the current one, or is not a version here. |
LockTimeout
|
when a live lock outlasts the timeout. |
RefTampered
|
when the ref and its record disagree. |