Skip to main content

datum_persistence/backend/
memory.rs

1//! Fully conformant in-memory reference storage backends.
2
3use std::{
4    collections::{BTreeMap, HashMap, VecDeque},
5    sync::{Arc, Mutex, MutexGuard},
6    time::{SystemTime, UNIX_EPOCH},
7};
8
9use futures_util::stream;
10use tokio::sync::watch;
11
12use crate::{
13    AppendOutcome, AtomicWrite, DurableStateStore, EventStream, Journal, PersistenceError,
14    PersistenceId, PersistenceResult, ReplayRange, Revision, SelectedSnapshot, SequenceNr,
15    SerializedPayload, SnapshotCriteria, SnapshotMetadata, SnapshotStore, StoredEvent, Tag,
16    VersionedState,
17    query::{
18        DeletedDurableState, DurableStateChange, DurableStateChangesQuery, EventEnvelope,
19        EventsByPersistenceIdQuery, EventsByTagQuery, Offset, PersistenceIdsQuery, QueryMode,
20        QueryStream, UpdatedDurableState,
21    },
22};
23
24#[derive(Debug, Default)]
25struct JournalEntity {
26    highest_sequence_nr: SequenceNr,
27    events: BTreeMap<SequenceNr, Arc<StoredEvent>>,
28}
29
30#[derive(Debug)]
31struct JournalEvent {
32    offset: u64,
33    event: Arc<StoredEvent>,
34}
35
36#[derive(Debug, Default)]
37struct MemoryJournalState {
38    entities: HashMap<PersistenceId, JournalEntity>,
39    event_log: Vec<JournalEvent>,
40    persistence_ids: Vec<PersistenceId>,
41    last_offset: u64,
42}
43
44/// In-memory event journal reference implementation.
45///
46/// All mutations are serialized under one short-lived in-memory lock. This is
47/// intentionally simple: the backend is the correctness oracle for the public
48/// conformance suite, not a production durability layer. Query offsets are a
49/// per-instance append counter and resume strictly after `Offset::Sequence(n)`.
50#[derive(Debug, Clone)]
51pub struct MemoryJournal {
52    state: Arc<Mutex<MemoryJournalState>>,
53    changes: watch::Sender<u64>,
54}
55
56impl Default for MemoryJournal {
57    fn default() -> Self {
58        let (changes, _receiver) = watch::channel(0);
59        Self {
60            state: Arc::new(Mutex::new(MemoryJournalState::default())),
61            changes,
62        }
63    }
64}
65
66impl MemoryJournal {
67    /// Creates an empty in-memory journal.
68    #[must_use]
69    pub fn new() -> Self {
70        Self::default()
71    }
72
73    fn notify_queries(&self) {
74        self.changes
75            .send_modify(|generation| *generation = generation.wrapping_add(1));
76    }
77}
78
79#[async_trait::async_trait]
80impl Journal for MemoryJournal {
81    async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>> {
82        let mut state = lock(&self.state, "journal")?;
83        let mut outcomes = Vec::with_capacity(writes.len());
84        let mut changed = false;
85
86        for write in writes {
87            let outcome = append_write(&mut state, write);
88            changed |= outcome == AppendOutcome::Accepted;
89            outcomes.push(outcome);
90        }
91        drop(state);
92
93        if changed {
94            self.notify_queries();
95        }
96        Ok(outcomes)
97    }
98
99    async fn append_one(&self, write: AtomicWrite) -> PersistenceResult<AppendOutcome> {
100        let mut state = lock(&self.state, "journal")?;
101        let outcome = append_write(&mut state, write);
102        drop(state);
103
104        if outcome == AppendOutcome::Accepted {
105            self.notify_queries();
106        }
107        Ok(outcome)
108    }
109
110    async fn highest_sequence_nr(
111        &self,
112        persistence_id: &PersistenceId,
113        _from_hint: SequenceNr,
114    ) -> PersistenceResult<SequenceNr> {
115        let state = lock(&self.state, "journal")?;
116        Ok(state
117            .entities
118            .get(persistence_id)
119            .map_or(SequenceNr::new(0), |entity| entity.highest_sequence_nr))
120    }
121
122    async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream> {
123        if range.from > range.to || range.max == 0 {
124            return Ok(Box::pin(stream::empty()));
125        }
126
127        let state = lock(&self.state, "journal")?;
128        let limit = usize::try_from(range.max).unwrap_or(usize::MAX);
129        let events = state
130            .entities
131            .get(&range.persistence_id)
132            .map(|entity| {
133                entity
134                    .events
135                    .range(range.from..=range.to)
136                    .take(limit)
137                    .map(|(_, event)| Arc::clone(event))
138                    .collect::<Vec<_>>()
139            })
140            .unwrap_or_default();
141        drop(state);
142        Ok(Box::pin(stream::iter(
143            events.into_iter().map(|event| Ok((*event).clone())),
144        )))
145    }
146
147    async fn delete_to(
148        &self,
149        persistence_id: &PersistenceId,
150        inclusive: SequenceNr,
151    ) -> PersistenceResult<()> {
152        let mut state = lock(&self.state, "journal")?;
153        if let Some(entity) = state.entities.get_mut(persistence_id) {
154            entity
155                .events
156                .retain(|sequence_nr, _| *sequence_nr > inclusive);
157        }
158        Ok(())
159    }
160}
161
162#[async_trait::async_trait]
163impl EventsByPersistenceIdQuery for MemoryJournal {
164    async fn events_by_persistence_id(
165        &self,
166        persistence_id: &PersistenceId,
167        from_sequence_nr: SequenceNr,
168        to_sequence_nr: SequenceNr,
169        mode: QueryMode,
170    ) -> PersistenceResult<QueryStream<EventEnvelope>> {
171        if from_sequence_nr > to_sequence_nr {
172            return Ok(Box::pin(stream::empty()));
173        }
174
175        let state = lock(&self.state, "journal")?;
176        let boundary = state.last_offset;
177        let snapshot = state
178            .event_log
179            .iter()
180            .filter(|entry| {
181                entry.event.persistence_id == *persistence_id
182                    && entry.event.sequence_nr >= from_sequence_nr
183                    && entry.event.sequence_nr <= to_sequence_nr
184                    && is_current_event(&state, entry)
185            })
186            .map(event_envelope)
187            .collect::<VecDeque<_>>();
188        drop(state);
189
190        if mode == QueryMode::Current {
191            return Ok(Box::pin(stream::iter(snapshot.into_iter().map(Ok))));
192        }
193
194        let cursor = PersistenceIdEventCursor {
195            state: Arc::clone(&self.state),
196            changes: self.changes.subscribe(),
197            persistence_id: persistence_id.clone(),
198            from_sequence_nr,
199            to_sequence_nr,
200            offset: boundary,
201            snapshot,
202        };
203        Ok(Box::pin(stream::unfold(cursor, next_persistence_id_event)))
204    }
205}
206
207#[async_trait::async_trait]
208impl EventsByTagQuery for MemoryJournal {
209    async fn events_by_tag(
210        &self,
211        tag: &Tag,
212        offset: Offset,
213        mode: QueryMode,
214    ) -> PersistenceResult<QueryStream<EventEnvelope>> {
215        let resume_after = sequence_offset(offset)?;
216        let state = lock(&self.state, "journal")?;
217        let boundary = state.last_offset;
218        let snapshot = state
219            .event_log
220            .iter()
221            .filter(|entry| {
222                entry.offset > resume_after
223                    && entry.event.tags.contains(tag)
224                    && is_current_event(&state, entry)
225            })
226            .map(event_envelope)
227            .collect::<VecDeque<_>>();
228        drop(state);
229
230        if mode == QueryMode::Current {
231            return Ok(Box::pin(stream::iter(snapshot.into_iter().map(Ok))));
232        }
233
234        let cursor = TagEventCursor {
235            state: Arc::clone(&self.state),
236            changes: self.changes.subscribe(),
237            tag: tag.clone(),
238            offset: boundary,
239            snapshot,
240        };
241        Ok(Box::pin(stream::unfold(cursor, next_tag_event)))
242    }
243}
244
245#[async_trait::async_trait]
246impl PersistenceIdsQuery for MemoryJournal {
247    async fn persistence_ids(
248        &self,
249        mode: QueryMode,
250    ) -> PersistenceResult<QueryStream<PersistenceId>> {
251        let state = lock(&self.state, "journal")?;
252        let snapshot = state
253            .persistence_ids
254            .iter()
255            .cloned()
256            .collect::<VecDeque<_>>();
257        let cursor_index = state.persistence_ids.len();
258        drop(state);
259
260        if mode == QueryMode::Current {
261            return Ok(Box::pin(stream::iter(snapshot.into_iter().map(Ok))));
262        }
263
264        let cursor = PersistenceIdsCursor {
265            state: Arc::clone(&self.state),
266            changes: self.changes.subscribe(),
267            index: cursor_index,
268            snapshot,
269        };
270        Ok(Box::pin(stream::unfold(cursor, next_persistence_id)))
271    }
272}
273
274struct PersistenceIdEventCursor {
275    state: Arc<Mutex<MemoryJournalState>>,
276    changes: watch::Receiver<u64>,
277    persistence_id: PersistenceId,
278    from_sequence_nr: SequenceNr,
279    to_sequence_nr: SequenceNr,
280    offset: u64,
281    snapshot: VecDeque<EventEnvelope>,
282}
283
284async fn next_persistence_id_event(
285    mut cursor: PersistenceIdEventCursor,
286) -> Option<(PersistenceResult<EventEnvelope>, PersistenceIdEventCursor)> {
287    if let Some(envelope) = cursor.snapshot.pop_front() {
288        return Some((Ok(envelope), cursor));
289    }
290
291    loop {
292        let (envelope, reached_end) = match scan_persistence_id_event(&mut cursor) {
293            Ok(result) => result,
294            Err(error) => return Some((Err(error), cursor)),
295        };
296
297        if let Some(envelope) = envelope {
298            return Some((Ok(envelope), cursor));
299        }
300        if reached_end {
301            return None;
302        }
303        if cursor.changes.changed().await.is_err() {
304            return None;
305        }
306    }
307}
308
309struct TagEventCursor {
310    state: Arc<Mutex<MemoryJournalState>>,
311    changes: watch::Receiver<u64>,
312    tag: Tag,
313    offset: u64,
314    snapshot: VecDeque<EventEnvelope>,
315}
316
317async fn next_tag_event(
318    mut cursor: TagEventCursor,
319) -> Option<(PersistenceResult<EventEnvelope>, TagEventCursor)> {
320    if let Some(envelope) = cursor.snapshot.pop_front() {
321        return Some((Ok(envelope), cursor));
322    }
323
324    loop {
325        let envelope = match scan_tag_event(&mut cursor) {
326            Ok(envelope) => envelope,
327            Err(error) => return Some((Err(error), cursor)),
328        };
329
330        if let Some(envelope) = envelope {
331            return Some((Ok(envelope), cursor));
332        }
333        if cursor.changes.changed().await.is_err() {
334            return None;
335        }
336    }
337}
338
339struct PersistenceIdsCursor {
340    state: Arc<Mutex<MemoryJournalState>>,
341    changes: watch::Receiver<u64>,
342    index: usize,
343    snapshot: VecDeque<PersistenceId>,
344}
345
346async fn next_persistence_id(
347    mut cursor: PersistenceIdsCursor,
348) -> Option<(PersistenceResult<PersistenceId>, PersistenceIdsCursor)> {
349    if let Some(persistence_id) = cursor.snapshot.pop_front() {
350        return Some((Ok(persistence_id), cursor));
351    }
352
353    loop {
354        let persistence_id = match scan_persistence_id(&mut cursor) {
355            Ok(persistence_id) => persistence_id,
356            Err(error) => return Some((Err(error), cursor)),
357        };
358
359        if let Some(persistence_id) = persistence_id {
360            return Some((Ok(persistence_id), cursor));
361        }
362        if cursor.changes.changed().await.is_err() {
363            return None;
364        }
365    }
366}
367
368/// In-memory snapshot-store reference implementation.
369#[derive(Debug, Default)]
370pub struct MemorySnapshotStore {
371    snapshots: Mutex<HashMap<PersistenceId, BTreeMap<SequenceNr, SelectedSnapshot>>>,
372}
373
374impl MemorySnapshotStore {
375    /// Creates an empty in-memory snapshot store.
376    #[must_use]
377    pub fn new() -> Self {
378        Self::default()
379    }
380}
381
382#[async_trait::async_trait]
383impl SnapshotStore for MemorySnapshotStore {
384    async fn load(
385        &self,
386        persistence_id: &PersistenceId,
387        criteria: &SnapshotCriteria,
388    ) -> PersistenceResult<Option<SelectedSnapshot>> {
389        let snapshots = lock(&self.snapshots, "snapshot store")?;
390        Ok(snapshots.get(persistence_id).and_then(|by_sequence_nr| {
391            by_sequence_nr
392                .values()
393                .filter(|snapshot| criteria.matches(&snapshot.metadata))
394                .max_by_key(|snapshot| {
395                    (
396                        snapshot.metadata.sequence_nr,
397                        snapshot.metadata.timestamp_ms,
398                    )
399                })
400                .cloned()
401        }))
402    }
403
404    async fn save(
405        &self,
406        metadata: SnapshotMetadata,
407        adapter_manifest: String,
408        state: SerializedPayload,
409    ) -> PersistenceResult<()> {
410        let mut snapshots = lock(&self.snapshots, "snapshot store")?;
411        let persistence_id = metadata.persistence_id.clone();
412        snapshots.entry(persistence_id).or_default().insert(
413            metadata.sequence_nr,
414            SelectedSnapshot {
415                metadata,
416                adapter_manifest,
417                state,
418            },
419        );
420        Ok(())
421    }
422
423    async fn delete(&self, metadata: SnapshotMetadata) -> PersistenceResult<()> {
424        let mut snapshots = lock(&self.snapshots, "snapshot store")?;
425        if let Some(by_sequence_nr) = snapshots.get_mut(&metadata.persistence_id)
426            && by_sequence_nr
427                .get(&metadata.sequence_nr)
428                .is_some_and(|snapshot| snapshot.metadata == metadata)
429        {
430            by_sequence_nr.remove(&metadata.sequence_nr);
431        }
432        Ok(())
433    }
434
435    async fn delete_matching(
436        &self,
437        persistence_id: &PersistenceId,
438        criteria: &SnapshotCriteria,
439    ) -> PersistenceResult<()> {
440        let mut snapshots = lock(&self.snapshots, "snapshot store")?;
441        if let Some(by_sequence_nr) = snapshots.get_mut(persistence_id) {
442            by_sequence_nr.retain(|_, snapshot| !criteria.matches(&snapshot.metadata));
443        }
444        Ok(())
445    }
446}
447
448#[derive(Debug, Clone)]
449struct DurableEntry {
450    versioned_state: VersionedState,
451    change_offset: u64,
452    change_timestamp_ms: i64,
453    change_tag: Option<Tag>,
454}
455
456#[derive(Debug, Default)]
457struct MemoryDurableState {
458    entries: HashMap<PersistenceId, DurableEntry>,
459    last_offset: u64,
460}
461
462/// In-memory durable-state reference implementation.
463///
464/// The query view retains only the latest revision for each id. Rapid writes
465/// therefore coalesce naturally while the latest revision remains observable.
466#[derive(Debug, Clone)]
467pub struct MemoryDurableStateStore {
468    state: Arc<Mutex<MemoryDurableState>>,
469    changes: watch::Sender<u64>,
470}
471
472impl Default for MemoryDurableStateStore {
473    fn default() -> Self {
474        let (changes, _receiver) = watch::channel(0);
475        Self {
476            state: Arc::new(Mutex::new(MemoryDurableState::default())),
477            changes,
478        }
479    }
480}
481
482impl MemoryDurableStateStore {
483    /// Creates an empty in-memory durable-state store.
484    #[must_use]
485    pub fn new() -> Self {
486        Self::default()
487    }
488
489    fn notify_queries(&self) {
490        self.changes
491            .send_modify(|generation| *generation = generation.wrapping_add(1));
492    }
493}
494
495#[async_trait::async_trait]
496impl DurableStateStore for MemoryDurableStateStore {
497    async fn get(&self, persistence_id: &PersistenceId) -> PersistenceResult<VersionedState> {
498        let state = lock(&self.state, "durable-state store")?;
499        Ok(state
500            .entries
501            .get(persistence_id)
502            .map_or_else(VersionedState::default, |entry| {
503                entry.versioned_state.clone()
504            }))
505    }
506
507    async fn upsert(
508        &self,
509        persistence_id: &PersistenceId,
510        new_revision: Revision,
511        state_payload: SerializedPayload,
512        tag: Option<Tag>,
513    ) -> PersistenceResult<()> {
514        let mut state = lock(&self.state, "durable-state store")?;
515        validate_revision(&state.entries, persistence_id, new_revision)?;
516        let change_offset = next_offset(state.last_offset, "durable-state query")?;
517        state.last_offset = change_offset;
518        state.entries.insert(
519            persistence_id.clone(),
520            DurableEntry {
521                versioned_state: VersionedState {
522                    state: Some(state_payload),
523                    revision: new_revision,
524                    tag: tag.clone(),
525                },
526                change_offset,
527                change_timestamp_ms: timestamp_ms(),
528                change_tag: tag,
529            },
530        );
531        drop(state);
532        self.notify_queries();
533        Ok(())
534    }
535
536    async fn delete(
537        &self,
538        persistence_id: &PersistenceId,
539        new_revision: Revision,
540    ) -> PersistenceResult<()> {
541        let mut state = lock(&self.state, "durable-state store")?;
542        validate_revision(&state.entries, persistence_id, new_revision)?;
543        let change_offset = next_offset(state.last_offset, "durable-state query")?;
544        let change_tag = state
545            .entries
546            .get(persistence_id)
547            .and_then(|entry| entry.change_tag.clone());
548        state.last_offset = change_offset;
549        state.entries.insert(
550            persistence_id.clone(),
551            DurableEntry {
552                versioned_state: VersionedState {
553                    state: None,
554                    revision: new_revision,
555                    tag: None,
556                },
557                change_offset,
558                change_timestamp_ms: timestamp_ms(),
559                change_tag,
560            },
561        );
562        drop(state);
563        self.notify_queries();
564        Ok(())
565    }
566}
567
568#[async_trait::async_trait]
569impl DurableStateChangesQuery for MemoryDurableStateStore {
570    async fn changes(
571        &self,
572        tag: &Tag,
573        offset: Offset,
574        mode: QueryMode,
575    ) -> PersistenceResult<QueryStream<DurableStateChange>> {
576        let resume_after = sequence_offset(offset)?;
577        let state = lock(&self.state, "durable-state store")?;
578        let boundary = state.last_offset;
579        let mut snapshot = state
580            .entries
581            .iter()
582            .filter(|(_, entry)| {
583                entry.change_offset > resume_after && entry.change_tag.as_ref() == Some(tag)
584            })
585            .map(|(persistence_id, entry)| durable_change(persistence_id, entry))
586            .collect::<Vec<_>>();
587        snapshot.sort_by_key(DurableStateChange::offset);
588        let snapshot = VecDeque::from(snapshot);
589        drop(state);
590
591        if mode == QueryMode::Current {
592            return Ok(Box::pin(stream::iter(snapshot.into_iter().map(Ok))));
593        }
594
595        let cursor = DurableStateCursor {
596            state: Arc::clone(&self.state),
597            changes: self.changes.subscribe(),
598            tag: tag.clone(),
599            offset: boundary,
600            snapshot,
601        };
602        Ok(Box::pin(stream::unfold(cursor, next_durable_change)))
603    }
604}
605
606struct DurableStateCursor {
607    state: Arc<Mutex<MemoryDurableState>>,
608    changes: watch::Receiver<u64>,
609    tag: Tag,
610    offset: u64,
611    snapshot: VecDeque<DurableStateChange>,
612}
613
614async fn next_durable_change(
615    mut cursor: DurableStateCursor,
616) -> Option<(PersistenceResult<DurableStateChange>, DurableStateCursor)> {
617    if let Some(change) = cursor.snapshot.pop_front() {
618        return Some((Ok(change), cursor));
619    }
620
621    loop {
622        let change = match scan_durable_change(&mut cursor) {
623            Ok(change) => change,
624            Err(error) => return Some((Err(error), cursor)),
625        };
626
627        if let Some(change) = change {
628            return Some((Ok(change), cursor));
629        }
630        if cursor.changes.changed().await.is_err() {
631            return None;
632        }
633    }
634}
635
636fn scan_persistence_id_event(
637    cursor: &mut PersistenceIdEventCursor,
638) -> PersistenceResult<(Option<EventEnvelope>, bool)> {
639    let state = lock(&cursor.state, "journal")?;
640    let after = cursor.offset;
641    let mut envelope = None;
642    for entry in state.event_log.iter().filter(|entry| entry.offset > after) {
643        cursor.offset = entry.offset;
644        if entry.event.persistence_id == cursor.persistence_id
645            && entry.event.sequence_nr >= cursor.from_sequence_nr
646            && entry.event.sequence_nr <= cursor.to_sequence_nr
647            && is_current_event(&state, entry)
648        {
649            envelope = Some(event_envelope(entry));
650            break;
651        }
652    }
653
654    let reached_end = cursor.to_sequence_nr != SequenceNr::new(u64::MAX)
655        && state
656            .entities
657            .get(&cursor.persistence_id)
658            .map_or(cursor.to_sequence_nr == SequenceNr::new(0), |entity| {
659                entity.highest_sequence_nr >= cursor.to_sequence_nr
660            });
661    if envelope.is_none() {
662        cursor.offset = state.last_offset;
663    }
664    Ok((envelope, reached_end))
665}
666
667fn scan_tag_event(cursor: &mut TagEventCursor) -> PersistenceResult<Option<EventEnvelope>> {
668    let state = lock(&cursor.state, "journal")?;
669    let after = cursor.offset;
670    let mut envelope = None;
671    for entry in state.event_log.iter().filter(|entry| entry.offset > after) {
672        cursor.offset = entry.offset;
673        if entry.event.tags.contains(&cursor.tag) && is_current_event(&state, entry) {
674            envelope = Some(event_envelope(entry));
675            break;
676        }
677    }
678    if envelope.is_none() {
679        cursor.offset = state.last_offset;
680    }
681    Ok(envelope)
682}
683
684fn scan_persistence_id(
685    cursor: &mut PersistenceIdsCursor,
686) -> PersistenceResult<Option<PersistenceId>> {
687    let state = lock(&cursor.state, "journal")?;
688    let persistence_id = state.persistence_ids.get(cursor.index).cloned();
689    if persistence_id.is_some() {
690        cursor.index += 1;
691    }
692    Ok(persistence_id)
693}
694
695fn scan_durable_change(
696    cursor: &mut DurableStateCursor,
697) -> PersistenceResult<Option<DurableStateChange>> {
698    let state = lock(&cursor.state, "durable-state store")?;
699    let change = state
700        .entries
701        .iter()
702        .filter(|(_, entry)| {
703            entry.change_offset > cursor.offset && entry.change_tag.as_ref() == Some(&cursor.tag)
704        })
705        .min_by_key(|(_, entry)| entry.change_offset)
706        .map(|(persistence_id, entry)| durable_change(persistence_id, entry));
707    if let Some(change) = &change {
708        // The in-memory backend only ever emits Sequence offsets.
709        cursor.offset = match change.offset() {
710            Offset::Sequence(value) => value,
711            _ => state.last_offset,
712        };
713    } else {
714        cursor.offset = state.last_offset;
715    }
716    Ok(change)
717}
718
719fn append_write(state: &mut MemoryJournalState, write: AtomicWrite) -> AppendOutcome {
720    let persistence_id = write.persistence_id().clone();
721    let highest_sequence_nr = state
722        .entities
723        .get(&persistence_id)
724        .map_or(SequenceNr::new(0), |entity| entity.highest_sequence_nr);
725    let first_sequence_nr = write.events()[0].sequence_nr;
726    let Some(expected) = highest_sequence_nr.as_u64().checked_add(1) else {
727        return AppendOutcome::Rejected {
728            reason: format!(
729                "persistence id {persistence_id} already reached the maximum sequence number"
730            ),
731        };
732    };
733
734    if first_sequence_nr != SequenceNr::new(expected) {
735        return AppendOutcome::Rejected {
736            reason: format!(
737                "expected first sequence number {expected} for {persistence_id}, got {first_sequence_nr}"
738            ),
739        };
740    }
741
742    let Ok(event_count) = u64::try_from(write.events().len()) else {
743        return AppendOutcome::Rejected {
744            reason: "atomic write contains too many events for query offsets".into(),
745        };
746    };
747    let Some(last_offset) = state.last_offset.checked_add(event_count) else {
748        return AppendOutcome::Rejected {
749            reason: "in-memory journal query offset exhausted".into(),
750        };
751    };
752
753    let is_new_persistence_id = highest_sequence_nr == SequenceNr::new(0);
754    let events = write
755        .into_events()
756        .into_iter()
757        .map(Arc::new)
758        .collect::<Vec<_>>();
759    let last_sequence_nr = events[events.len() - 1].sequence_nr;
760    let entity = state.entities.entry(persistence_id.clone()).or_default();
761    for event in &events {
762        entity.events.insert(event.sequence_nr, Arc::clone(event));
763    }
764    entity.highest_sequence_nr = last_sequence_nr;
765
766    for event in events {
767        state.last_offset += 1;
768        state.event_log.push(JournalEvent {
769            offset: state.last_offset,
770            event,
771        });
772    }
773    debug_assert_eq!(state.last_offset, last_offset);
774    if is_new_persistence_id {
775        state.persistence_ids.push(persistence_id);
776    }
777    AppendOutcome::Accepted
778}
779
780fn validate_revision(
781    entries: &HashMap<PersistenceId, DurableEntry>,
782    persistence_id: &PersistenceId,
783    new_revision: Revision,
784) -> PersistenceResult<()> {
785    let stored = entries
786        .get(persistence_id)
787        .map_or(Revision::new(0), |entry| entry.versioned_state.revision);
788    let expected = stored
789        .as_u64()
790        .checked_add(1)
791        .map(Revision::new)
792        .ok_or_else(|| PersistenceError::RevisionExhausted {
793            persistence_id: persistence_id.clone(),
794        })?;
795    if new_revision != expected {
796        return Err(PersistenceError::RevisionConflict {
797            persistence_id: persistence_id.clone(),
798            expected,
799            actual: new_revision,
800        });
801    }
802    Ok(())
803}
804
805fn event_envelope(entry: &JournalEvent) -> EventEnvelope {
806    EventEnvelope {
807        offset: Offset::Sequence(entry.offset),
808        persistence_id: entry.event.persistence_id.clone(),
809        sequence_nr: entry.event.sequence_nr,
810        timestamp_ms: entry.event.timestamp_ms,
811        adapter_manifest: entry.event.adapter_manifest.clone(),
812        payload: entry.event.payload.clone(),
813        metadata: entry.event.metadata.clone(),
814        tags: entry.event.tags.clone(),
815    }
816}
817
818fn durable_change(persistence_id: &PersistenceId, entry: &DurableEntry) -> DurableStateChange {
819    let offset = Offset::Sequence(entry.change_offset);
820    match &entry.versioned_state.state {
821        Some(state) => DurableStateChange::Updated(UpdatedDurableState {
822            offset,
823            persistence_id: persistence_id.clone(),
824            revision: entry.versioned_state.revision,
825            state: state.clone(),
826            timestamp_ms: entry.change_timestamp_ms,
827        }),
828        None => DurableStateChange::Deleted(DeletedDurableState {
829            offset,
830            persistence_id: persistence_id.clone(),
831            revision: entry.versioned_state.revision,
832            timestamp_ms: entry.change_timestamp_ms,
833        }),
834    }
835}
836
837fn is_current_event(state: &MemoryJournalState, entry: &JournalEvent) -> bool {
838    state
839        .entities
840        .get(&entry.event.persistence_id)
841        .and_then(|entity| entity.events.get(&entry.event.sequence_nr))
842        .is_some_and(|event| Arc::ptr_eq(event, &entry.event))
843}
844
845fn sequence_offset(offset: Offset) -> PersistenceResult<u64> {
846    match offset {
847        Offset::NoOffset => Ok(0),
848        Offset::Sequence(value) => Ok(value),
849        other => Err(PersistenceError::Failure(format!(
850            "the in-memory backend resumes only from Offset::Sequence positions, got {other:?}"
851        ))),
852    }
853}
854
855fn next_offset(current: u64, name: &str) -> PersistenceResult<u64> {
856    current
857        .checked_add(1)
858        .ok_or_else(|| PersistenceError::Failure(format!("in-memory {name} offset exhausted")))
859}
860
861fn timestamp_ms() -> i64 {
862    let millis = SystemTime::now()
863        .duration_since(UNIX_EPOCH)
864        .unwrap_or_default()
865        .as_millis();
866    i64::try_from(millis).unwrap_or(i64::MAX)
867}
868
869fn memory_lock_error(name: &str) -> PersistenceError {
870    PersistenceError::Failure(format!("in-memory {name} lock was poisoned"))
871}
872
873fn lock<'a, T>(mutex: &'a Mutex<T>, name: &str) -> PersistenceResult<MutexGuard<'a, T>> {
874    mutex.lock().map_err(|_| memory_lock_error(name))
875}