Contracts (ABCs)

Abstract base classes defining the core storage interfaces.

StorageEngine

StorageEngine

Bases: ABC

Async key-value store contract.

Any class that provides durable, crash-safe storage of byte key-value pairs should inherit from this ABC and implement all four methods.

put(key, value) abstractmethod async

Persist a key-value pair.

Parameters:

Name	Type	Description	Default
key	Key	The lookup key (raw bytes).	required
value	Value	The value to associate with key (raw bytes).	required

Source code in app/common/abc.py

@abstractmethod
async def put(self, key: Key, value: Value) -> None:
    """Persist a key-value pair.

    Args:
        key: The lookup key (raw bytes).
        value: The value to associate with *key* (raw bytes).
    """

get(key) abstractmethod async

Retrieve the value for key.

Parameters:

Name	Type	Description	Default
key	Key	The lookup key.	required

Returns:

Type	Description
Value | None	The stored value, or None if the key does not exist or
Value | None	has been deleted.

Source code in app/common/abc.py

@abstractmethod
async def get(self, key: Key) -> Value | None:
    """Retrieve the value for *key*.

    Args:
        key: The lookup key.

    Returns:
        The stored value, or ``None`` if the key does not exist or
        has been deleted.
    """

delete(key) abstractmethod async

Delete key from the store.

Parameters:

Name	Type	Description	Default
key	Key	The key to remove.	required

Source code in app/common/abc.py

@abstractmethod
async def delete(self, key: Key) -> None:
    """Delete *key* from the store.

    Args:
        key: The key to remove.
    """

close() abstractmethod async

Flush pending data and release all resources.

After close() returns, subsequent calls to :meth:put, :meth:get, or :meth:delete should raise an error.

Source code in app/common/abc.py

@abstractmethod
async def close(self) -> None:
    """Flush pending data and release all resources.

    After ``close()`` returns, subsequent calls to :meth:`put`,
    :meth:`get`, or :meth:`delete` should raise an error.
    """

Serializable

Serializable

Bases: ABC

Byte-level serialization contract.

Any class that can round-trip its state through bytes should inherit from this ABC. The from_bytes class method must reconstruct an equivalent instance from output of to_bytes.

to_bytes() abstractmethod

Serialize this instance to a compact byte string.

Returns:

Type	Description
bytes	A bytes object that can be passed to :meth:from_bytes
bytes	to reconstruct an equivalent instance.

Source code in app/common/abc.py

@abstractmethod
def to_bytes(self) -> bytes:
    """Serialize this instance to a compact byte string.

    Returns:
        A ``bytes`` object that can be passed to :meth:`from_bytes`
        to reconstruct an equivalent instance.
    """

from_bytes(data) abstractmethod classmethod

Reconstruct an instance from serialized data.

Parameters:

Name	Type	Description	Default
data	bytes	Bytes previously produced by :meth:to_bytes.	required

Returns:

Type	Description
Self	A new instance equivalent to the one that produced data.

Source code in app/common/abc.py

@classmethod
@abstractmethod
def from_bytes(cls, data: bytes) -> Self:
    """Reconstruct an instance from serialized *data*.

    Args:
        data: Bytes previously produced by :meth:`to_bytes`.

    Returns:
        A new instance equivalent to the one that produced *data*.
    """

MemTable

MemTable

Bases: ABC

Mutable in-memory sorted table contract.

Defines the minimal interface that a writable memtable must expose: insert, point lookup, sorted iteration, and freeze-to-snapshot.

put(key, seq, timestamp_ms, value) abstractmethod

Insert or update key in the table.

Parameters:

Name	Type	Description	Default
key	Key	The lookup key (raw bytes).	required
seq	SeqNum	Monotonically increasing sequence number.	required
timestamp_ms	int	Wall-clock timestamp in milliseconds.	required
value	Value	The value to store (or TOMBSTONE for deletions).	required

Source code in app/common/abc.py

@abstractmethod
def put(
    self, key: Key, seq: SeqNum, timestamp_ms: int, value: Value,
) -> None:
    """Insert or update *key* in the table.

    Args:
        key: The lookup key (raw bytes).
        seq: Monotonically increasing sequence number.
        timestamp_ms: Wall-clock timestamp in milliseconds.
        value: The value to store (or ``TOMBSTONE`` for deletions).
    """

get(key) abstractmethod

Look up key and return its latest value.

Parameters:

Name	Type	Description	Default
key	Key	The lookup key.	required

Returns:

Type	Description
tuple[SeqNum, Value] | None	A (seq, value) tuple, or None if the key is not
tuple[SeqNum, Value] | None	present in this table.

Source code in app/common/abc.py

@abstractmethod
def get(self, key: Key) -> tuple[SeqNum, Value] | None:
    """Look up *key* and return its latest value.

    Args:
        key: The lookup key.

    Returns:
        A ``(seq, value)`` tuple, or ``None`` if the key is not
        present in this table.
    """

items() abstractmethod

Yield all entries in ascending key order.

Yields:

Type	Description
tuple[Key, SeqNum, int, Value]	Tuples of (key, seq, timestamp_ms, value).

Source code in app/common/abc.py

@abstractmethod
def items(self) -> Iterator[tuple[Key, SeqNum, int, Value]]:
    """Yield all entries in ascending key order.

    Yields:
        Tuples of ``(key, seq, timestamp_ms, value)``.
    """

freeze() abstractmethod

Return a sorted snapshot of all entries and mark the table as frozen.

Returns:

Type	Description
list[tuple[Key, SeqNum, int, Value]]	A list of (key, seq, timestamp_ms, value) tuples sorted
list[tuple[Key, SeqNum, int, Value]]	by key ascending.

Raises:

Type	Description
SnapshotEmptyError	If the table contains no entries.

Source code in app/common/abc.py

@abstractmethod
def freeze(self) -> list[tuple[Key, SeqNum, int, Value]]:
    """Return a sorted snapshot of all entries and mark the table as frozen.

    Returns:
        A list of ``(key, seq, timestamp_ms, value)`` tuples sorted
        by key ascending.

    Raises:
        SnapshotEmptyError: If the table contains no entries.
    """