livery.strongroom._records¶
livery.strongroom._records ¶
The ref record and the tombstone: the two records beside names.
A ref record is written beside a ref on every update, so the provenance of a name is a file and never a log to reconstruct. A tombstone is what an erased object becomes: the name stays, the bytes go, and the fact is kept in every tier. Both are canonical JSON, and neither is an object in the store: a record lives beside the ref, a tombstone under the object's path.
Reach for livery.strongroom.RefRecord and livery.strongroom.Tombstone.
Classes:
| Name | Description |
|---|---|
RefRecord |
What a ref update writes beside the ref. |
Tombstone |
What an erased object becomes, in every tier. |
RefRecord
dataclass
¶
RefRecord(digest: Digest, previous: Digest | None, by: Subject, at: str, receipt: Digest | None = None, meta: dict[str, Value] = dict())
What a ref update writes beside the ref.
Attributes:
| Name | Type | Description |
|---|---|---|
digest |
Digest
|
what the ref names after the update. |
previous |
Digest | None
|
what it named before, or None on creation. |
by |
Subject
|
who moved it. |
at |
str
|
when, as an RFC 3339 UTC instant. |
receipt |
Digest | None
|
across a trust boundary, the signed receipt of the call that moved the ref; None under local custody. |
meta |
dict[str, Value]
|
an opaque object a consumer may use, such as validators for a URL or a freshness window for a query. Strongroom stores it and never reads it. |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
to_json |
The record as a JSON object. |
from_json |
Decode a record from its JSON value. |
encode |
The record's canonical JSON bytes. |
decode |
Decode a record from its stored bytes. |
__post_init__ ¶
to_json ¶
The record as a JSON object.
Source code in packages/strongroom/src/livery/strongroom/_records.py
from_json
classmethod
¶
Decode a record from its JSON value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Value
|
the JSON value. |
required |
Returns:
| Type | Description |
|---|---|
RefRecord
|
The record. |
Raises:
| Type | Description |
|---|---|
FormatError
|
when the shape or a field is wrong. |
Source code in packages/strongroom/src/livery/strongroom/_records.py
decode
classmethod
¶
Decode a record from its stored bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytes
|
the record file's bytes. |
required |
Returns:
| Type | Description |
|---|---|
RefRecord
|
The record. |
Raises:
| Type | Description |
|---|---|
FormatError
|
when the bytes are not JSON, not a record, or not canonical. |
Source code in packages/strongroom/src/livery/strongroom/_records.py
Tombstone
dataclass
¶
What an erased object becomes, in every tier.
Attributes:
| Name | Type | Description |
|---|---|---|
digest |
Digest
|
the erased object's name, which stays valid in every tree that names it. |
at |
str
|
when, as an RFC 3339 UTC instant. |
authority |
Subject
|
who erased it. |
receipt |
Digest | None
|
the receipt of the erasing call, or None under local custody. |
reason |
str
|
free text, shown to a reader whose view meets the erased entry. |
Methods:
| Name | Description |
|---|---|
__post_init__ |
|
to_json |
The tombstone as a JSON object. |
from_json |
Decode a tombstone from its JSON value. |
encode |
The tombstone's canonical JSON bytes. |
decode |
Decode a tombstone from its stored bytes. |
__post_init__ ¶
to_json ¶
The tombstone as a JSON object.
Source code in packages/strongroom/src/livery/strongroom/_records.py
from_json
classmethod
¶
Decode a tombstone from its JSON value.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
value
|
Value
|
the JSON value. |
required |
Returns:
| Type | Description |
|---|---|
Tombstone
|
The tombstone. |
Raises:
| Type | Description |
|---|---|
FormatError
|
when the shape or a field is wrong. |
Source code in packages/strongroom/src/livery/strongroom/_records.py
decode
classmethod
¶
Decode a tombstone from its stored bytes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
bytes
|
the tombstone file's bytes. |
required |
Returns:
| Type | Description |
|---|---|
Tombstone
|
The tombstone. |
Raises:
| Type | Description |
|---|---|
FormatError
|
when the bytes are not JSON, not a tombstone, or not canonical. |