Skip to main content

EventStore

nautilus_event_store::backend

Trait EventStore 

Source 
pub trait EventStore: Send {
    // Required methods
    fn open_run(&mut self, manifest: RunManifest) -> Result<(), EventStoreError>;
    fn append_batch(
        &mut self,
        entries: &[AppendEntry],
    ) -> Result<u64, EventStoreError>;
    fn scan_range(
        &self,
        from: u64,
        to: u64,
        direction: ScanDirection,
    ) -> Result<Vec<EventStoreEntry>, EventStoreError>;
    fn scan_seq(
        &self,
        seq: u64,
    ) -> Result<Option<EventStoreEntry>, EventStoreError>;
    fn lookup(
        &self,
        kind: IndexKind,
        key: &str,
    ) -> Result<Option<u64>, EventStoreError>;
    fn iter_index_keys(
        &self,
        kind: IndexKind,
    ) -> Result<Vec<(String, u64)>, EventStoreError>;
    fn seal(&mut self, status: RunStatus) -> Result<(), EventStoreError>;
    fn manifest(&self) -> Result<RunManifest, EventStoreError>;
    fn high_watermark(&self) -> Result<u64, EventStoreError>;

    // Provided methods
    fn record_snapshot_anchor(
        &mut self,
        _anchor: SnapshotAnchor,
    ) -> Result<(), EventStoreError> { ... }
    fn latest_snapshot_anchor(
        &self,
    ) -> Result<Option<SnapshotAnchor>, EventStoreError> { ... }
}
Expand description

The single-node embedded event store.

One backend instance owns one open run. Writes funnel through append_batch; reads are seq-keyed scans or single-key lookups across the secondary indices.

Backends are responsible for:

  • Per-run organization on disk (one redb file per run, one in-memory log per run).
  • Durable commit semantics (Durability::Immediate for redb).
  • High-watermark advance after commit acknowledgement.
  • Mapping backend-specific errors onto EventStoreError.

This trait does not own batching or thread-management policy: the writer (crates/event_store/src/writer/) is the dedicated thread that batches entries and invokes append_batch against the backend.

Required Methods§

Source

fn open_run(&mut self, manifest: RunManifest) -> Result<(), EventStoreError>

Opens an existing run or creates a new one with the supplied manifest.

On reopening a run whose status is RunStatus::Running without a RunEnded entry, the backend returns EventStoreError::CrashedPredecessor so the kernel can seal it before opening a new run.

§Errors

Returns EventStoreError::Backend for unclassified backend failures, EventStoreError::Corrupted for header-region damage, and EventStoreError::Disk for disk pressure during creation.

Source

fn append_batch( &mut self, entries: &[AppendEntry], ) -> Result<u64, EventStoreError>

Appends a batch of (entry, index_keys) pairs in a single backend transaction.

The writer assigns seq, ts_publish, and the canonical entry_hash, plus any sidecar IndexKeys the encoder produced, before constructing each AppendEntry. The backend rejects batches whose first seq is not exactly high_watermark + 1, and whose subsequent seqs are not contiguous (each successor is prev + 1).

On successful commit, the backend advances its high-watermark and returns the new value.

§Errors

Returns EventStoreError::Closed when the run is sealed, EventStoreError::OutOfOrder when the first seq is not exactly high_watermark + 1 or a within-batch seq is not contiguous, EventStoreError::Disk when the backing storage refuses the write, and EventStoreError::Backend for unclassified backend failures.

Source

fn scan_range( &self, from: u64, to: u64, direction: ScanDirection, ) -> Result<Vec<EventStoreEntry>, EventStoreError>

Scans entries by seq over the inclusive range [from, to].

Backends may stream rows lazily; the trait’s vector return is a simple implementation default for the in-memory backend and the verifier hot path. The reader (crates/event_store/src/reader/) wraps this with iterator semantics.

§Errors

Returns EventStoreError::HashMismatch when a row’s recomputed hash diverges from the stored value, EventStoreError::Gap when the scan observes a missing seq, and EventStoreError::Backend for unclassified backend failures.

Source

fn scan_seq(&self, seq: u64) -> Result<Option<EventStoreEntry>, EventStoreError>

Reads a single entry by seq.

§Errors

See EventStore::scan_range.

Source

fn lookup( &self, kind: IndexKind, key: &str, ) -> Result<Option<u64>, EventStoreError>

Looks up the first seq recorded under the given index key.

Returns None when the key has not been observed.

§Errors

Returns EventStoreError::Backend for unclassified backend failures.

Source

fn iter_index_keys( &self, kind: IndexKind, ) -> Result<Vec<(String, u64)>, EventStoreError>

Enumerates every (key, seq) pair stored under the given secondary index.

Used by the verifier to cross-check the stored sidecar indices against the projection rebuilt from the entry table. The returned vector’s order is backend-defined; callers that need a stable comparison sort it themselves.

§Errors

Returns EventStoreError::Backend for unclassified backend failures.

Source

fn seal(&mut self, status: RunStatus) -> Result<(), EventStoreError>

Seals the open run with the given final status and persists the manifest update.

Subsequent calls to EventStore::append_batch return EventStoreError::Closed.

§Errors

Returns EventStoreError::Backend for unclassified backend failures and EventStoreError::Disk for disk pressure during the seal commit.

Source

fn manifest(&self) -> Result<RunManifest, EventStoreError>

Returns the current manifest snapshot.

§Errors

Returns EventStoreError::Backend when no run is open.

Source

fn high_watermark(&self) -> Result<u64, EventStoreError>

Returns the largest seq durably acknowledged for the open run.

Returns 0 when no entries have been committed yet (the writer assigns seq starting at 1).

§Errors

Returns EventStoreError::Backend when no run is open.

Provided Methods§

Source

fn record_snapshot_anchor( &mut self, _anchor: SnapshotAnchor, ) -> Result<(), EventStoreError>

Records the latest cache snapshot anchor for the open run.

The anchor’s high-watermark must be less than or equal to the durable high-watermark and must not move backward relative to the latest recorded anchor. Backends persist the anchor independently from the snapshot blob; the cache owns the blob and content-hash calculation.

§Errors

Returns EventStoreError::Backend when no run is open, when the backend does not support snapshot anchors, or when the anchor is invalid for the current high-watermark; returns EventStoreError::Closed when the run is sealed.

Source

fn latest_snapshot_anchor( &self, ) -> Result<Option<SnapshotAnchor>, EventStoreError>

Returns the latest recorded snapshot anchor for the open run.

Returns Ok(None) when no snapshot anchor has been recorded yet. The default implementation also returns Ok(None): a backend without anchor support truthfully has no anchor to report, and consumers (the verifier, retention planning) must be able to distinguish “no anchor” from a real read failure.

§Errors

Returns EventStoreError::Backend when no run is open and EventStoreError::Corrupted when a stored anchor fails to decode.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§