Skip to main content

datum_persistence/
journal.rs

1//! Byte-oriented event journal storage contract.
2
3use std::pin::Pin;
4
5use futures_core::Stream;
6
7use crate::{
8    AppendOutcome, PersistenceError, PersistenceId, PersistenceResult, SequenceNr,
9    SerializedPayload, Tag,
10};
11
12/// One serialized event as stored by a journal backend.
13#[derive(Debug, Clone, PartialEq, Eq)]
14pub struct StoredEvent {
15    /// Stable identity of the persistent entity that owns the event.
16    pub persistence_id: PersistenceId,
17    /// Monotonic sequence number within the persistence id.
18    pub sequence_nr: SequenceNr,
19    /// Durable event-adapter manifest, separate from serializer manifests.
20    pub adapter_manifest: String,
21    /// Stable identifier of the writer instance that produced the event.
22    pub writer_uuid: String,
23    /// Event timestamp as milliseconds since the Unix epoch, 1970-01-01 UTC.
24    pub timestamp_ms: i64,
25    /// Optional serialized event metadata frame.
26    pub metadata: Option<SerializedPayload>,
27    /// Serialized event payload frame.
28    pub payload: SerializedPayload,
29    /// Query tags attached to the adapted stored event.
30    pub tags: Vec<Tag>,
31}
32
33/// A non-empty, gapless sequence of events committed all-or-nothing.
34///
35/// Construction validates that every event has the same persistence id and
36/// that sequence numbers are strictly ascending without gaps. An append batch
37/// may contain multiple atomic writes; the batch as a whole is not atomic.
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct AtomicWrite {
40    events: Vec<StoredEvent>,
41}
42
43impl AtomicWrite {
44    /// Validates and creates one atomic journal write.
45    pub fn new(events: Vec<StoredEvent>) -> PersistenceResult<Self> {
46        let Some(first) = events.first() else {
47            return Err(PersistenceError::InvalidAtomicWrite(
48                "at least one event is required".to_owned(),
49            ));
50        };
51
52        if let Some(event) = events
53            .iter()
54            .find(|event| event.persistence_id != first.persistence_id)
55        {
56            return Err(PersistenceError::InvalidAtomicWrite(format!(
57                "event for persistence id {} does not match {}",
58                event.persistence_id, first.persistence_id
59            )));
60        }
61
62        for pair in events.windows(2) {
63            let current = pair[0].sequence_nr.as_u64();
64            let expected = current.checked_add(1).ok_or_else(|| {
65                PersistenceError::InvalidAtomicWrite(format!(
66                    "sequence number {current} cannot have a successor"
67                ))
68            })?;
69            let actual = pair[1].sequence_nr.as_u64();
70            if actual != expected {
71                return Err(PersistenceError::InvalidAtomicWrite(format!(
72                    "expected sequence number {expected} after {current}, got {actual}"
73                )));
74            }
75        }
76
77        Ok(Self { events })
78    }
79
80    /// Returns the persistence id shared by every event in the write.
81    #[must_use]
82    pub fn persistence_id(&self) -> &PersistenceId {
83        &self.events[0].persistence_id
84    }
85
86    /// Returns the validated events in storage order.
87    #[must_use]
88    pub fn events(&self) -> &[StoredEvent] {
89        &self.events
90    }
91
92    /// Consumes the write and returns its validated events.
93    #[must_use]
94    pub fn into_events(self) -> Vec<StoredEvent> {
95        self.events
96    }
97}
98
99/// Inclusive replay selection for one persistence id.
100#[derive(Debug, Clone, PartialEq, Eq)]
101pub struct ReplayRange {
102    /// Persistence id whose events should be replayed.
103    pub persistence_id: PersistenceId,
104    /// First sequence number to emit, inclusive.
105    pub from: SequenceNr,
106    /// Last sequence number to emit, inclusive.
107    pub to: SequenceNr,
108    /// Maximum number of events to emit.
109    pub max: u64,
110}
111
112/// Owned asynchronous stream returned by journal replay.
113///
114/// Individual storage/read failures are emitted as stream items. The stream is
115/// `Send` and owns its replay state, so it does not borrow the journal.
116pub type EventStream = Pin<Box<dyn Stream<Item = PersistenceResult<StoredEvent>> + Send + 'static>>;
117
118/// Byte-oriented event journal storage provider.
119#[async_trait::async_trait]
120pub trait Journal: Send + Sync {
121    /// Appends one independently atomic write per input item.
122    ///
123    /// The result must contain exactly one outcome per input write, in input
124    /// order. [`AppendOutcome::Rejected`] is deterministic and guarantees that
125    /// none of that atomic write was stored. `Err` means storage failure or
126    /// uncertainty about whether a commit happened.
127    async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>>;
128
129    /// Appends one atomic write without requiring callers to allocate an input batch.
130    ///
131    /// Backends with a single-write fast path should override this method. The
132    /// default preserves the exact outcome-count contract of [`Self::append`].
133    async fn append_one(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
134        let outcomes = self.append(vec![write]).await?;
135        let mut outcomes = outcomes.into_iter();
136        let outcome = outcomes.next().ok_or_else(|| {
137            PersistenceError::Failure("journal returned no outcome for one atomic write".into())
138        })?;
139        if outcomes.next().is_some() {
140            return Err(PersistenceError::Failure(
141                "journal returned more than one outcome for one atomic write".into(),
142            ));
143        }
144        Ok(outcome)
145    }
146
147    /// Returns the monotonic high watermark for one persistence id.
148    ///
149    /// The value survives all logical deletes, including delete-to-MAX. The
150    /// backend may use `from_hint` for read optimization but must return the
151    /// actual watermark; an unknown id returns sequence number zero.
152    async fn highest_sequence_nr(
153        &self,
154        persistence_id: &PersistenceId,
155        from_hint: SequenceNr,
156    ) -> PersistenceResult<SequenceNr>;
157
158    /// Replays stored, non-deleted events matching an inclusive range.
159    ///
160    /// Reversed bounds and `max == 0` produce an empty stream.
161    async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream>;
162
163    /// Logically deletes events currently stored through `inclusive` while
164    /// preserving the high watermark.
165    ///
166    /// Deletion is point-in-time: an event appended after this call completes
167    /// remains visible even when its sequence number is at or below `inclusive`
168    /// (notably after delete-to-MAX with a preserved watermark). Marker-based
169    /// backends must therefore scope their marker to the events present at the
170    /// deletion linearization point. [`crate::assert_journal_conformance`] is
171    /// the normative executable contract for this behavior.
172    async fn delete_to(
173        &self,
174        persistence_id: &PersistenceId,
175        inclusive: SequenceNr,
176    ) -> PersistenceResult<()>;
177}