Skip to main content

datum_persistence/
durable.rs

1//! Byte-oriented durable-state storage contract.
2
3use crate::{PersistenceId, PersistenceResult, Revision, SerializedPayload, Tag};
4
5/// Latest serialized durable state together with its CAS revision.
6#[derive(Debug, Clone, PartialEq, Eq)]
7pub struct VersionedState {
8    /// Current state, or `None` when absent or deleted by a tombstone.
9    pub state: Option<SerializedPayload>,
10    /// Current revision. An id never written or deleted has revision zero.
11    pub revision: Revision,
12    /// Current query tag, or `None` when absent, untagged, or deleted.
13    pub tag: Option<Tag>,
14}
15
16impl Default for VersionedState {
17    fn default() -> Self {
18        Self {
19            state: None,
20            revision: Revision::new(0),
21            tag: None,
22        }
23    }
24}
25
26/// Byte-oriented durable-state storage provider.
27///
28/// The optional tag is part of the observable latest-value contract: upsert
29/// replaces it and delete clears it. [`crate::assert_durable_state_store_conformance`]
30/// is the normative executable contract for revisions, tombstones, and tags.
31#[async_trait::async_trait]
32pub trait DurableStateStore: Send + Sync {
33    /// Gets the latest value and revision. Unknown ids return absent state at
34    /// revision zero.
35    async fn get(&self, persistence_id: &PersistenceId) -> PersistenceResult<VersionedState>;
36
37    /// Stores `state` when `new_revision == stored_revision + 1`.
38    ///
39    /// A mismatch returns [`crate::PersistenceError::RevisionConflict`], never
40    /// a generic storage failure. The first successful write uses revision one.
41    /// A successful upsert replaces both the state and its optional tag.
42    async fn upsert(
43        &self,
44        persistence_id: &PersistenceId,
45        new_revision: Revision,
46        state: SerializedPayload,
47        tag: Option<Tag>,
48    ) -> PersistenceResult<()>;
49
50    /// Advances the revision under the same CAS rule, clears the tag, and leaves
51    /// a tombstone.
52    async fn delete(
53        &self,
54        persistence_id: &PersistenceId,
55        new_revision: Revision,
56    ) -> PersistenceResult<()>;
57}