1pub mod write_group_rules {
27 use alloc::format;
28 use alloc::string::String;
29 use alloc::vec::Vec;
30 use core::num::NonZeroUsize;
31
32 use happenstance_core::{
33 AppendCondition, Event, EventId, EventStore, EventType, Query, QueryItem, ReadOptions,
34 RecordedAt, SequencePosition, StoreId, collect,
35 };
36 use happenstance_sync::{
37 GroupPage, IngestGroup, IngestStore, ReplicatedEvent, Waiting, WriteGroup, WriteGroupStore,
38 };
39 use happenstance_testkit::RuleOutcome;
40
41 use crate::IngestFixture;
42 use crate::violation::{Violation, ensure};
43
44 const CLAUSE: &str = "SY-39";
46
47 const WHOLE_LOG: NonZeroUsize = NonZeroUsize::MIN.saturating_add(63);
49
50 const MAX_PAGES: usize = 64;
53
54 const APPENDED: EventType = EventType::from_static("GroupAppended");
55 const SHIPPED: EventType = EventType::from_static("GroupShipped");
56 const REVERSED: EventType = EventType::from_static("GroupReversed");
57
58 const ORIGIN: StoreId = StoreId::from_bytes([0x79; 16]);
60
61 pub async fn an_append_reads_back_as_one_group<F>(
79 open: impl AsyncFn() -> F,
80 ) -> Result<RuleOutcome, Violation>
81 where
82 F: IngestFixture,
83 F::Store: WriteGroupStore,
84 {
85 let fixture = open().await;
86 let store = fixture.connect().await;
87 append(&store, &["append-a1", "append-a2", "append-a3"]).await?;
88 append(&store, &["append-b1"]).await?;
89
90 let page = read(&store, None, WHOLE_LOG).await?;
91
92 expect_shape(
93 &page,
94 &[&["append-a1", "append-a2", "append-a3"], &["append-b1"]],
95 )?;
96 let expected = [
97 position_of(&store, "append-a1").await?,
98 position_of(&store, "append-b1").await?,
99 ];
100 let firsts: Vec<SequencePosition> = page.groups.iter().map(WriteGroup::first).collect();
101 ensure(firsts == expected, CLAUSE, || {
102 format!(
103 "the store named its two appends {firsts:?}; the positions it gave their first \
104 events are {expected:?}"
105 )
106 })?;
107 ensure(
108 page.groups.iter().all(|g| g.guard().is_none()),
109 CLAUSE,
110 || String::from("a local append read back with a guard; a local append records none"),
111 )?;
112 Ok(RuleOutcome::Ran)
113 }
114
115 pub async fn an_ingested_group_keeps_its_boundary_and_guard<F>(
132 open: impl AsyncFn() -> F,
133 ) -> Result<RuleOutcome, Violation>
134 where
135 F: IngestFixture,
136 F::Store: WriteGroupStore,
137 {
138 let fixture = open().await;
139 let store = fixture.connect().await;
140 ensure_foreign(&store).await?;
141 let guard = guard()?;
142 let x = [shipped(4, "ingest-x1")?, shipped(5, "ingest-x2")?];
143 let y = [shipped(6, "ingest-y1")?];
144
145 ingest(
146 &store,
147 &[
148 IngestGroup::new(&x, &[]).with_guard(Some(&guard)),
149 IngestGroup::new(&y, &[]),
150 ],
151 )
152 .await?;
153 let page = read(&store, None, WHOLE_LOG).await?;
154
155 expect_shape(&page, &[&["ingest-x1", "ingest-x2"], &["ingest-y1"]])?;
156 let ids: Vec<EventId> = events(&page).map(|event| event.id).collect();
157 let sent: Vec<EventId> = x.iter().chain(&y).map(|event| event.id).collect();
158 ensure(ids == sent, CLAUSE, || {
159 format!("the store read back identities {ids:?} for the origin's {sent:?}")
160 })?;
161 let guards: Vec<Option<&AppendCondition>> =
162 page.groups.iter().map(WriteGroup::guard).collect();
163 ensure(guards == [Some(&guard), None], CLAUSE, || {
164 format!(
165 "the store read back guards {guards:?}; the first group arrived under \
166 {guard:?} and the second under none"
167 )
168 })?;
169 Ok(RuleOutcome::Ran)
170 }
171
172 pub async fn compensation_joins_its_group<F>(
188 open: impl AsyncFn() -> F,
189 ) -> Result<RuleOutcome, Violation>
190 where
191 F: IngestFixture,
192 F::Store: WriteGroupStore,
193 {
194 let fixture = open().await;
195 let store = fixture.connect().await;
196 ensure_foreign(&store).await?;
197 let losing = [shipped(9, "compensated-losing")?];
198 let reversal = [opaque(REVERSED, "compensated-reversal")?];
199
200 ingest(&store, &[IngestGroup::new(&losing, &reversal)]).await?;
201 let page = read(&store, None, WHOLE_LOG).await?;
202
203 expect_shape(&page, &[&["compensated-losing", "compensated-reversal"]])?;
204 Ok(RuleOutcome::Ran)
205 }
206
207 pub async fn a_group_after_a_redelivery_is_named_by_its_first_landed_row<F>(
232 open: impl AsyncFn() -> F,
233 ) -> Result<RuleOutcome, Violation>
234 where
235 F: IngestFixture,
236 F::Store: WriteGroupStore,
237 {
238 let fixture = open().await;
239 let store = fixture.connect().await;
240 ensure_foreign(&store).await?;
241 let guard = guard()?;
242 let held = [shipped(21, "redelivered-held")?];
243 let redelivered = [
244 shipped(21, "redelivered-held")?,
245 shipped(22, "redelivered-new1")?,
246 shipped(23, "redelivered-new2")?,
247 ];
248
249 ingest(&store, &[IngestGroup::new(&held, &[])]).await?;
250 append(&store, &["redelivered-local1", "redelivered-local2"]).await?;
251 ingest(
252 &store,
253 &[IngestGroup::new(&redelivered, &[]).with_guard(Some(&guard))],
254 )
255 .await?;
256 let page = read(&store, None, WHOLE_LOG).await?;
257
258 expect_shape(
259 &page,
260 &[
261 &["redelivered-held"],
262 &["redelivered-local1", "redelivered-local2"],
263 &["redelivered-new1", "redelivered-new2"],
264 ],
265 )?;
266 let landed = position_of(&store, "redelivered-new1").await?;
267 let named = page.groups.last().map(WriteGroup::first);
268 ensure(named == Some(landed), CLAUSE, || {
269 format!(
270 "the store named the group that landed after a re-delivery {named:?}; the first \
271 row it wrote is at {landed}"
272 )
273 })?;
274 let kept = page.groups.last().and_then(WriteGroup::guard);
275 ensure(kept == Some(&guard), CLAUSE, || {
276 format!(
277 "the group that landed after a re-delivery read back with the guard {kept:?}; \
278 it arrived under {guard:?}"
279 )
280 })?;
281 Ok(RuleOutcome::Ran)
282 }
283
284 pub async fn a_read_never_cuts_a_group<F>(
304 open: impl AsyncFn() -> F,
305 ) -> Result<RuleOutcome, Violation>
306 where
307 F: IngestFixture,
308 F::Store: WriteGroupStore,
309 {
310 let fixture = open().await;
311 let store = fixture.connect().await;
312 append(&store, &["cut-a1", "cut-a2"]).await?;
313 append(&store, &["cut-b1", "cut-b2", "cut-b3"]).await?;
314 append(&store, &["cut-c1", "cut-c2"]).await?;
315
316 let head = read(&store, None, budget(4)?).await?;
317 expect_shape(&head, &[&["cut-a1", "cut-a2"]])?;
318
319 let after = head.groups.first().map(WriteGroup::first);
320 let oversized = read(&store, after, budget(1)?).await?;
321 expect_shape(&oversized, &[&["cut-b1", "cut-b2", "cut-b3"]])?;
322 Ok(RuleOutcome::Ran)
323 }
324
325 pub async fn pages_chain_on_first_and_end_with_nothing<F>(
344 open: impl AsyncFn() -> F,
345 ) -> Result<RuleOutcome, Violation>
346 where
347 F: IngestFixture,
348 F::Store: WriteGroupStore,
349 {
350 let fixture = open().await;
351 let store = fixture.connect().await;
352 let written: [&[&str]; 4] = [
353 &["chain-a1", "chain-a2"],
354 &["chain-b1"],
355 &["chain-c1", "chain-c2"],
356 &["chain-d1"],
357 ];
358 for group in written {
359 append(&store, group).await?;
360 }
361
362 let pages = chain(&store, budget(2)?).await?;
363
364 let read: Vec<Vec<String>> = pages.iter().flat_map(shape).collect();
365 let expected: Vec<Vec<String>> = written.iter().map(|group| owned(group)).collect();
366 ensure(read == expected, CLAUSE, || {
367 format!("chained pages read back groups {read:?}; the log holds {expected:?}")
368 })?;
369 let waiting: Vec<Waiting> = pages.iter().map(|page| page.waiting).collect();
370 let Some((last, before)) = waiting.split_last() else {
371 return Err(Violation::new(CLAUSE, "the store returned no page at all"));
372 };
373 ensure(
374 *last == Waiting::Nothing && !before.contains(&Waiting::Nothing),
375 CLAUSE,
376 || {
377 format!(
378 "the pages said {waiting:?}; only the last, which reached the end of the \
379 log, may say Nothing, and it must"
380 )
381 },
382 )?;
383 Ok(RuleOutcome::Ran)
384 }
385
386 async fn chain<S>(store: &S, max: NonZeroUsize) -> Result<Vec<GroupPage>, Violation>
389 where
390 S: WriteGroupStore,
391 {
392 let mut pages = Vec::new();
393 let mut after = None;
394 for _ in 0..MAX_PAGES {
395 let page = read(store, after, max).await?;
396 let Some(last) = page.groups.last() else {
397 return Ok(pages);
398 };
399 after = Some(last.first());
400 pages.push(page);
401 }
402 Err(Violation::new(
403 CLAUSE,
404 format!("the store was still handing back groups after {MAX_PAGES} pages"),
405 ))
406 }
407
408 fn expect_shape(page: &GroupPage, expected: &[&[&str]]) -> Result<(), Violation> {
410 let read = shape(page);
411 let expected: Vec<Vec<String>> = expected.iter().map(|group| owned(group)).collect();
412 ensure(read == expected, CLAUSE, || {
413 format!("the store read back groups {read:?} where it wrote {expected:?}")
414 })
415 }
416
417 fn shape(page: &GroupPage) -> Vec<Vec<String>> {
419 page.groups
420 .iter()
421 .map(|group| {
422 group
423 .events()
424 .iter()
425 .map(|event| String::from_utf8_lossy(event.event.data()).into_owned())
426 .collect()
427 })
428 .collect()
429 }
430
431 fn owned(group: &[&str]) -> Vec<String> {
432 group.iter().map(|payload| String::from(*payload)).collect()
433 }
434
435 fn events(page: &GroupPage) -> impl Iterator<Item = &ReplicatedEvent> + '_ {
436 page.groups.iter().flat_map(|group| group.events().iter())
437 }
438
439 fn budget(events: usize) -> Result<NonZeroUsize, Violation> {
440 NonZeroUsize::new(events).ok_or_else(|| Violation::new(CLAUSE, "a page budget of zero"))
441 }
442
443 async fn append<S: EventStore>(store: &S, payloads: &[&str]) -> Result<(), Violation> {
445 let events = payloads
446 .iter()
447 .map(|payload| opaque(APPENDED, payload))
448 .collect::<Result<Vec<Event>, Violation>>()?;
449 EventStore::append(store, &events, None)
450 .await
451 .map(|_| ())
452 .map_err(|error| {
453 Violation::new(CLAUSE, format!("the store refused an append: {error}"))
454 })
455 }
456
457 async fn ingest<S: IngestStore>(
458 store: &S,
459 groups: &[IngestGroup<'_>],
460 ) -> Result<(), Violation> {
461 IngestStore::ingest(store, groups)
462 .await
463 .map(|_| ())
464 .map_err(|error| {
465 Violation::new(CLAUSE, format!("the store refused an ingest: {error}"))
466 })
467 }
468
469 async fn read<S: WriteGroupStore>(
470 store: &S,
471 after: Option<SequencePosition>,
472 max: NonZeroUsize,
473 ) -> Result<GroupPage, Violation> {
474 WriteGroupStore::read_groups(store, after, max)
475 .await
476 .map_err(|error| {
477 Violation::new(CLAUSE, format!("the store refused a group read: {error}"))
478 })
479 }
480
481 async fn position_of<S: EventStore>(
483 store: &S,
484 payload: &str,
485 ) -> Result<SequencePosition, Violation> {
486 let log = collect(EventStore::read(store, &Query::all(), ReadOptions::new()))
487 .await
488 .map_err(|error| {
489 Violation::new(
490 CLAUSE,
491 format!("the store refused a read of its log: {error}"),
492 )
493 })?;
494 log.iter()
495 .find(|row| row.event.data().as_ref() == payload.as_bytes())
496 .map(|row| row.position)
497 .ok_or_else(|| Violation::new(CLAUSE, format!("{payload} is not in the log")))
498 }
499
500 async fn ensure_foreign<S: IngestStore>(store: &S) -> Result<(), Violation> {
502 let own = IngestStore::store_id(store).await.map_err(|error| {
503 Violation::new(CLAUSE, format!("the store refused its identity: {error}"))
504 })?;
505 ensure(own != ORIGIN, CLAUSE, || {
506 format!("the fixture's store has the incarnation {own}, the rules' foreign origin")
507 })
508 }
509
510 fn guard() -> Result<AppendCondition, Violation> {
512 let item = QueryItem::of_types([SHIPPED]).map_err(|error| {
513 Violation::new(CLAUSE, format!("the rule's own query is invalid: {error}"))
514 })?;
515 Ok(AppendCondition::new(Query::from_item(item)))
516 }
517
518 fn shipped(position: u64, payload: &str) -> Result<ReplicatedEvent, Violation> {
519 let at = SequencePosition::new(position)
520 .ok_or_else(|| Violation::new(CLAUSE, "the rule's origin position is zero"))?;
521 Ok(ReplicatedEvent::new(
522 EventId::new(ORIGIN, at),
523 RecordedAt::from_millis(1_800_000_000_000),
524 opaque(SHIPPED, payload)?,
525 ))
526 }
527
528 fn opaque(event_type: EventType, payload: &str) -> Result<Event, Violation> {
529 Event::new(event_type, payload.as_bytes().to_vec()).map_err(|error| {
530 Violation::new(CLAUSE, format!("the rule's own event is invalid: {error}"))
531 })
532 }
533}
534
535#[macro_export]
552macro_rules! for_each_write_group_rule {
553 ($($callback:tt)+) => {
556 $($callback)+! {
557 an_append_reads_back_as_one_group,
559 an_ingested_group_keeps_its_boundary_and_guard,
560 compensation_joins_its_group,
561 a_group_after_a_redelivery_is_named_by_its_first_landed_row,
562
563 a_read_never_cuts_a_group,
565 pages_chain_on_first_and_end_with_nothing,
566 }
567 };
568}
569
570#[macro_export]
576macro_rules! emit_write_group_tokio {
577 ($($name:ident),* $(,)?) => {
578 $(
579 #[tokio::test]
580 async fn $name() -> ::core::result::Result<(), $crate::Violation> {
581 $crate::__private::write_group_rules::$name(__write_group_fixture)
582 .await?
583 .report(::core::stringify!($name));
584 Ok(())
585 }
586 )*
587 };
588}
589
590#[macro_export]
593macro_rules! emit_write_group_blocking {
594 ($($name:ident),* $(,)?) => {
595 $(
596 #[test]
597 fn $name() -> ::core::result::Result<(), $crate::Violation> {
598 $crate::__private::block_on(
599 $crate::__private::write_group_rules::$name(__write_group_fixture),
600 )?
601 .report(::core::stringify!($name));
602 Ok(())
603 }
604 )*
605 };
606}
607
608#[macro_export]
616macro_rules! emit_write_group_wasm {
617 ($($name:ident),* $(,)?) => {
618 $(
619 #[::wasm_bindgen_test::wasm_bindgen_test]
620 async fn $name() -> ::core::result::Result<(), $crate::Violation> {
621 let __outcome =
622 $crate::__private::write_group_rules::$name(__write_group_fixture).await?;
623 if let Some(__line) = __outcome.skip_line(::core::stringify!($name)) {
624 ::wasm_bindgen_test::console_log!("{}", __line);
625 }
626 Ok(())
627 }
628 )*
629 };
630}
631
632#[doc(hidden)]
637#[macro_export]
638macro_rules! __write_group_rule_names {
639 ($($name:ident),* $(,)?) => { [ $( ::core::stringify!($name) ),* ] };
640}
641
642#[cfg(test)]
645#[test]
646fn no_orphan_write_group_rules() {
647 const SOURCE: &str = include_str!("write_group_suite.rs");
648 const PREFIX: &str = " pub async fn ";
649
650 let registered = crate::for_each_write_group_rule!(crate::__write_group_rule_names);
651 let mut declared: Vec<&str> = SOURCE
652 .lines()
653 .filter_map(|line| line.strip_prefix(PREFIX))
654 .filter_map(|rest| {
655 rest.split(|c: char| !c.is_alphanumeric() && c != '_')
656 .next()
657 })
658 .collect();
659
660 assert!(
661 !declared.is_empty(),
662 "the source scan matched no rule at all"
663 );
664 declared.sort_unstable();
665 let mut registered_sorted = registered.to_vec();
666 registered_sorted.sort_unstable();
667 assert_eq!(
668 declared, registered_sorted,
669 "`for_each_write_group_rule!` and the rules declared in `write_group_suite.rs` disagree"
670 );
671}