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}