1use std::{
11 collections::HashSet,
12 sync::atomic::{AtomicU8, AtomicU64, Ordering},
13 time::Duration,
14};
15
16use futures_util::StreamExt;
17use tokio::time::timeout;
18
19use crate::{
20 AppendOutcome, AtomicWrite, DurableStateStore, EventStream, Journal, PersistenceError,
21 PersistenceId, PersistenceResult, ReplayRange, Revision, SelectedSnapshot, SequenceNr,
22 SerializedPayload, SerializerId, SnapshotCriteria, SnapshotMetadata, SnapshotStore,
23 StoredEvent, Tag,
24 query::{
25 DurableStateChange, DurableStateChangesQuery, EventEnvelope, EventsByPersistenceIdQuery,
26 EventsByTagQuery, Offset, PersistenceIdsQuery, QueryMode, QueryStream,
27 },
28};
29
30static TEST_NAMESPACE: AtomicU64 = AtomicU64::new(1);
31const QUERY_WAIT: Duration = Duration::from_secs(2);
32const FAILING_JOURNAL_PASS: u8 = 0;
33const FAILING_JOURNAL_FAIL_NEXT: u8 = 1;
34const FAILING_JOURNAL_REJECT_NEXT: u8 = 2;
35
36#[derive(Debug, Default)]
38pub struct FailingJournal {
39 inner: crate::MemoryJournal,
40 next_append: AtomicU8,
41}
42
43impl FailingJournal {
44 #[must_use]
46 pub fn new() -> Self {
47 Self::default()
48 }
49
50 pub fn fail_next_append(&self) {
52 self.next_append
53 .store(FAILING_JOURNAL_FAIL_NEXT, Ordering::Release);
54 }
55
56 pub fn reject_next_append(&self) {
58 self.next_append
59 .store(FAILING_JOURNAL_REJECT_NEXT, Ordering::Release);
60 }
61}
62
63#[async_trait::async_trait]
64impl Journal for FailingJournal {
65 async fn append(&self, writes: Vec<AtomicWrite>) -> PersistenceResult<Vec<AppendOutcome>> {
66 match self
67 .next_append
68 .swap(FAILING_JOURNAL_PASS, Ordering::AcqRel)
69 {
70 FAILING_JOURNAL_FAIL_NEXT => Err(PersistenceError::Failure(
71 "injected journal append failure".into(),
72 )),
73 FAILING_JOURNAL_REJECT_NEXT => Ok(writes
74 .into_iter()
75 .map(|_| AppendOutcome::Rejected {
76 reason: "injected journal append rejection".into(),
77 })
78 .collect()),
79 _ => self.inner.append(writes).await,
80 }
81 }
82
83 async fn highest_sequence_nr(
84 &self,
85 persistence_id: &PersistenceId,
86 from_hint: SequenceNr,
87 ) -> PersistenceResult<SequenceNr> {
88 self.inner
89 .highest_sequence_nr(persistence_id, from_hint)
90 .await
91 }
92
93 async fn replay(&self, range: ReplayRange) -> PersistenceResult<EventStream> {
94 self.inner.replay(range).await
95 }
96
97 async fn delete_to(
98 &self,
99 persistence_id: &PersistenceId,
100 inclusive: SequenceNr,
101 ) -> PersistenceResult<()> {
102 self.inner.delete_to(persistence_id, inclusive).await
103 }
104}
105
106pub async fn assert_journal_conformance(journal: &dyn Journal) -> PersistenceResult<()> {
108 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
109 let unknown_id = test_id("journal-unknown", namespace);
110 assert_eq!(
111 journal
112 .highest_sequence_nr(&unknown_id, SequenceNr::new(99))
113 .await?,
114 SequenceNr::new(0),
115 "an unknown persistence id must have watermark zero regardless of the hint"
116 );
117
118 assert!(matches!(
119 AtomicWrite::new(Vec::new()),
120 Err(PersistenceError::InvalidAtomicWrite(_))
121 ));
122 let mismatched_id = test_id("journal-mismatched", namespace);
123 assert!(matches!(
124 AtomicWrite::new(vec![event(&unknown_id, 1, 1), event(&mismatched_id, 2, 2),]),
125 Err(PersistenceError::InvalidAtomicWrite(_))
126 ));
127 assert!(matches!(
128 AtomicWrite::new(vec![event(&unknown_id, 1, 1), event(&unknown_id, 3, 3),]),
129 Err(PersistenceError::InvalidAtomicWrite(_))
130 ));
131
132 let ordered_id = test_id("journal-ordered", namespace);
133 let outcomes = journal
134 .append(vec![
135 atomic(vec![
136 event(&ordered_id, 1, 1),
137 event(&ordered_id, 2, 2),
138 event(&ordered_id, 3, 3),
139 ]),
140 atomic(vec![event(&ordered_id, 4, 4)]),
141 atomic(vec![event(&ordered_id, 5, 5)]),
142 ])
143 .await?;
144 assert_eq!(
145 outcomes.len(),
146 3,
147 "append must return one outcome per input"
148 );
149 assert!(
150 outcomes
151 .iter()
152 .all(|outcome| *outcome == AppendOutcome::Accepted),
153 "valid sequential writes must be accepted"
154 );
155
156 let all = replay(journal, replay_range(&ordered_id, 1, 5, u64::MAX)).await?;
157 assert_sequence_nrs(&all, &[1, 2, 3, 4, 5]);
158 assert_eq!(
159 all[1].metadata,
160 Some(payload(102)),
161 "journal replay must preserve optional metadata frames"
162 );
163 assert_eq!(all[1].tags, vec![Tag::new("even")]);
164
165 let bounded = replay(journal, replay_range(&ordered_id, 2, 4, u64::MAX)).await?;
166 assert_sequence_nrs(&bounded, &[2, 3, 4]);
167 let limited = replay(journal, replay_range(&ordered_id, 2, 5, 2)).await?;
168 assert_sequence_nrs(&limited, &[2, 3]);
169 assert!(
170 replay(journal, replay_range(&ordered_id, 5, 4, u64::MAX))
171 .await?
172 .is_empty(),
173 "reversed replay bounds must be empty"
174 );
175 assert!(
176 replay(journal, replay_range(&ordered_id, 1, 5, 0))
177 .await?
178 .is_empty(),
179 "replay max zero must be empty"
180 );
181
182 journal.delete_to(&ordered_id, SequenceNr::new(3)).await?;
183 assert_sequence_nrs(
184 &replay(journal, replay_range(&ordered_id, 1, 5, u64::MAX)).await?,
185 &[4, 5],
186 );
187 assert_eq!(
188 journal
189 .highest_sequence_nr(&ordered_id, SequenceNr::new(0))
190 .await?,
191 SequenceNr::new(5),
192 "the high watermark must survive a prefix delete"
193 );
194 journal
195 .delete_to(&ordered_id, SequenceNr::new(u64::MAX))
196 .await?;
197 assert!(
198 replay(journal, replay_range(&ordered_id, 1, u64::MAX, u64::MAX))
199 .await?
200 .is_empty(),
201 "delete-to-MAX must hide the entire stored range"
202 );
203 assert_eq!(
204 journal
205 .highest_sequence_nr(&ordered_id, SequenceNr::new(u64::MAX))
206 .await?,
207 SequenceNr::new(5),
208 "the high watermark must survive delete-to-MAX"
209 );
210 assert_eq!(
211 journal
212 .append(vec![atomic(vec![event(&ordered_id, 6, 6)])])
213 .await?,
214 vec![AppendOutcome::Accepted],
215 "a delete-to-MAX must not hide later events above the preserved watermark"
216 );
217 assert_sequence_nrs(
218 &replay(journal, replay_range(&ordered_id, 1, u64::MAX, u64::MAX)).await?,
219 &[6],
220 );
221
222 let rejected_id = test_id("journal-rejected", namespace);
223 assert_eq!(
224 journal
225 .append(vec![atomic(vec![event(&rejected_id, 1, 10)])])
226 .await?,
227 vec![AppendOutcome::Accepted]
228 );
229 let sibling_id = test_id("journal-sibling", namespace);
230 let outcomes = journal
231 .append(vec![
232 atomic(vec![event(&rejected_id, 3, 30), event(&rejected_id, 4, 40)]),
233 atomic(vec![event(&sibling_id, 1, 50), event(&sibling_id, 2, 60)]),
234 ])
235 .await?;
236 assert_eq!(
237 outcomes.len(),
238 2,
239 "append must return one outcome per input"
240 );
241 assert!(matches!(
242 &outcomes[0],
243 AppendOutcome::Rejected { reason } if !reason.is_empty()
244 ));
245 assert_eq!(outcomes[1], AppendOutcome::Accepted);
246 assert_sequence_nrs(
247 &replay(journal, replay_range(&rejected_id, 1, u64::MAX, u64::MAX)).await?,
248 &[1],
249 );
250 assert_sequence_nrs(
251 &replay(journal, replay_range(&sibling_id, 1, u64::MAX, u64::MAX)).await?,
252 &[1, 2],
253 );
254
255 Ok(())
256}
257
258pub async fn assert_snapshot_store_conformance(
260 snapshots: &dyn SnapshotStore,
261) -> PersistenceResult<()> {
262 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
263 let persistence_id = test_id("snapshot", namespace);
264 assert!(
265 snapshots
266 .load(&persistence_id, &SnapshotCriteria::latest())
267 .await?
268 .is_none(),
269 "snapshot absence must be returned as None, not a load failure"
270 );
271 assert!(
272 snapshots
273 .load(&persistence_id, &SnapshotCriteria::none())
274 .await?
275 .is_none(),
276 "SnapshotCriteria::none must never select a snapshot"
277 );
278
279 for (sequence_nr, timestamp_ms, marker) in [(1, 100, 1), (3, 300, 3), (2, 200, 2)] {
280 snapshots
281 .save(
282 snapshot_metadata(&persistence_id, sequence_nr, timestamp_ms),
283 format!("datum-tck-state-adapter-v{marker}"),
284 payload(marker),
285 )
286 .await?;
287 }
288 let latest = require_snapshot(
289 snapshots
290 .load(&persistence_id, &SnapshotCriteria::latest())
291 .await?,
292 );
293 assert_eq!(latest.metadata.sequence_nr, SequenceNr::new(3));
294 assert_eq!(latest.adapter_manifest, "datum-tck-state-adapter-v3");
295 assert_eq!(latest.state, payload(3));
296
297 let exact_two = SnapshotCriteria {
298 min_sequence_nr: SequenceNr::new(2),
299 max_sequence_nr: SequenceNr::new(2),
300 min_timestamp_ms: 200,
301 max_timestamp_ms: 200,
302 };
303 assert_eq!(
304 require_snapshot(snapshots.load(&persistence_id, &exact_two).await?).state,
305 payload(2),
306 "all snapshot criteria bounds must be inclusive"
307 );
308
309 let replacement = snapshot_metadata(&persistence_id, 3, 350);
310 snapshots
311 .save(
312 replacement.clone(),
313 "datum-tck-state-adapter-v33".into(),
314 payload(33),
315 )
316 .await?;
317 let latest = require_snapshot(
318 snapshots
319 .load(&persistence_id, &SnapshotCriteria::latest())
320 .await?,
321 );
322 assert_eq!(latest.metadata, replacement);
323 assert_eq!(latest.adapter_manifest, "datum-tck-state-adapter-v33");
324 assert_eq!(latest.state, payload(33));
325 snapshots
326 .delete(snapshot_metadata(&persistence_id, 3, 300))
327 .await?;
328 assert_eq!(
329 require_snapshot(
330 snapshots
331 .load(&persistence_id, &SnapshotCriteria::latest())
332 .await?,
333 )
334 .state,
335 payload(33),
336 "deleting replaced metadata must not remove the current same-sequence snapshot"
337 );
338
339 snapshots
340 .delete(snapshot_metadata(&persistence_id, 2, 200))
341 .await?;
342 assert!(snapshots.load(&persistence_id, &exact_two).await?.is_none());
343
344 for (sequence_nr, timestamp_ms) in [(4, 400), (5, 500), (6, 600)] {
345 snapshots
346 .save(
347 snapshot_metadata(&persistence_id, sequence_nr, timestamp_ms),
348 format!("datum-tck-state-adapter-v{sequence_nr}"),
349 payload(sequence_nr),
350 )
351 .await?;
352 }
353 let delete_range = SnapshotCriteria {
354 min_sequence_nr: SequenceNr::new(4),
355 max_sequence_nr: SequenceNr::new(5),
356 min_timestamp_ms: 400,
357 max_timestamp_ms: 500,
358 };
359 snapshots
360 .delete_matching(&persistence_id, &delete_range)
361 .await?;
362 assert!(
363 snapshots
364 .load(&persistence_id, &delete_range)
365 .await?
366 .is_none(),
367 "delete_matching must remove every snapshot inside the inclusive criteria"
368 );
369 assert_eq!(
370 require_snapshot(
371 snapshots
372 .load(&persistence_id, &SnapshotCriteria::latest())
373 .await?,
374 )
375 .metadata
376 .sequence_nr,
377 SequenceNr::new(6),
378 "delete_matching must preserve snapshots outside its criteria"
379 );
380
381 Ok(())
382}
383
384pub async fn assert_durable_state_store_conformance(
386 durable_state: &dyn DurableStateStore,
387) -> PersistenceResult<()> {
388 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
389 let persistence_id = test_id("durable", namespace);
390 let absent = durable_state.get(&persistence_id).await?;
391 assert_eq!(absent.revision, Revision::new(0));
392 assert!(
393 absent.state.is_none(),
394 "unknown durable state must be absent"
395 );
396
397 let invalid_first_revision = durable_state
398 .upsert(&persistence_id, Revision::new(2), payload(2), None)
399 .await
400 .expect_err("the first durable-state write must use revision one");
401 assert!(matches!(
402 invalid_first_revision,
403 PersistenceError::RevisionConflict {
404 expected,
405 actual,
406 ..
407 } if expected == Revision::new(1) && actual == Revision::new(2)
408 ));
409 assert_eq!(durable_state.get(&persistence_id).await?, absent);
410
411 durable_state
412 .upsert(
413 &persistence_id,
414 Revision::new(1),
415 payload(1),
416 Some(Tag::new("blue")),
417 )
418 .await?;
419 let first = durable_state.get(&persistence_id).await?;
420 assert_eq!(first.revision, Revision::new(1));
421 assert_eq!(first.state, Some(payload(1)));
422 assert_eq!(first.tag, Some(Tag::new("blue")));
423
424 let conflict = durable_state
425 .upsert(&persistence_id, Revision::new(3), payload(3), None)
426 .await
427 .expect_err("a skipped durable-state revision must conflict");
428 assert!(matches!(
429 conflict,
430 PersistenceError::RevisionConflict {
431 persistence_id: ref conflict_id,
432 expected,
433 actual,
434 } if conflict_id == &persistence_id
435 && expected == Revision::new(2)
436 && actual == Revision::new(3)
437 ));
438 assert_eq!(
439 durable_state.get(&persistence_id).await?,
440 first,
441 "a CAS conflict must not change stored durable state"
442 );
443
444 durable_state
445 .upsert(&persistence_id, Revision::new(2), payload(2), None)
446 .await?;
447 assert_eq!(durable_state.get(&persistence_id).await?.tag, None);
448 durable_state
449 .delete(&persistence_id, Revision::new(3))
450 .await?;
451 let tombstone = durable_state.get(&persistence_id).await?;
452 assert_eq!(tombstone.revision, Revision::new(3));
453 assert!(
454 tombstone.state.is_none(),
455 "delete must leave an absent-state tombstone at the advanced revision"
456 );
457 assert_eq!(
458 tombstone.tag, None,
459 "delete must clear the durable-state tag"
460 );
461
462 let stale_delete = durable_state
463 .delete(&persistence_id, Revision::new(3))
464 .await
465 .expect_err("reusing the tombstone revision must conflict");
466 assert!(matches!(
467 stale_delete,
468 PersistenceError::RevisionConflict {
469 expected,
470 actual,
471 ..
472 } if expected == Revision::new(4) && actual == Revision::new(3)
473 ));
474 assert_eq!(durable_state.get(&persistence_id).await?, tombstone);
475
476 Ok(())
477}
478
479pub async fn assert_events_by_persistence_id_query_conformance(
486 journal: &dyn Journal,
487 query: &dyn EventsByPersistenceIdQuery,
488) -> PersistenceResult<()> {
489 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
490 let persistence_id = test_id("query-pid-bounds", namespace);
491 append_accepted(
492 journal,
493 vec![
494 event(&persistence_id, 1, 1),
495 event(&persistence_id, 2, 2),
496 event(&persistence_id, 3, 3),
497 event(&persistence_id, 4, 4),
498 event(&persistence_id, 5, 5),
499 ],
500 )
501 .await?;
502
503 let bounded = collect_query(
504 query
505 .events_by_persistence_id(
506 &persistence_id,
507 SequenceNr::new(2),
508 SequenceNr::new(4),
509 QueryMode::Current,
510 )
511 .await?,
512 "current per-id inclusive range",
513 )
514 .await?;
515 assert_envelope_sequence_nrs(&bounded, &[2, 3, 4]);
516
517 let current_at_boundary = query
518 .events_by_persistence_id(
519 &persistence_id,
520 SequenceNr::new(1),
521 SequenceNr::new(6),
522 QueryMode::Current,
523 )
524 .await?;
525 append_accepted(journal, vec![event(&persistence_id, 6, 6)]).await?;
526 let boundary_events = collect_query(current_at_boundary, "current per-id boundary").await?;
527 assert_envelope_sequence_nrs(&boundary_events, &[1, 2, 3, 4, 5]);
528
529 let live_id = test_id("query-pid-live", namespace);
530 append_accepted(journal, vec![event(&live_id, 1, 11)]).await?;
531 let mut live = query
532 .events_by_persistence_id(
533 &live_id,
534 SequenceNr::new(1),
535 SequenceNr::new(3),
536 QueryMode::Live,
537 )
538 .await?;
539 let first = require_query_item(&mut live, "initial live per-id event").await?;
540 assert_eq!(first.sequence_nr, SequenceNr::new(1));
541
542 append_accepted(
543 journal,
544 vec![event(&live_id, 2, 12), event(&live_id, 3, 13)],
545 )
546 .await?;
547 let second = require_query_item(&mut live, "second live per-id event").await?;
548 let third = require_query_item(&mut live, "third live per-id event").await?;
549 assert_eq!(second.sequence_nr, SequenceNr::new(2));
550 assert_eq!(third.sequence_nr, SequenceNr::new(3));
551 assert!(
552 next_query_item(&mut live, "finite live per-id completion")
553 .await?
554 .is_none(),
555 "a live per-id query must complete after its finite inclusive upper bound"
556 );
557
558 Ok(())
559}
560
561pub async fn assert_events_by_tag_query_conformance(
567 journal: &dyn Journal,
568 query: &dyn EventsByTagQuery,
569) -> PersistenceResult<()> {
570 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
571 let tag = Tag::new(format!("query-order-{namespace}"));
572 let first_id = test_id("query-tag-first", namespace);
573 let second_id = test_id("query-tag-second", namespace);
574 append_accepted(journal, vec![tagged_event(&first_id, 1, 101, &tag)]).await?;
575 append_accepted(journal, vec![tagged_event(&second_id, 1, 102, &tag)]).await?;
576 append_accepted(journal, vec![tagged_event(&first_id, 2, 103, &tag)]).await?;
577
578 let ordered = collect_query(
579 query
580 .events_by_tag(&tag, Offset::NoOffset, QueryMode::Current)
581 .await?,
582 "current tag ordering",
583 )
584 .await?;
585 assert_eq!(
586 ordered
587 .iter()
588 .map(|envelope| (&envelope.persistence_id, envelope.sequence_nr.as_u64()))
589 .collect::<Vec<_>>(),
590 vec![(&first_id, 1), (&second_id, 1), (&first_id, 2)],
591 "tag queries must preserve the backend's global append order"
592 );
593 assert_strict_sequence_offsets(&ordered);
594
595 let resume_tag = Tag::new(format!("query-resume-{namespace}"));
596 let resume_id = test_id("query-tag-resume", namespace);
597 append_accepted(
598 journal,
599 vec![
600 tagged_event(&resume_id, 1, 201, &resume_tag),
601 tagged_event(&resume_id, 2, 202, &resume_tag),
602 tagged_event(&resume_id, 3, 203, &resume_tag),
603 ],
604 )
605 .await?;
606
607 let mut disconnected = query
608 .events_by_tag(&resume_tag, Offset::NoOffset, QueryMode::Live)
609 .await?;
610 let first = require_query_item(&mut disconnected, "first pre-disconnect tag event").await?;
611 let second = require_query_item(&mut disconnected, "second pre-disconnect tag event").await?;
612 let resume_offset = second.offset;
613 drop(disconnected);
614
615 append_accepted(journal, vec![tagged_event(&resume_id, 4, 204, &resume_tag)]).await?;
616 let resumed = collect_query(
617 query
618 .events_by_tag(&resume_tag, resume_offset, QueryMode::Current)
619 .await?,
620 "resumed current tag query",
621 )
622 .await?;
623
624 let observed = std::iter::once(first)
625 .chain(std::iter::once(second))
626 .chain(resumed)
627 .filter(|envelope| envelope.persistence_id == resume_id)
628 .map(|envelope| envelope.sequence_nr.as_u64())
629 .collect::<HashSet<_>>();
630 assert_eq!(
631 observed,
632 HashSet::from([1, 2, 3, 4]),
633 "resuming from the last observed offset must not lose unseen tag events"
634 );
635
636 Ok(())
637}
638
639pub async fn assert_persistence_ids_query_conformance(
644 journal: &dyn Journal,
645 query: &dyn PersistenceIdsQuery,
646) -> PersistenceResult<()> {
647 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
648 let first_id = test_id("query-ids-first", namespace);
649 let second_id = test_id("query-ids-second", namespace);
650 let third_id = test_id("query-ids-third", namespace);
651 append_accepted(journal, vec![event(&first_id, 1, 301)]).await?;
652
653 let current_at_boundary = query.persistence_ids(QueryMode::Current).await?;
654 append_accepted(journal, vec![event(&second_id, 1, 302)]).await?;
655 let current = collect_query(current_at_boundary, "current persistence ids boundary").await?;
656 assert!(current.contains(&first_id));
657 assert!(
658 !current.contains(&second_id),
659 "Current persistence_ids must exclude ids first written after its boundary"
660 );
661
662 let mut live = query.persistence_ids(QueryMode::Live).await?;
663 let initial_count = 2;
664 let mut initial = Vec::with_capacity(initial_count);
665 for _ in 0..initial_count {
666 initial.push(require_query_item(&mut live, "initial live persistence id").await?);
667 }
668 assert!(initial.contains(&first_id));
669 assert!(initial.contains(&second_id));
670
671 append_accepted(journal, vec![event(&third_id, 1, 303)]).await?;
672 assert_eq!(
673 require_query_item(&mut live, "later live persistence id").await?,
674 third_id
675 );
676
677 Ok(())
678}
679
680pub async fn assert_durable_state_changes_query_conformance(
686 durable_state: &dyn DurableStateStore,
687 query: &dyn DurableStateChangesQuery,
688) -> PersistenceResult<()> {
689 let namespace = TEST_NAMESPACE.fetch_add(1, Ordering::Relaxed);
690 let tag = Tag::new(format!("query-durable-{namespace}"));
691 let persistence_id = test_id("query-durable", namespace);
692 for revision in 1..=3 {
693 durable_state
694 .upsert(
695 &persistence_id,
696 Revision::new(revision),
697 payload(revision),
698 Some(tag.clone()),
699 )
700 .await?;
701 }
702
703 let current = collect_query(
704 query
705 .changes(&tag, Offset::NoOffset, QueryMode::Current)
706 .await?,
707 "current durable-state changes",
708 )
709 .await?;
710 let matching = current
711 .iter()
712 .filter(|change| change.persistence_id() == &persistence_id)
713 .collect::<Vec<_>>();
714 assert_eq!(
715 matching.len(),
716 1,
717 "Current durable changes must coalesce to one latest value per id"
718 );
719 assert_eq!(matching[0].revision(), Revision::new(3));
720 assert!(matches!(matching[0], DurableStateChange::Updated(_)));
721
722 let mut live = query
723 .changes(&tag, Offset::NoOffset, QueryMode::Live)
724 .await?;
725 let initial = require_query_item(&mut live, "initial live durable change").await?;
726 assert_eq!(initial.revision(), Revision::new(3));
727
728 for revision in 4..=6 {
729 durable_state
730 .upsert(
731 &persistence_id,
732 Revision::new(revision),
733 payload(revision),
734 Some(tag.clone()),
735 )
736 .await?;
737 }
738 let latest = timeout(QUERY_WAIT, async {
739 loop {
740 match live.next().await {
741 Some(Ok(change)) if change.persistence_id() == &persistence_id => {
742 if change.revision() == Revision::new(6) {
743 break Ok(change);
744 }
745 }
746 Some(Ok(_)) => {}
747 Some(Err(error)) => break Err(error),
748 None => {
749 break Err(PersistenceError::Failure(
750 "live durable query completed before the latest revision".into(),
751 ));
752 }
753 }
754 }
755 })
756 .await
757 .map_err(|_| PersistenceError::Failure("latest durable revision timed out".into()))??;
758 let resume_offset = latest.offset();
759 drop(live);
760
761 durable_state
762 .delete(&persistence_id, Revision::new(7))
763 .await?;
764 let resumed = collect_query(
765 query
766 .changes(&tag, resume_offset, QueryMode::Current)
767 .await?,
768 "resumed durable-state changes",
769 )
770 .await?;
771 assert!(
772 resumed.iter().any(|change| {
773 matches!(
774 change,
775 DurableStateChange::Deleted(deleted)
776 if deleted.persistence_id == persistence_id
777 && deleted.revision == Revision::new(7)
778 )
779 }),
780 "resuming after the latest observed durable offset must expose the later tombstone"
781 );
782
783 Ok(())
784}
785
786fn test_id(kind: &str, namespace: u64) -> PersistenceId {
787 PersistenceId::new("datum-tck", format!("{kind}-{namespace}"))
788 .expect("conformance-suite ids are valid")
789}
790
791fn payload(marker: u64) -> SerializedPayload {
792 SerializedPayload::new(
793 SerializerId::new(7),
794 "datum-tck-v1",
795 marker.to_be_bytes().to_vec(),
796 )
797}
798
799fn event(persistence_id: &PersistenceId, sequence_nr: u64, marker: u64) -> StoredEvent {
800 let is_even = sequence_nr & 1 == 0;
801 StoredEvent {
802 persistence_id: persistence_id.clone(),
803 sequence_nr: SequenceNr::new(sequence_nr),
804 adapter_manifest: "datum-tck-adapter-v1".to_owned(),
805 writer_uuid: "datum-tck-writer".to_owned(),
806 timestamp_ms: i64::try_from(marker).expect("test marker fits i64"),
807 metadata: is_even.then(|| payload(marker + 100)),
808 payload: payload(marker),
809 tags: is_even.then(|| Tag::new("even")).into_iter().collect(),
810 }
811}
812
813fn tagged_event(
814 persistence_id: &PersistenceId,
815 sequence_nr: u64,
816 marker: u64,
817 tag: &Tag,
818) -> StoredEvent {
819 let mut event = event(persistence_id, sequence_nr, marker);
820 event.tags = vec![tag.clone()];
821 event
822}
823
824fn atomic(events: Vec<StoredEvent>) -> AtomicWrite {
825 AtomicWrite::new(events).expect("conformance-suite writes are internally valid")
826}
827
828fn replay_range(persistence_id: &PersistenceId, from: u64, to: u64, max: u64) -> ReplayRange {
829 ReplayRange {
830 persistence_id: persistence_id.clone(),
831 from: SequenceNr::new(from),
832 to: SequenceNr::new(to),
833 max,
834 }
835}
836
837async fn replay(journal: &dyn Journal, range: ReplayRange) -> PersistenceResult<Vec<StoredEvent>> {
838 let stream = journal.replay(range).await?;
839 collect_events(stream).await
840}
841
842async fn collect_events(mut stream: EventStream) -> PersistenceResult<Vec<StoredEvent>> {
843 let mut events = Vec::new();
844 while let Some(event) = stream.next().await {
845 events.push(event?);
846 }
847 Ok(events)
848}
849
850async fn append_accepted(journal: &dyn Journal, events: Vec<StoredEvent>) -> PersistenceResult<()> {
851 let outcome = journal.append_one(atomic(events)).await?;
852 assert_eq!(
853 outcome,
854 AppendOutcome::Accepted,
855 "conformance-suite setup writes must be accepted"
856 );
857 Ok(())
858}
859
860async fn collect_query<T>(stream: QueryStream<T>, context: &str) -> PersistenceResult<Vec<T>> {
861 timeout(QUERY_WAIT, async move {
862 let mut stream = stream;
863 let mut items = Vec::new();
864 while let Some(item) = stream.next().await {
865 items.push(item?);
866 }
867 Ok(items)
868 })
869 .await
870 .map_err(|_| PersistenceError::Failure(format!("{context} timed out")))?
871}
872
873async fn next_query_item<T>(
874 stream: &mut QueryStream<T>,
875 context: &str,
876) -> PersistenceResult<Option<T>> {
877 timeout(QUERY_WAIT, stream.next())
878 .await
879 .map_err(|_| PersistenceError::Failure(format!("{context} timed out")))?
880 .transpose()
881}
882
883async fn require_query_item<T>(stream: &mut QueryStream<T>, context: &str) -> PersistenceResult<T> {
884 next_query_item(stream, context).await?.ok_or_else(|| {
885 PersistenceError::Failure(format!("{context} completed without an expected item"))
886 })
887}
888
889fn assert_sequence_nrs(events: &[StoredEvent], expected: &[u64]) {
890 let actual = events
891 .iter()
892 .map(|event| event.sequence_nr.as_u64())
893 .collect::<Vec<_>>();
894 assert_eq!(actual, expected, "replay sequence numbers differ");
895}
896
897fn assert_envelope_sequence_nrs(events: &[EventEnvelope], expected: &[u64]) {
898 let actual = events
899 .iter()
900 .map(|event| event.sequence_nr.as_u64())
901 .collect::<Vec<_>>();
902 assert_eq!(actual, expected, "query sequence numbers differ");
903}
904
905fn assert_strict_sequence_offsets(events: &[EventEnvelope]) {
906 let mut sequences = Vec::new();
911 let mut timestamps = Vec::new();
912 for event in events {
913 match event.offset {
914 Offset::Sequence(offset) => sequences.push(offset),
915 Offset::Timestamp {
916 epoch_micros,
917 seq_nr,
918 } => timestamps.push((epoch_micros, seq_nr)),
919 other => panic!("an emitted event must carry a concrete offset, got {other:?}"),
920 }
921 }
922 assert!(
923 sequences.is_empty() || timestamps.is_empty(),
924 "a backend must not mix offset kinds in one stream"
925 );
926 assert!(
927 sequences.windows(2).all(|pair| pair[0] < pair[1]),
928 "tag-query sequence offsets must follow strict global append order: {sequences:?}"
929 );
930 assert!(
931 timestamps.windows(2).all(|pair| pair[0] <= pair[1]),
932 "tag-query timestamp offsets must be non-decreasing: {timestamps:?}"
933 );
934}
935
936fn snapshot_metadata(
937 persistence_id: &PersistenceId,
938 sequence_nr: u64,
939 timestamp_ms: i64,
940) -> SnapshotMetadata {
941 SnapshotMetadata {
942 persistence_id: persistence_id.clone(),
943 sequence_nr: SequenceNr::new(sequence_nr),
944 timestamp_ms,
945 }
946}
947
948fn require_snapshot(snapshot: Option<SelectedSnapshot>) -> SelectedSnapshot {
949 snapshot.expect("a matching saved snapshot must be returned")
950}
951
952#[cfg(test)]
953mod tests {
954 use super::*;
955 use crate::{MemoryDurableStateStore, MemoryJournal, MemorySnapshotStore};
956
957 #[tokio::test]
958 async fn memory_backends_pass_the_public_conformance_suite() -> PersistenceResult<()> {
959 assert_journal_conformance(&MemoryJournal::new()).await?;
960 assert_snapshot_store_conformance(&MemorySnapshotStore::new()).await?;
961 assert_durable_state_store_conformance(&MemoryDurableStateStore::new()).await?;
962 Ok(())
963 }
964
965 struct FailingSnapshotStore;
966
967 #[async_trait::async_trait]
968 impl SnapshotStore for FailingSnapshotStore {
969 async fn load(
970 &self,
971 _persistence_id: &PersistenceId,
972 _criteria: &SnapshotCriteria,
973 ) -> PersistenceResult<Option<SelectedSnapshot>> {
974 Err(PersistenceError::Failure(
975 "injected snapshot load failure".to_owned(),
976 ))
977 }
978
979 async fn save(
980 &self,
981 _metadata: SnapshotMetadata,
982 _adapter_manifest: String,
983 _state: SerializedPayload,
984 ) -> PersistenceResult<()> {
985 Ok(())
986 }
987
988 async fn delete(&self, _metadata: SnapshotMetadata) -> PersistenceResult<()> {
989 Ok(())
990 }
991
992 async fn delete_matching(
993 &self,
994 _persistence_id: &PersistenceId,
995 _criteria: &SnapshotCriteria,
996 ) -> PersistenceResult<()> {
997 Ok(())
998 }
999 }
1000
1001 #[tokio::test]
1002 async fn snapshot_conformance_does_not_treat_load_failure_as_absence() {
1003 let error = assert_snapshot_store_conformance(&FailingSnapshotStore)
1004 .await
1005 .expect_err("the injected load failure must propagate");
1006 assert!(
1007 matches!(error, PersistenceError::Failure(message) if message.contains("injected"))
1008 );
1009 }
1010}