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}