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 an error if the backend fails, the header region is damaged, or disk pressure prevents 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 an error if the run is sealed, if the first seq is not exactly high_watermark + 1 or a within-batch seq is not contiguous, if the backing storage refuses the write, or if the backend fails.

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 an error if a row’s recomputed hash diverges from the stored value, if the scan observes a missing seq, or if the backend fails.

Source

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

Reads a single entry by seq.

§Errors

Returns an error if EventStore::scan_range fails.

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 an error if the backend fails.

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 an error if the backend fails.

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 an error if the backend fails or disk pressure prevents the seal commit.

Source

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

Returns the current manifest snapshot.

§Errors

Returns an error if 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 an error if 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 an error if no run is open, when the backend does not support snapshot anchors, or when the anchor is invalid for the current high-watermark, or if 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 an error if no run is open or 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§