Skip to content

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.

digest instance-attribute

digest: Digest

previous instance-attribute

previous: Digest | None

by instance-attribute

by: Subject

at instance-attribute

at: str

receipt class-attribute instance-attribute

receipt: Digest | None = None

meta class-attribute instance-attribute

meta: dict[str, Value] = field(default_factory=dict)

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_records.py
def __post_init__(self) -> None:
    check_timestamp(self.at, where="record.at")

to_json

to_json() -> dict[str, Value]

The record as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def to_json(self) -> dict[str, Value]:
    """The record as a JSON object."""
    return {
        "digest": str(self.digest),
        "previous": None if self.previous is None else str(self.previous),
        "by": self.by.to_json(),
        "at": self.at,
        "receipt": None if self.receipt is None else str(self.receipt),
        "meta": self.meta,
    }

from_json classmethod

from_json(value: Value) -> RefRecord

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
@classmethod
def from_json(cls, value: Value) -> RefRecord:
    """Decode a record from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The record.

    Raises:
        FormatError: when the shape or a field is wrong.
    """
    fields = expect_object(
        value, ("digest", "previous", "by", "at", "receipt", "meta"), where="record"
    )
    meta = fields["meta"]
    if not isinstance(meta, dict):
        raise FormatError("record.meta is not a JSON object")
    return cls(
        digest=expect_digest(fields["digest"], where="record.digest"),
        previous=expect_optional_digest(
            fields["previous"], where="record.previous"
        ),
        by=Subject.from_json(fields["by"], where="record.by"),
        at=expect_str(fields["at"], where="record.at"),
        receipt=expect_optional_digest(fields["receipt"], where="record.receipt"),
        meta=meta,
    )

encode

encode() -> bytes

The record's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def encode(self) -> bytes:
    """The record's canonical JSON bytes."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> RefRecord

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
@classmethod
def decode(cls, data: bytes) -> RefRecord:
    """Decode a record from its stored bytes.

    Args:
        data: the record file's bytes.

    Returns:
        The record.

    Raises:
        FormatError: when the bytes are not JSON, not a record, or
            not canonical.
    """
    return cls.from_json(_loads(data, what="record"))

Tombstone dataclass

Tombstone(digest: Digest, at: str, authority: Subject, receipt: Digest | None, reason: str)

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.

digest instance-attribute

digest: Digest

at instance-attribute

at: str

authority instance-attribute

authority: Subject

receipt instance-attribute

receipt: Digest | None

reason instance-attribute

reason: str

__post_init__

__post_init__() -> None
Source code in packages/strongroom/src/livery/strongroom/_records.py
def __post_init__(self) -> None:
    check_timestamp(self.at, where="tombstone.at")

to_json

to_json() -> dict[str, Value]

The tombstone as a JSON object.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def to_json(self) -> dict[str, Value]:
    """The tombstone as a JSON object."""
    return {
        "digest": str(self.digest),
        "at": self.at,
        "authority": self.authority.to_json(),
        "receipt": None if self.receipt is None else str(self.receipt),
        "reason": self.reason,
    }

from_json classmethod

from_json(value: Value) -> Tombstone

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
@classmethod
def from_json(cls, value: Value) -> Tombstone:
    """Decode a tombstone from its JSON value.

    Args:
        value: the JSON value.

    Returns:
        The tombstone.

    Raises:
        FormatError: when the shape or a field is wrong.
    """
    fields = expect_object(
        value, ("digest", "at", "authority", "receipt", "reason"), where="tombstone"
    )
    return cls(
        digest=expect_digest(fields["digest"], where="tombstone.digest"),
        at=expect_str(fields["at"], where="tombstone.at"),
        authority=Subject.from_json(
            fields["authority"], where="tombstone.authority"
        ),
        receipt=expect_optional_digest(
            fields["receipt"], where="tombstone.receipt"
        ),
        reason=expect_str(fields["reason"], where="tombstone.reason"),
    )

encode

encode() -> bytes

The tombstone's canonical JSON bytes.

Source code in packages/strongroom/src/livery/strongroom/_records.py
def encode(self) -> bytes:
    """The tombstone's canonical JSON bytes."""
    return canonical(self.to_json())

decode classmethod

decode(data: bytes) -> Tombstone

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.

Source code in packages/strongroom/src/livery/strongroom/_records.py
@classmethod
def decode(cls, data: bytes) -> Tombstone:
    """Decode a tombstone from its stored bytes.

    Args:
        data: the tombstone file's bytes.

    Returns:
        The tombstone.

    Raises:
        FormatError: when the bytes are not JSON, not a tombstone,
            or not canonical.
    """
    return cls.from_json(_loads(data, what="tombstone"))