GitHub

StorageService

API reference for StorageService.

Where an encrypted server keeps batches (Effect's Storage).

A batch owns one sequence per entry from its sequence. write stores a batch unless all its ids are stored (so retries are idempotent); entry_sequences gives where each id was first stored. A storage that supports remote compaction sets compaction; with an active snapshot, changes serves the snapshot's batches for a start at or below its base, then the originals above it.

Attributes

AttributeTypeDescription
first_sequenceint | None = None

The lowest assigned sequence (default 0). Overestimating skips entries.

compactionStorageCompaction | None = None
get_idEffect[RemoteId]

The storage's remote id, which the server sends clients in its hello. Never fails.

Functions

get_or_create_session_auth_binding

get_or_create_session_auth_binding(public_key, signing_public_key) -> Effect[bytes]

The signing key bound to public_key, binding the given one on first use. The server passes only verified keys, and rejects one that differs from the returned binding.

ParameterTypeDescription
public_keystr
signing_public_keybytes

Returns Effect[bytes]

@abstractmethod
def get_or_create_session_auth_binding(
    self, public_key: str, signing_public_key: bytes, /
) -> Effect[bytes]:
    """The signing key bound to ``public_key``, binding the given one
    on first use. The server passes only verified keys, and rejects one
    that differs from the returned binding."""

write

write(public_key, store_id, batches) -> Effect[list[EncryptedRemoteBatch]]

Store the batches not already stored, in order.

ParameterTypeDescription
public_keystr
store_idStoreId
batchesSequence[EncryptedBatch]

Returns Effect[list[EncryptedRemoteBatch]]

@abstractmethod
def write(
    self, public_key: str, store_id: StoreId, batches: Sequence[EncryptedBatch], /
) -> Effect[list[EncryptedRemoteBatch]]:
    """Store the batches not already stored, in order."""

entry_sequences

entry_sequences(public_key, store_id, entry_ids) -> Effect[list[WriteAck]]

Where each known entry was first stored.

ParameterTypeDescription
public_keystr
store_idStoreId
entry_idsSequence[EntryId]

Returns Effect[list[WriteAck]]

@abstractmethod
def entry_sequences(
    self, public_key: str, store_id: StoreId, entry_ids: Sequence[EntryId], /
) -> Effect[list[WriteAck]]:
    """Where each known entry was first stored."""

changes

changes(public_key, store_id, start_sequence) -> Stream[EncryptedRemoteBatch]

The stored batches whose last sequence is at or after start_sequence, then new ones.

ParameterTypeDescription
public_keystr
store_idStoreId
start_sequenceint

Returns Stream[EncryptedRemoteBatch]

@abstractmethod
def changes(
    self, public_key: str, store_id: StoreId, start_sequence: int, /
) -> Stream[EncryptedRemoteBatch]:
    """The stored batches whose last sequence is at or after
    ``start_sequence``, then new ones."""

latest_sequence

latest_sequence(public_key, store_id) -> Effect[int | None]

The sequence of the last stored entry, None when there is none.

ParameterTypeDescription
public_keystr
store_idStoreId

Returns Effect[int | None]

@abstractmethod
def latest_sequence(self, public_key: str, store_id: StoreId, /) -> Effect[int | None]:
    """The sequence of the last stored entry, ``None`` when there is none."""