datum-persistence 0.11.3

Event sourcing, durable state, and CQRS persistence for Datum
Documentation
//! Byte-oriented snapshot storage contract.

use crate::{PersistenceId, PersistenceResult, SequenceNr, SerializedPayload};

/// Durable identity and timestamp of one saved snapshot.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SnapshotMetadata {
    /// Persistence id whose state was captured.
    pub persistence_id: PersistenceId,
    /// Event sequence number represented by the snapshot state.
    pub sequence_nr: SequenceNr,
    /// Snapshot timestamp as milliseconds since the Unix epoch, 1970-01-01 UTC.
    pub timestamp_ms: i64,
}

/// Inclusive sequence-number and timestamp bounds for snapshot selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SnapshotCriteria {
    /// Smallest eligible sequence number, inclusive.
    pub min_sequence_nr: SequenceNr,
    /// Largest eligible sequence number, inclusive.
    pub max_sequence_nr: SequenceNr,
    /// Smallest eligible Unix-epoch timestamp in milliseconds, inclusive.
    pub min_timestamp_ms: i64,
    /// Largest eligible Unix-epoch timestamp in milliseconds, inclusive.
    pub max_timestamp_ms: i64,
}

impl SnapshotCriteria {
    /// Selects the latest snapshot without restricting sequence or timestamp.
    #[must_use]
    pub const fn latest() -> Self {
        Self {
            min_sequence_nr: SequenceNr::new(0),
            max_sequence_nr: SequenceNr::new(u64::MAX),
            min_timestamp_ms: i64::MIN,
            max_timestamp_ms: i64::MAX,
        }
    }

    /// Selects no snapshot.
    #[must_use]
    pub const fn none() -> Self {
        Self {
            min_sequence_nr: SequenceNr::new(1),
            max_sequence_nr: SequenceNr::new(0),
            min_timestamp_ms: i64::MIN,
            max_timestamp_ms: i64::MAX,
        }
    }

    /// Returns whether metadata falls within every inclusive bound.
    #[must_use]
    pub fn matches(&self, metadata: &SnapshotMetadata) -> bool {
        self.min_sequence_nr <= metadata.sequence_nr
            && metadata.sequence_nr <= self.max_sequence_nr
            && self.min_timestamp_ms <= metadata.timestamp_ms
            && metadata.timestamp_ms <= self.max_timestamp_ms
    }
}

impl Default for SnapshotCriteria {
    fn default() -> Self {
        Self::latest()
    }
}

/// Snapshot metadata paired with its serialized state frame.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SelectedSnapshot {
    /// Metadata identifying the selected snapshot.
    pub metadata: SnapshotMetadata,
    /// Durable state-adapter manifest, separate from serializer manifests.
    pub adapter_manifest: String,
    /// Serialized state captured by the snapshot.
    pub state: SerializedPayload,
}

/// Byte-oriented snapshot storage provider.
#[async_trait::async_trait]
pub trait SnapshotStore: Send + Sync {
    /// Loads the latest snapshot that satisfies `criteria`.
    ///
    /// `Ok(None)` means no snapshot matches. `Err` is a storage/load failure and
    /// must remain distinguishable because recovery cannot safely fall back to
    /// full replay after a failed snapshot load.
    async fn load(
        &self,
        persistence_id: &PersistenceId,
        criteria: &SnapshotCriteria,
    ) -> PersistenceResult<Option<SelectedSnapshot>>;

    /// Saves a snapshot. A save at an existing sequence number replaces the
    /// previously observable snapshot at that sequence number.
    async fn save(
        &self,
        metadata: SnapshotMetadata,
        adapter_manifest: String,
        state: SerializedPayload,
    ) -> PersistenceResult<()>;

    /// Deletes the snapshot with exactly matching metadata, if present.
    async fn delete(&self, metadata: SnapshotMetadata) -> PersistenceResult<()>;

    /// Deletes every snapshot for `persistence_id` matching the criteria.
    async fn delete_matching(
        &self,
        persistence_id: &PersistenceId,
        criteria: &SnapshotCriteria,
    ) -> PersistenceResult<()>;
}