pub struct StorageEngine { /* private fields */ }Expand description
Single-writer durable KV storage composed from the log and rebuildable redb index.
Implementations§
Source§impl StorageEngine
impl StorageEngine
Sourcepub fn open(path: impl AsRef<Path>) -> Result<OpenedStorage, StorageError>
pub fn open(path: impl AsRef<Path>) -> Result<OpenedStorage, StorageError>
Opens a data directory, verifies its log, and catches the index up before use.
§Errors
Returns an error for directory contention, log corruption, invalid committed mutations, a divergent index checkpoint, or filesystem failures.
Sourcepub fn open_with_limits(
path: impl AsRef<Path>,
limits: StorageLimits,
) -> Result<OpenedStorage, StorageError>
pub fn open_with_limits( path: impl AsRef<Path>, limits: StorageLimits, ) -> Result<OpenedStorage, StorageError>
Opens and fully recovers a data directory under finite shared limits.
§Errors
Returns an error for invalid limits, directory contention, corruption, exhausted recovery work/bytes, timeout, divergence, or I/O failure.
Sourcepub fn backup(
&self,
destination: impl AsRef<Path>,
) -> Result<BackupInfo, BackupError>
pub fn backup( &self, destination: impl AsRef<Path>, ) -> Result<BackupInfo, BackupError>
Creates an atomic, independently verifiable backup at the current checkpoint.
§Errors
Returns an error when the snapshot cannot be created, the destination exists or is inside the live data directory, or synchronized promotion of the complete backup fails.
Sourcepub fn write(
&mut self,
transaction_id: Uuid,
mutations: &[Mutation],
) -> Result<AppendOutcome, StorageError>
pub fn write( &mut self, transaction_id: Uuid, mutations: &[Mutation], ) -> Result<AppendOutcome, StorageError>
Durably commits an atomic batch and then materializes it.
The log is synchronized before redb is updated. If redb fails, the error includes the durable commit receipt and this handle blocks reads and writes until reopen replays the log.
§Errors
Returns an error for invalid mutations, idempotency conflicts, log I/O, or materialized-index failures.
Sourcepub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, StorageError>
pub fn get(&self, key: &[u8]) -> Result<Option<Vec<u8>>, StorageError>
Reads a binary value from the caught-up materialized index.
§Errors
Returns an error for an empty or oversized key, an index read failure, or a handle made stale by a prior post-commit index failure.
Sourcepub fn vector_space(
&self,
name: &VectorSpaceName,
) -> Result<Option<VectorSpaceDefinition>, StorageError>
pub fn vector_space( &self, name: &VectorSpaceName, ) -> Result<Option<VectorSpaceDefinition>, StorageError>
Returns an immutable vector-space definition when present.
§Errors
Returns an error for a stale handle or malformed materialized state.
Sourcepub fn lexical_index(
&self,
name: &VectorSpaceName,
) -> Result<Option<LexicalIndexDefinition>, StorageError>
pub fn lexical_index( &self, name: &VectorSpaceName, ) -> Result<Option<LexicalIndexDefinition>, StorageError>
Returns an immutable lexical-index definition when present.
§Errors
Returns an error for a stale handle or malformed materialized state.
Sourcepub fn lexical_corpus(
&self,
definition: &LexicalIndexDefinition,
query_tokens: &[String],
max_candidates: u64,
timeout: Duration,
) -> Result<LexicalMaterializedCorpus, StorageError>
pub fn lexical_corpus( &self, definition: &LexicalIndexDefinition, query_tokens: &[String], max_candidates: u64, timeout: Duration, ) -> Result<LexicalMaterializedCorpus, StorageError>
Reads bounded query-relevant statistics from the rebuildable lexical projection.
§Errors
Returns an error for a stale handle, malformed projection, exhausted candidate budget, or elapsed deadline.
Sourcepub fn vector_entries(
&self,
name: &VectorSpaceName,
max_candidates: u64,
max_bytes: u64,
) -> Result<Vec<VectorEntry>, StorageError>
pub fn vector_entries( &self, name: &VectorSpaceName, max_candidates: u64, max_bytes: u64, ) -> Result<Vec<VectorEntry>, StorageError>
Reads one vector space in strict binary-key order under explicit candidate and decoded-byte budgets.
§Errors
Returns an error for a stale handle, malformed state, or an exhausted count/byte budget. No partial list is returned.
Sourcepub fn vector_entries_with_timeout(
&self,
name: &VectorSpaceName,
max_candidates: u64,
max_bytes: u64,
timeout: Duration,
) -> Result<Vec<VectorEntry>, VectorEntriesError>
pub fn vector_entries_with_timeout( &self, name: &VectorSpaceName, max_candidates: u64, max_bytes: u64, timeout: Duration, ) -> Result<Vec<VectorEntry>, VectorEntriesError>
Reads one vector space under count, decoded-byte, and wall-clock bounds.
§Errors
Returns an error for a stale handle, malformed state, exhausted count/byte budget, or elapsed exact-retrieval deadline. No partial list is returned.
Sourcepub fn scan_page(
&self,
after: Option<&[u8]>,
limit: usize,
) -> Result<KvPage, StorageError>
pub fn scan_page( &self, after: Option<&[u8]>, limit: usize, ) -> Result<KvPage, StorageError>
Scans one bounded page in strict binary-key order.
after is exclusive. A returned next_after is present only when at
least one additional entry exists.
§Errors
Returns an error for a stale handle, invalid cursor key, invalid page size, or materialized-index failure.
Sourcepub fn scan_page_with_byte_limit(
&self,
after: Option<&[u8]>,
limit: usize,
max_bytes: u64,
) -> Result<KvPage, ScanPageError>
pub fn scan_page_with_byte_limit( &self, after: Option<&[u8]>, limit: usize, max_bytes: u64, ) -> Result<KvPage, ScanPageError>
Scans one ordered page under an aggregate key/value byte budget.
The byte limit is checked inside the materialized-index iterator before a key or value is cloned into the returned page.
§Errors
Returns an error for a stale handle, invalid cursor or page size, exhausted byte budget, or materialized-index failure.
Sourcepub fn index_path(&self) -> PathBuf
pub fn index_path(&self) -> PathBuf
Returns the internal materialized-index path for diagnostics.
Sourcepub fn snapshot(&self) -> Result<SnapshotInfo, StorageError>
pub fn snapshot(&self) -> Result<SnapshotInfo, StorageError>
Creates or reuses a verified logical snapshot at the current index checkpoint.
§Errors
Returns an error when the live index is stale, cannot be streamed, or the snapshot cannot be synchronized, verified, and atomically promoted.
Sourcepub fn snapshot_with_limits(
&self,
limits: &MaintenanceLimits,
) -> Result<SnapshotInfo, StorageError>
pub fn snapshot_with_limits( &self, limits: &MaintenanceLimits, ) -> Result<SnapshotInfo, StorageError>
Creates or reuses a verified snapshot under explicit finite limits.
§Errors
Returns an error for invalid limits, stale state, exhausted records or bytes, timeout, verification failure, or I/O failure.
Sourcepub fn compact(&mut self) -> Result<CompactionOutcome, StorageError>
pub fn compact(&mut self) -> Result<CompactionOutcome, StorageError>
Retires the active log prefix behind a verified logical snapshot.
The new empty segment is synchronized before an immutable manifest generation selects it. Physical deletion of the retired segment happens only after that commit and is reported independently.
§Errors
Returns an error while preparing the snapshot, segment, or manifest. A poisoned or stale handle must be reopened before compaction.
Sourcepub fn compact_with_limits(
&mut self,
limits: &MaintenanceLimits,
) -> Result<CompactionOutcome, StorageError>
pub fn compact_with_limits( &mut self, limits: &MaintenanceLimits, ) -> Result<CompactionOutcome, StorageError>
Compacts the active generation under one shared finite deadline.
§Errors
Returns an error before the manifest commit for invalid limits, stale state, exhausted snapshot policy, timeout, corruption, or I/O failure.