GitHub

StorageCompaction

API reference for StorageCompaction.

Storage primitives for encrypted remote compaction (Effect's StorageCompaction). The server owns the policy; each primitive is atomic per store.

A store always has one active activation, the originals (base first_sequence - 1) before the first commit. begin opens a stage pinned to it and to through; the claim expires stage_ttl after begin or the latest stored Part, and begin takes over an expired one. Stage primitives fail with CompactionNotFound once the stage expired, was aborted or committed, or belongs to another store. rollback reactivates the previous generation and re-appends, at the head, the input of the stage that built the withdrawn one. A sweep prunes a generation, and the originals it replaced, grace after it was superseded or withdrawn.

Attributes

AttributeTypeDescription
configCompactionConfig

Functions

status

status(public_key, store_id) -> Effect[CompactionStoreStatus]
ParameterTypeDescription
public_keystr
store_idStoreId

Returns Effect[CompactionStoreStatus]

@abstractmethod
def status(self, public_key: str, store_id: StoreId, /) -> Effect[CompactionStoreStatus]: ...

begin

begin(public_key, store_id, /, *, through) -> Effect[CompactionBeginResult]
ParameterTypeDescription
public_keystr
store_idStoreId
throughint

Returns Effect[CompactionBeginResult]

@abstractmethod
def begin(
    self, public_key: str, store_id: StoreId, /, *, through: int
) -> Effect[CompactionBeginResult]: ...

input_headers

input_headers(public_key, store_id, stage_id) -> Stream[CompactionBatchHeader, CompactionNotFound]

Batch headers in input order: the pinned batch set, then the originals in (base, through].

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr

Returns Stream[CompactionBatchHeader, CompactionNotFound]

@abstractmethod
def input_headers(
    self, public_key: str, store_id: StoreId, stage_id: str, /
) -> Stream[CompactionBatchHeader, CompactionNotFound]:
    """Batch headers in input order: the pinned batch set, then the
    originals in ``(base, through]``."""

fetch

fetch(public_key, store_id, stage_id, sequences) -> Stream[EncryptedRemoteBatch, CompactionNotFound]

Input batches by input sequence: snapshot batches at or below the pinned base, originals above it.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr
sequencesSequence[int]

Returns Stream[EncryptedRemoteBatch, CompactionNotFound]

@abstractmethod
def fetch(
    self, public_key: str, store_id: StoreId, stage_id: str, sequences: Sequence[int], /
) -> Stream[EncryptedRemoteBatch, CompactionNotFound]:
    """Input batches by input sequence: snapshot batches at or below the
    pinned base, originals above it."""

stage_part

stage_part(public_key, store_id, stage_id, segment, batches) -> Effect[Literal['Stored', 'AlreadyStored'], CompactionInvalidRequest | CompactionNotFound]

Store one segment of snapshot batches (non-empty), or answer AlreadyStored for a segment already staged. A segment index or size out of range closes the stage.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr
segmentint
batchesSequence[EncryptedBatch]

Returns Effect[Literal['Stored', 'AlreadyStored'], CompactionInvalidRequest | CompactionNotFound]

@abstractmethod
def stage_part(
    self,
    public_key: str,
    store_id: StoreId,
    stage_id: str,
    segment: int,
    batches: Sequence[EncryptedBatch],
    /,
) -> Effect[Literal["Stored", "AlreadyStored"], CompactionInvalidRequest | CompactionNotFound]:
    """Store one segment of snapshot batches (non-empty), or answer
    ``AlreadyStored`` for a segment already staged. A segment index or
    size out of range closes the stage."""

staged_headers

staged_headers(public_key, store_id, stage_id) -> Stream[StagedHeader, CompactionNotFound]

Staged batch headers in position order.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr

Returns Stream[StagedHeader, CompactionNotFound]

@abstractmethod
def staged_headers(
    self, public_key: str, store_id: StoreId, stage_id: str, /
) -> Stream[StagedHeader, CompactionNotFound]:
    """Staged batch headers in position order."""

commit

commit(public_key, store_id, stage_id, virtual_sequences) -> Effect[Literal['Committed', 'Superseded'], CompactionNotFound]

Activate the staged set, each batch at its virtual start sequence, if the pinned activation is still active; logs the outcome with this commit's own activation id.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr
virtual_sequencesSequence[int]

Returns Effect[Literal['Committed', 'Superseded'], CompactionNotFound]

@abstractmethod
def commit(
    self, public_key: str, store_id: StoreId, stage_id: str, virtual_sequences: Sequence[int], /
) -> Effect[Literal["Committed", "Superseded"], CompactionNotFound]:
    """Activate the staged set, each batch at its virtual start
    sequence, if the pinned activation is still active; logs the
    outcome with this commit's own activation id."""

record_no_op

record_no_op(public_key, store_id, stage_id) -> Effect[None, CompactionNotFound]

Record a no-op for the stage and log it.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr

Returns Effect[None, CompactionNotFound]

@abstractmethod
def record_no_op(
    self, public_key: str, store_id: StoreId, stage_id: str, /
) -> Effect[None, CompactionNotFound]:
    """Record a no-op for the stage and log it."""

abort

abort(public_key, store_id, stage_id) -> Effect[None]

Release an open stage and discard what it staged; a no-op for a stage that is no longer open.

ParameterTypeDescription
public_keystr
store_idStoreId
stage_idstr

Returns Effect[None]

@abstractmethod
def abort(self, public_key: str, store_id: StoreId, stage_id: str, /) -> Effect[None]:
    """Release an open stage and discard what it staged; a no-op for a
    stage that is no longer open."""

rollback

rollback(public_key, store_id, expected_activation_id) -> Effect[str, CompactionRollbackError]

Reactivate the previous generation; the new activation's id.

ParameterTypeDescription
public_keystr
store_idStoreId
expected_activation_idstr

Returns Effect[str, CompactionRollbackError]

@abstractmethod
def rollback(
    self, public_key: str, store_id: StoreId, expected_activation_id: str, /
) -> Effect[str, CompactionRollbackError]:
    """Reactivate the previous generation; the new activation's id."""

history

history(public_key, store_id) -> Effect[tuple[CompactionActivation, ...]]

Every activation of the store, oldest first.

ParameterTypeDescription
public_keystr
store_idStoreId

Returns Effect[tuple[CompactionActivation, ...]]

@abstractmethod
def history(
    self, public_key: str, store_id: StoreId, /
) -> Effect[tuple[CompactionActivation, ...]]:
    """Every activation of the store, oldest first."""