Skip to main content

datum_persistence/
snapshot.rs

1//! Byte-oriented snapshot storage contract.
2
3use crate::{PersistenceId, PersistenceResult, SequenceNr, SerializedPayload};
4
5/// Durable identity and timestamp of one saved snapshot.
6#[derive(Debug, Clone, PartialEq, Eq)]
7pub struct SnapshotMetadata {
8    /// Persistence id whose state was captured.
9    pub persistence_id: PersistenceId,
10    /// Event sequence number represented by the snapshot state.
11    pub sequence_nr: SequenceNr,
12    /// Snapshot timestamp as milliseconds since the Unix epoch, 1970-01-01 UTC.
13    pub timestamp_ms: i64,
14}
15
16/// Inclusive sequence-number and timestamp bounds for snapshot selection.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub struct SnapshotCriteria {
19    /// Smallest eligible sequence number, inclusive.
20    pub min_sequence_nr: SequenceNr,
21    /// Largest eligible sequence number, inclusive.
22    pub max_sequence_nr: SequenceNr,
23    /// Smallest eligible Unix-epoch timestamp in milliseconds, inclusive.
24    pub min_timestamp_ms: i64,
25    /// Largest eligible Unix-epoch timestamp in milliseconds, inclusive.
26    pub max_timestamp_ms: i64,
27}
28
29impl SnapshotCriteria {
30    /// Selects the latest snapshot without restricting sequence or timestamp.
31    #[must_use]
32    pub const fn latest() -> Self {
33        Self {
34            min_sequence_nr: SequenceNr::new(0),
35            max_sequence_nr: SequenceNr::new(u64::MAX),
36            min_timestamp_ms: i64::MIN,
37            max_timestamp_ms: i64::MAX,
38        }
39    }
40
41    /// Selects no snapshot.
42    #[must_use]
43    pub const fn none() -> Self {
44        Self {
45            min_sequence_nr: SequenceNr::new(1),
46            max_sequence_nr: SequenceNr::new(0),
47            min_timestamp_ms: i64::MIN,
48            max_timestamp_ms: i64::MAX,
49        }
50    }
51
52    /// Returns whether metadata falls within every inclusive bound.
53    #[must_use]
54    pub fn matches(&self, metadata: &SnapshotMetadata) -> bool {
55        self.min_sequence_nr <= metadata.sequence_nr
56            && metadata.sequence_nr <= self.max_sequence_nr
57            && self.min_timestamp_ms <= metadata.timestamp_ms
58            && metadata.timestamp_ms <= self.max_timestamp_ms
59    }
60}
61
62impl Default for SnapshotCriteria {
63    fn default() -> Self {
64        Self::latest()
65    }
66}
67
68/// Snapshot metadata paired with its serialized state frame.
69#[derive(Debug, Clone, PartialEq, Eq)]
70pub struct SelectedSnapshot {
71    /// Metadata identifying the selected snapshot.
72    pub metadata: SnapshotMetadata,
73    /// Durable state-adapter manifest, separate from serializer manifests.
74    pub adapter_manifest: String,
75    /// Serialized state captured by the snapshot.
76    pub state: SerializedPayload,
77}
78
79/// Byte-oriented snapshot storage provider.
80#[async_trait::async_trait]
81pub trait SnapshotStore: Send + Sync {
82    /// Loads the latest snapshot that satisfies `criteria`.
83    ///
84    /// `Ok(None)` means no snapshot matches. `Err` is a storage/load failure and
85    /// must remain distinguishable because recovery cannot safely fall back to
86    /// full replay after a failed snapshot load.
87    async fn load(
88        &self,
89        persistence_id: &PersistenceId,
90        criteria: &SnapshotCriteria,
91    ) -> PersistenceResult<Option<SelectedSnapshot>>;
92
93    /// Saves a snapshot. A save at an existing sequence number replaces the
94    /// previously observable snapshot at that sequence number.
95    async fn save(
96        &self,
97        metadata: SnapshotMetadata,
98        adapter_manifest: String,
99        state: SerializedPayload,
100    ) -> PersistenceResult<()>;
101
102    /// Deletes the snapshot with exactly matching metadata, if present.
103    async fn delete(&self, metadata: SnapshotMetadata) -> PersistenceResult<()>;
104
105    /// Deletes every snapshot for `persistence_id` matching the criteria.
106    async fn delete_matching(
107        &self,
108        persistence_id: &PersistenceId,
109        criteria: &SnapshotCriteria,
110    ) -> PersistenceResult<()>;
111}