Trait StorageBackend 

pub trait StorageBackend: Send + Sync {
    // Required methods
    fn write_entry(&self, entry: &LogEntry) -> Result<(), DbError>;
    fn read_log(&self) -> Result<Vec<LogEntry>, DbError>;
    fn compact(&self, entries: Vec<LogEntry>) -> Result<(), DbError>;
    fn read_at(&self, offset: u64, length: u32) -> Result<Vec<u8>, DbError>;

    // Provided methods
    fn compact_with_hook(
        &self,
        entries: Vec<LogEntry>,
        _hook: Option<String>,
    ) -> Result<(), DbError> { ... }
    fn get_size(&self) -> Result<u64, DbError> { ... }
    fn stream_log_into(
        &self,
        f: &mut dyn FnMut(LogEntry, u32) -> ControlFlow<(), ()>,
    ) -> Result<u64, DbError> { ... }
}

The core storage abstraction. Implement this trait to add a new storage backend.

All three methods operate on LogEntry — the atomic unit of data in MoltenDB. The engine never writes raw bytes; it always goes through this interface.

Required Methods

fn write_entry(&self, entry: &LogEntry) -> Result<(), DbError>

Append a single log entry to the persistent store.

This is called on every insert, update, delete, and index creation. Implementations may buffer writes (async) or flush immediately (sync).

fn read_log(&self) -> Result<Vec<LogEntry>, DbError>

Read all log entries from persistent storage into a Vec.

Called on startup to rebuild the in-memory state, and by EncryptedStorage which must decrypt entries before they can be streamed into state. For large databases, prefer stream_log_into which avoids holding the full log in RAM.

fn compact(&self, entries: Vec<LogEntry>) -> Result<(), DbError>

Compact the log by writing only the current state (removing dead entries).

entries is the complete current state of the database — every live document as a single INSERT entry. The implementation should atomically replace the existing log with this minimal set.

fn read_at(&self, offset: u64, length: u32) -> Result<Vec<u8>, DbError>

Read exactly length bytes starting at offset from the log.

This is used to fetch “Cold” documents from the append-only log without loading the entire file into memory.

Provided Methods

fn compact_with_hook( &self, entries: Vec<LogEntry>, _hook: Option<String>, ) -> Result<(), DbError>

Compact the log and execute an optional post-backup shell hook.

The default implementation calls compact() and ignores the hook. Backends that support shell hooks should override this.

fn get_size(&self) -> Result<u64, DbError>

Return the current size of the persistent log file in bytes.

Used by the WASM worker to implement size-based auto-compaction — the JS side calls get_size after every INSERT batch and compacts if the file exceeds the configured threshold (default: 5 MB).

The default implementation returns 0 (no size information available). OpfsStorage overrides this with a real FileSystemSyncAccessHandle.getSize() call. Native disk backends don’t need this — they use OS-level file metadata instead.

fn stream_log_into( &self, f: &mut dyn FnMut(LogEntry, u32) -> ControlFlow<(), ()>, ) -> Result<u64, DbError>

Stream log entries into state one at a time, without loading the full log into RAM. Implementations may load a binary snapshot first and only replay the delta lines written after the snapshot.

The default implementation falls back to read_log() for backwards compatibility (used by WASM/EncryptedStorage which don’t have snapshots).

Returns the total number of entries processed.

Implementors

impl StorageBackend for AsyncDiskStorage

impl StorageBackend for EncryptedStorage

Implement the StorageBackend trait so EncryptedStorage can be used anywhere a StorageBackend is expected — the rest of the engine doesn’t know or care that encryption is happening.

impl StorageBackend for SyncDiskStorage