happenstance_sync_testkit/lib.rs
1//! The conformance suite for `happenstance-sync` peers, and for the stores
2//! they ingest into.
3//!
4//! # Status: the peer, ingest, write-group, restore, watermark and convergence families
5//!
6//! Published since #108 part E, with `happenstance-sync`, and grown rule by rule
7//! through phase 13, which ran it against the network peers. It is the bar a peer or ingest adapter must
8//! clear before it is considered to exist, exactly as `happenstance-testkit` is
9//! for a store, and an adapter outside this workspace mounts it the same way.
10//! **Pin it exactly**: a new rule is a minor of this crate's number.
11//!
12//! Publishing settled the two questions this paragraph used to defer. Its
13//! `version` is the workspace's, in lockstep until 1.0 — ADR-0066 §4 makes a
14//! new rule a minor of *its* number, and lockstep keeps that true while the
15//! workspace is `0.y`. And `happenstance-testkit`'s `RuleOutcome` is part of
16//! this crate's public API, through every rule's signature.
17//!
18//! # Mounting it
19//!
20//! ```
21//! # macro_rules! ignore { ($($t:tt)*) => {} }
22//! # ignore! {
23//! happenstance_sync_testkit::sync_peer_conformance!(
24//! happenstance_sync_testkit::MemorySyncFixture::new()
25//! );
26//! # }
27//! ```
28//!
29//! The expression builds a [`SyncFixture`]: one isolated backing peer per
30//! instance. It is evaluated **inside the generated module**, so a fixture type
31//! defined beside the invocation is named `super::MyFixture`; the macro does not
32//! glob-import its parent, because an unused glob would be a warning in every
33//! crate that named its fixture by full path.
34//!
35//! # What is checked
36//!
37//! | Rule | Clause | What it rejects |
38//! |---|---|---|
39//! | [`ingest_never_rejects`](rules::ingest_never_rejects) | SY-1 | a peer that evaluates the travelling guard and refuses or drops a conflicting fact |
40//! | [`compensation_is_atomic_with_the_losing_event`](rules::compensation_is_atomic_with_the_losing_event) | SY-2 | a peer that splits a losing event from the compensation that rode with it |
41//! | [`event_id_order_is_identical_on_every_peer`](rules::event_id_order_is_identical_on_every_peer) | SY-23 | a peer that dedupes by the highest origin position it has seen, and so drops an origin's lower event that arrives late |
42//! | [`peer_declares_its_own_limits`](rules::peer_declares_its_own_limits) | SY-18 | a peer whose declared limits admit an event its ingest then refuses, or that declares below VT-21's floor |
43//! | [`peer_takes_a_batch_at_its_declared_limits`](rules::peer_takes_a_batch_at_its_declared_limits) | SY-18 | a peer that refuses a push its own batch limits admit: more events, or more bytes, than it really takes |
44//! | [`push_envelope_preserves_group_boundaries`](rules::push_envelope_preserves_group_boundaries) | SY-30 | a peer that merges the groups of a page into one, or strips the guard a group was pushed with |
45//! | [`every_refusal_states_its_class`](rules::every_refusal_states_its_class) | SY-36 | a peer whose errors all state one failure class, whatever the failure |
46//! | [`nothing_waiting_means_the_next_pull_is_empty`](rules::nothing_waiting_means_the_next_pull_is_empty) | SY-37 | a peer that says nothing is waiting when its page ran out, not its log |
47//! | [`ack_never_confirms_a_non_durable_event`](rules::ack_never_confirms_a_non_durable_event) | SY-31 | a peer that confirms an event before it is durable |
48//! | [`round_trip_preserves_the_whole_log`](rules::round_trip_preserves_the_whole_log) | SY-28, SY-27 | a peer that withholds from its counterpart the events a type or tag filter matches, among those the rule's log carries |
49//! | [`retention_gap_is_reported_not_silent`](rules::retention_gap_is_reported_not_silent) | SY-32 | a peer that compacts and answers a token below its floor, or the start, with a strict subset in silence, or refuses it as anything but `Reseed`; skipped unless the fixture declares [`COMPACTION`](SyncFixture::COMPACTION) |
50//!
51//! Each rule names a wrong implementation, and that implementation lives in
52//! this crate's `tests/wrong_peers.rs` — SY-18's in `tests/wrong_limits.rs`,
53//! over [`KvCappedFixture`], its batch rule's in `tests/wrong_peers.rs`,
54//! SY-23's in `tests/wrong_orders.rs`, SY-28's in `tests/wrong_scopes.rs`,
55//! SY-31's across a reopen in `tests/wrong_reopens.rs`, and SY-32's in
56//! `tests/wrong_retention.rs` — where the rule is shown to fail it. A rule no
57//! peer can fail is decorative. The mount also emits
58//! `every_declined_capability_is_stated_by_this_fixture`, which fails a
59//! fixture that leaves [`REOPEN`](SyncFixture::REOPEN) at this crate's default
60//! declension ([`sync_declensions_are_stated`]).
61//!
62//! **No peer or ingest rule decodes a payload** (SY-35), and **no rule in
63//! [`rules`] holds two peers** (SY-8). [`rules`] says how the rules keep both. The model family
64//! below is the one exception to the second, and its module says why.
65//!
66//! # The model family
67//!
68//! Behind the off-by-default `proptest` feature, and absent on wasm32 because
69//! `proptest` does not build there. `sync_model` generates peer topologies of
70//! three to six peers — chains whose ends never meet included — and drives them
71//! from one seed through writes, partitions, lost acks, duplicated pushes and
72//! delayed pages, then checks every peer at quiescence against a model of its
73//! own. It opens **one fixture per node**, so the fixture expression must build
74//! a fresh, isolated peer each time it is evaluated.
75//!
76//! | Rule | Clause | What it rejects |
77//! |---|---|---|
78//! | `transitive_convergence_over_a_partial_mesh` | SY-24, SY-4 | a peer that quarantines what it accepted, or never forwards it |
79//! | `redelivery_of_an_accepted_group_is_a_no_op` | SY-11 | a peer that dedupes per batch (SF-03), or miscounts its acknowledgement |
80//! | `forwarding_order_is_arrival_order` | SY-25 | a peer that re-sorts what it forwards |
81//!
82//! The names are written out rather than linked, because the module they live
83//! in does not exist without the feature. A failure names its seed in hex and
84//! the smallest scenario it shrank to; `tests/wrong_topologies.rs` pins every
85//! rule's verdict against four wrong peers.
86//!
87//! ```
88//! # macro_rules! ignore { ($($t:tt)*) => {} }
89//! # ignore! {
90//! #[cfg(not(target_arch = "wasm32"))]
91//! happenstance_sync_testkit::sync_model_conformance!(
92//! happenstance_sync_testkit::MemorySyncFixture::new()
93//! );
94//! # }
95//! ```
96//!
97//! # The ingest family
98//!
99//! The other side of a peer: the store an
100//! [`IngestStore`](happenstance_sync::IngestStore) writes into. A store adapter
101//! that implements the port mounts it beside the event-store suite:
102//!
103//! ```
104//! # macro_rules! ignore { ($($t:tt)*) => {} }
105//! # ignore! {
106//! happenstance_sync_testkit::ingest_store_conformance!(
107//! happenstance_sync_testkit::MemoryIngestFixture::new()
108//! );
109//! # }
110//! ```
111//!
112//! The expression builds an [`IngestFixture`], whose store is both an
113//! `EventStore` and an `IngestStore`. The reference is
114//! [`MemoryIngestFixture`], over `happenstance-sync`'s `MemoryIngestStore`;
115//! `happenstance-sqlite`'s spike and the Durable Object mount the family too.
116//!
117//! | Rule | Clause | What it rejects |
118//! |---|---|---|
119//! | [`ingest_preserves_origin_identity`](ingest_rules::ingest_preserves_origin_identity) | VT-5 | a store that re-mints an ingested event |
120//! | [`ingest_preserves_the_recorded_time`](ingest_rules::ingest_preserves_the_recorded_time) | VT-9 | a store that restamps an ingested event with its arrival time, keeps whole seconds, holds a time before 1970 as the epoch, holds times non-decreasing with position, binds one time per group, or clamps a future time to its own clock |
121//! | [`ingested_events_land_above_the_local_head`](ingest_rules::ingested_events_land_above_the_local_head) | SY-5 | an order-preserving merge, which hides an event below a checkpoint already read past |
122//! | [`dedupe_reaches_identity_without_decoding`](ingest_rules::dedupe_reaches_identity_without_decoding) | SY-12, SY-11, SY-3 | content-keyed dedupe, and a compensation written again on redelivery |
123//! | [`an_unheld_own_identity_stops_the_ingest`](ingest_rules::an_unheld_own_identity_stops_the_ingest) | SY-38 | a dropped claim, a check of the batch's head only, a group-by-group commit, a claim hidden by the call's own compensation, and a refused held echo |
124//! | [`ingest_group_is_atomic_under_a_mid_group_fault`](ingest_rules::ingest_group_is_atomic_under_a_mid_group_fault) | SY-30 | a group written in chunks without a transaction, a compensation committed apart, a fault answered `Ok`, and an armed fault that never fires |
125//! | [`ingest_validates_every_event_not_the_head`](ingest_rules::ingest_validates_every_event_not_the_head) | SY-18 | per-event ceilings checked on each group's head only, a compensation never checked, and a ceiling off by one |
126//! | [`ingest_holds_the_call_to_its_tags_per_batch_ceiling`](ingest_rules::ingest_holds_the_call_to_its_tags_per_batch_ceiling) | VT-36, SY-18 | a tags-per-batch ceiling held to each group apart, a compensation left out of the total, a ceiling off by one, and a total refused as per-event, `Park` rather than `Split` |
127//! | [`only_the_adjudicator_compensates`](ingest_rules::only_the_adjudicator_compensates) | SY-7 | a compensation minted under an incarnation the store never read, so its log names an author nobody assigned |
128//! | [`directional_merge_rules_compose`](ingest_rules::directional_merge_rules_compose) | SY-10 | a store with the merge rule built in, which answers a group whose travelling guard its log breaks with a reversal of its own, and so judges, as a spoke, what the hub sends; and one that re-mints its own claim when a peer's claim on the seat arrives |
129//! | [`bulk_ingest_is_idempotent_in_bounded_round_trips`](ingest_rules::bulk_ingest_is_idempotent_in_bounded_round_trips) | SY-14, VT-24 | a store that consults what it holds for the first 64 events of a call only and writes a held event past them again, and one that refuses a call of VT-24's 128 events as over its batch limit |
130//!
131//! Each wrong store lives in `tests/wrong_ingest_stores.rs`, where a test runs
132//! the whole family against it and asserts it fails exactly its rule.
133//!
134//! SY-7's rule opens **two** stores, so a fixture must give each store it
135//! opens a fresh incarnation, and the rule fails one that does not. It plays
136//! the runner above them and holds the adjudicator assignment itself,
137//! mounting `happenstance-sync`'s shipped `runner::Adjudicate` hook: a seat
138//! rule on the adjudicator and `runner::Accept` on the other (#450). What it
139//! holds the store to is the identity a compensation is filed under; that the
140//! shipped runner writes none under `Accept` is `happenstance-sync`'s own
141//! tests'. Every peer adjudicating, the configuration SY-7 forbids, is run by
142//! the clause's falsification test in this crate's own unit tests, which
143//! records the two compensations it leaves for one conflict.
144//!
145//! SY-10's rule opens two stores for each of its two walks, hub and spoke and
146//! peer to peer, under the same requirement. It plays a runner that mounts one
147//! merge rule per direction of the edge through the same hook: the hub
148//! adjudicates what the spoke pushes, and the spoke takes what the hub sends
149//! unjudged. What it holds the store to is writing what each direction hands
150//! it and nothing of its own. The hub's rule run on the spoke as well is the
151//! clause's falsification test, in this crate's unit tests, and the shipped
152//! `runner::Edge` is held to its half in `happenstance-sync`'s own tests,
153//! against wrong runners that each mount a rule where they should not. SY-33's
154//! rule, which must exempt SY-38's refusal (ADR-0098), is not written yet; the
155//! exemption is carried forward to it.
156//!
157//! ## Capabilities
158//!
159//! Three rules need the fixture's co-operation, and say so rather than pass
160//! when they do not get it. SY-30's needs
161//! [`MID_GROUP_FAULT`](IngestFixture::MID_GROUP_FAULT) and
162//! [`arm_mid_group_fault`](IngestFixture::arm_mid_group_fault), because only
163//! the adapter can fail its own write between two rows. SY-18's reads
164//! [`MAX_EVENT_DATA_LEN`](IngestFixture::MAX_EVENT_DATA_LEN),
165//! [`MAX_TAGS_PER_EVENT`](IngestFixture::MAX_TAGS_PER_EVENT) and
166//! [`MAX_METADATA_LEN`](IngestFixture::MAX_METADATA_LEN), each mirrored from
167//! the adapter's own constant. VT-36's reads
168//! [`MAX_TAGS_PER_BATCH`](IngestFixture::MAX_TAGS_PER_BATCH), mirrored the
169//! same way; only a store whose call has a tags wall of its own states one,
170//! today `happenstance-cloudflare`'s. [`MemoryIngestFixture`] declines the fault in its own words and declares
171//! no ceiling, so it reports all three rules skipped; the faithful store in
172//! `tests/wrong_ingest_stores.rs` runs them, and `happenstance-sqlite`'s
173//! ingest spike runs the first two. The mount also emits
174//! `every_declined_capability_is_stated_by_this_fixture`, which fails a
175//! fixture whose declension is this crate's default
176//! ([`ingest_declensions_are_stated`]).
177//!
178//! # The write-group family
179//!
180//! A store that a runner or a [`StoreSyncPeer`](happenstance_sync::StoreSyncPeer)
181//! reads from must hand its log back in the writes that made it (SY-39), so a
182//! relay forwards each write as one group with its guard (SY-30). The family
183//! mounts on the same [`IngestFixture`], whose store must also implement
184//! [`WriteGroupStore`](happenstance_sync::WriteGroupStore):
185//!
186//! ```
187//! # macro_rules! ignore { ($($t:tt)*) => {} }
188//! # ignore! {
189//! happenstance_sync_testkit::write_group_store_conformance!(
190//! happenstance_sync_testkit::MemoryIngestFixture::new()
191//! );
192//! # }
193//! ```
194//!
195//! | Rule | Clause | What it rejects |
196//! |---|---|---|
197//! | [`an_append_reads_back_as_one_group`](write_group_rules::an_append_reads_back_as_one_group) | SY-39 | a store that records no groups, and one that merges adjacent appends |
198//! | [`an_ingested_group_keeps_its_boundary_and_guard`](write_group_rules::an_ingested_group_keeps_its_boundary_and_guard) | SY-39, SY-30 | a store that drops an ingested group's guard, or merges what one call ingested |
199//! | [`compensation_joins_its_group`](write_group_rules::compensation_joins_its_group) | SY-39, SY-2 | a store that records a compensation as a group of its own |
200//! | [`a_group_after_a_redelivery_is_named_by_its_first_landed_row`](write_group_rules::a_group_after_a_redelivery_is_named_by_its_first_landed_row) | SY-39, SY-11 | a store that names a group by the first position it allocated, not the first row it wrote |
201//! | [`a_read_never_cuts_a_group`](write_group_rules::a_read_never_cuts_a_group) | SY-39 | a page filled by event, a first group skipped for being too large, and a resume above a row position |
202//! | [`pages_chain_on_first_and_end_with_nothing`](write_group_rules::pages_chain_on_first_and_end_with_nothing) | SY-39, SY-37 | a page its budget cut that says nothing is waiting |
203//!
204//! Each wrong store lives in `tests/wrong_write_group_stores.rs`, where a test
205//! runs the whole family against it and asserts the exact set it fails.
206//!
207//! # The convergence family
208//!
209//! Not an adapter's bar but a projection's: a fold that declares itself
210//! convergent, by implementing
211//! [`ConvergentProjection`](happenstance::ConvergentProjection), is run under
212//! two interleavings of one set of events from two origins, and its read
213//! models must be byte-identical; and run over one arrival order numbered
214//! twice, densely and offset with gaps, and its read models must again be
215//! byte-identical. The rules are called directly over a
216//! [`ConvergenceFixture`]; there is no mounting macro, because there is no
217//! adapter to mount them beside and no capability to decline.
218//!
219//! | Rule | Clause | What it rejects |
220//! |---|---|---|
221//! | [`convergent_projection_is_interleaving_independent`](convergence_rules::convergent_projection_is_interleaving_independent) | SY-20 | `unit-ledger`, and any declared fold whose answer depends on arrival order |
222//! | [`convergent_projection_cannot_observe_local_position`](convergence_rules::convergent_projection_cannot_observe_local_position) | SY-21 | a declared fold that writes its checkpoint, a local position, into its read model |
223//! | [`non_convergent_projections_are_excluded_not_failed`](convergence_rules::non_convergent_projections_are_excluded_not_failed) | SY-22 | a check with no exclusion, which fails FIFO cost layers, and a check that does not really reorder |
224//!
225//! A payload is decoded here, and only by the projection under test: a fold
226//! reads its events, which is what makes it a fold. The check itself reads no
227//! event at all: it compares the bytes of two read models. What the runner
228//! reads to select and route events is their type and the projection's scope
229//! tags, which is what SY-35 requires. The wrong projections live in
230//! `tests/wrong_projections.rs`.
231//! [`StockOnHandFixture`] and [`CostLayersFixture`] are the reference cases:
232//! one domain, a sum that converges and a FIFO queue that cannot.
233//!
234//! # The restore family
235//!
236//! VT-6's restore half: a peer whose store is restored from a backup must not
237//! hand back an identity it already issued to a different event. Mounted on a
238//! [`RestoreFixture`], which supplies what no peer port has, a writer of the
239//! store's own events, a backup and a restore, and runs the adapter's
240//! documented post-restore procedure (VT-6's re-mint) as part of the restore:
241//!
242//! ```
243//! # macro_rules! ignore { ($($t:tt)*) => {} }
244//! # ignore! {
245//! happenstance_sync_testkit::restore_conformance!(
246//! happenstance_sync_testkit::MemoryRestoreFixture::new()
247//! );
248//! # }
249//! ```
250//!
251//! | Rule | Clause | What it rejects |
252//! |---|---|---|
253//! | [`restored_peer_does_not_reissue_identities`](restore_rules::restored_peer_does_not_reissue_identities) | VT-6 | a store whose identity survives a restore, so a new event takes an identity a lost one was issued; a restore that restores nothing; and a store that stamps its current incarnation on what it reads back, so a re-mint rewrites restored history |
254//!
255//! A family of its own rather than a capability on [`SyncFixture`]: a peer
256//! that issues no identity of its own, as `MemorySyncPeer` does not, has
257//! nothing a restore could reissue, and every rule of the peer family is held
258//! against peers built on it. [`MemoryRestoreFixture`], a store peer over the
259//! in-memory oracle that restores into a fresh incarnation, is the reference;
260//! the wrong peers live in `tests/wrong_restores.rs`, and
261//! `happenstance-postgres` mounts the family with its re-mint and runs the
262//! same sequence without it as its negative control.
263//!
264//! # The watermark family
265//!
266//! A projection store's bar, not a peer's: the store a runner keeps its
267//! per-peer confirmation watermark in, beside the read model whose rows
268//! depend on it (SY-31). The rule takes the
269//! [`ProjectionFixture`](happenstance_testkit::ProjectionFixture) a projection
270//! adapter already mounts the projection suite with, and is called directly,
271//! as the convergence family's are:
272//!
273//! ```
274//! # macro_rules! ignore { ($($t:tt)*) => {} }
275//! # ignore! {
276//! #[tokio::test]
277//! async fn watermark_advances_transactionally_with_a_read_model()
278//! -> Result<(), happenstance_sync_testkit::Violation> {
279//! happenstance_sync_testkit::watermark_rules::watermark_advances_transactionally_with_a_read_model(
280//! async || happenstance_testkit::fixtures::MemoryProjectionFixture::new(),
281//! )
282//! .await?
283//! .report("watermark_advances_transactionally_with_a_read_model");
284//! Ok(())
285//! }
286//! # }
287//! ```
288//!
289//! | Rule | Clause | What it rejects |
290//! |---|---|---|
291//! | [`watermark_advances_transactionally_with_a_read_model`](watermark_rules::watermark_advances_transactionally_with_a_read_model) | SY-31 | a store that refuses the reserved `sync/` prefix, keeps a watermark in its handle, keys every peer's watermark alike, or upserts one around the port's regression check |
292//!
293//! The rule plays the runner, with the shipped
294//! [`Edge`](happenstance_sync::runner::Edge) and its
295//! [`Watermark`](happenstance_sync::runner::Watermark), so what it holds the
296//! store to is what that runner asks of it. The wrong stores live in
297//! `tests/wrong_watermark_stores.rs`.
298//!
299//! # Harnesses
300//!
301//! The emitter is a parameter, as in the event-store family, so the suite never
302//! decides which runtime a peer is tested on:
303//! [`emit_sync_tokio!`](crate::emit_sync_tokio) (the default),
304//! [`emit_sync_blocking!`](crate::emit_sync_blocking) — no runtime and no
305//! `Send` bound, which is what a `!Send` peer runs under — and
306//! [`emit_sync_wasm!`](crate::emit_sync_wasm). The ingest family has
307//! [`emit_ingest_tokio!`](crate::emit_ingest_tokio) (the default),
308//! [`emit_ingest_blocking!`](crate::emit_ingest_blocking) and
309//! [`emit_ingest_wasm!`](crate::emit_ingest_wasm), the Durable Object's. The
310//! write-group family has
311//! [`emit_write_group_tokio!`](crate::emit_write_group_tokio) (the default),
312//! [`emit_write_group_blocking!`](crate::emit_write_group_blocking) and
313//! [`emit_write_group_wasm!`](crate::emit_write_group_wasm). The restore
314//! family has [`emit_restore_tokio!`](crate::emit_restore_tokio) (the default)
315//! and [`emit_restore_blocking!`](crate::emit_restore_blocking).
316//!
317//! # Failure is a value
318//!
319//! A rule returns `Result<RuleOutcome, Violation>` and an emitted test returns
320//! `Result<(), Violation>`, so a breach reaches the test runner as an error
321//! naming its clause. [`Violation`] says why this family does not panic as the
322//! other two do.
323//!
324//! # Features
325//!
326//! * **`proptest`**, off by default: the model family above. Absent on wasm32
327//! whatever the feature says, because `proptest` does not build there.
328
329#![cfg_attr(docsrs, feature(doc_cfg))]
330#![cfg_attr(doctest, doc = include_str!("../README.md"))]
331
332extern crate alloc;
333
334mod fixture;
335mod kv_capped;
336// `sync_suite.rs` and not `suite.rs`: the specification cites the event-store
337// family's file by bare name, and `cargo xtask spec-trace` refuses a bare name
338// two files answer to.
339mod sync_suite;
340mod violation;
341// Declared after the existing modules so their line numbers do not move. The
342// gate is `happenstance-testkit`'s `model`'s: `proptest` does not build for
343// wasm32, and a Cargo feature is not target-scoped.
344#[cfg(all(feature = "proptest", not(target_arch = "wasm32")))]
345#[cfg_attr(docsrs, doc(cfg(feature = "proptest")))]
346pub mod sync_model;
347
348pub use fixture::{
349 MAX_PROVOKED_BATCH_BYTES, MAX_PROVOKED_BATCH_EVENTS, MemorySyncFixture, MemorySyncHandle,
350 Refusal, RefusalsOf, SyncFixture, UNSTATED_COMPACTION, UNSTATED_SYNC_REOPEN,
351 batch_over_the_limit, oversized_push_refusal, sync_declensions_are_stated,
352};
353pub use kv_capped::{KV_VALUE_CAP, KvCappedFixture, KvCappedPeer, KvPeerError};
354pub use sync_suite::{
355 BYTE_LOG_REFUSED_REASON, COUNT_LOG_REFUSED_REASON, LOG_REFUSED, NO_CONFIRMATION,
356 NO_CONFIRMATION_REASON, NO_SECOND_PAGE, NO_SECOND_PAGE_REASON, rules,
357};
358pub use violation::Violation;
359
360// The ingest family (#108), declared after the peer families so their lines
361// do not move.
362mod ingest_fixture;
363// `ingest_suite.rs` for `sync_suite.rs`'s reason: a bare name two files answer
364// to is one `cargo xtask spec-trace` refuses.
365mod ingest_suite;
366pub use ingest_fixture::{
367 IngestFixture, MemoryIngestFixture, MemoryIngestHandle, UNSTATED_MID_GROUP_FAULT,
368 ingest_declensions_are_stated,
369};
370pub use ingest_suite::{
371 MAX_PROVOKED_TAGS, MAX_PROVOKED_TAGS_PER_BATCH, NO_HIDDEN_CLAIM, NO_HIDDEN_CLAIM_REASON,
372 NO_PER_EVENT_LIMITS, NO_PER_EVENT_LIMITS_REASON, NO_TAGS_PER_BATCH_LIMIT,
373 NO_TAGS_PER_BATCH_LIMIT_REASON, ingest_rules,
374};
375
376// The write-group family (#420), declared after the ingest family for the
377// same reason, and mounted on its fixture.
378mod write_group_suite;
379pub use write_group_suite::write_group_rules;
380
381// The convergence family (#141), declared after the others so their lines do
382// not move. `convergence_suite.rs` and not `convergence.rs`: `happenstance`
383// has a `src/convergence.rs` and a `tests/convergence.rs`, and
384// `cargo xtask spec-trace` refuses a bare name two files answer to.
385mod convergence_fixture;
386mod convergence_suite;
387pub use convergence_fixture::{
388 ConvergenceFixture, CostLayers, CostLayersFixture, EventOf, Stock, StockOnHand,
389 StockOnHandFixture, StoreOf,
390};
391pub use convergence_suite::convergence_rules;
392
393// The restore family (#133), declared after the others so their lines do not
394// move. `restore_suite.rs` for `sync_suite.rs`'s reason.
395mod restore_fixture;
396mod restore_suite;
397pub use restore_fixture::{MemoryRestoreFixture, RestoreFixture};
398pub use restore_suite::restore_rules;
399
400// The watermark family (#143), declared after the others so their lines do
401// not move. `watermark_suite.rs` for `sync_suite.rs`'s reason.
402mod watermark_suite;
403pub use watermark_suite::watermark_rules;
404
405/// Generates the ingest conformance suite for a store adapter.
406///
407/// Takes an expression that produces an [`IngestFixture`]. The rule list is
408/// not written here; it comes from
409/// [`for_each_ingest_store_rule!`](crate::for_each_ingest_store_rule), which
410/// is the only place it is written at all.
411///
412/// # Examples
413///
414/// The default harness, `#[tokio::test]`:
415///
416/// ```
417/// # macro_rules! ignore { ($($t:tt)*) => {} }
418/// # ignore! {
419/// happenstance_sync_testkit::ingest_store_conformance!(
420/// happenstance_sync_testkit::MemoryIngestFixture::new()
421/// );
422/// # }
423/// ```
424///
425/// A different harness, and a module name of your own:
426///
427/// ```
428/// # macro_rules! ignore { ($($t:tt)*) => {} }
429/// # ignore! {
430/// happenstance_sync_testkit::ingest_store_conformance!(
431/// mod_name = blocking_ingest_conformance,
432/// emit = happenstance_sync_testkit::emit_ingest_blocking,
433/// fixture = super::MyFixture::new()
434/// );
435/// # }
436/// ```
437#[macro_export]
438macro_rules! ingest_store_conformance {
439 (mod_name = $mod_name:ident, emit = $emit:path, fixture = $fixture:expr) => {
440 mod $mod_name {
441 // Hoisted behind a function, as in the other families, so an
442 // emitter needs to know nothing about the fixture's type.
443 // Re-evaluated per call, so every arrangement gets its own fixture.
444 async fn __ingest_fixture() -> impl $crate::__private::IngestFixture {
445 $fixture
446 }
447
448 // CF-18's machine-checked half, emitted here rather than through
449 // `$emit` so a caller's emitter cannot drop it:
450 // `happenstance_testkit::event_store_conformance!`'s copy carries
451 // the argument, and the reason the `cfg_attr` pair stays inert on
452 // a native build.
453 #[cfg_attr(not(target_arch = "wasm32"), test)]
454 #[cfg_attr(target_arch = "wasm32", ::wasm_bindgen_test::wasm_bindgen_test)]
455 fn every_declined_capability_is_stated_by_this_fixture()
456 -> ::core::result::Result<(), $crate::Violation> {
457 $crate::ingest_declensions_are_stated(__ingest_fixture)
458 }
459
460 $crate::for_each_ingest_store_rule!($emit);
461 }
462 };
463 (mod_name = $mod_name:ident, fixture = $fixture:expr) => {
464 $crate::ingest_store_conformance!(
465 mod_name = $mod_name,
466 emit = $crate::emit_ingest_tokio,
467 fixture = $fixture
468 );
469 };
470 ($fixture:expr) => {
471 $crate::ingest_store_conformance!(
472 mod_name = ingest_conformance,
473 emit = $crate::emit_ingest_tokio,
474 fixture = $fixture
475 );
476 };
477}
478
479/// Generates the write-group conformance suite for a store adapter.
480///
481/// Takes an expression that produces an [`IngestFixture`] whose store also
482/// implements [`WriteGroupStore`](happenstance_sync::WriteGroupStore). The
483/// rule list comes from
484/// [`for_each_write_group_rule!`](crate::for_each_write_group_rule).
485///
486/// # Examples
487///
488/// ```
489/// # macro_rules! ignore { ($($t:tt)*) => {} }
490/// # ignore! {
491/// happenstance_sync_testkit::write_group_store_conformance!(
492/// happenstance_sync_testkit::MemoryIngestFixture::new()
493/// );
494/// # }
495/// ```
496///
497/// A different harness, and a module name of your own:
498///
499/// ```
500/// # macro_rules! ignore { ($($t:tt)*) => {} }
501/// # ignore! {
502/// happenstance_sync_testkit::write_group_store_conformance!(
503/// mod_name = blocking_write_group_conformance,
504/// emit = happenstance_sync_testkit::emit_write_group_blocking,
505/// fixture = super::MyFixture::new()
506/// );
507/// # }
508/// ```
509#[macro_export]
510macro_rules! write_group_store_conformance {
511 (mod_name = $mod_name:ident, emit = $emit:path, fixture = $fixture:expr) => {
512 mod $mod_name {
513 // Hoisted as in the ingest family; the opaque type names the one
514 // extra bound every rule here needs.
515 async fn __write_group_fixture()
516 -> impl $crate::__private::IngestFixture<Store: $crate::__private::WriteGroupStore>
517 {
518 $fixture
519 }
520
521 $crate::for_each_write_group_rule!($emit);
522 }
523 };
524 (mod_name = $mod_name:ident, fixture = $fixture:expr) => {
525 $crate::write_group_store_conformance!(
526 mod_name = $mod_name,
527 emit = $crate::emit_write_group_tokio,
528 fixture = $fixture
529 );
530 };
531 ($fixture:expr) => {
532 $crate::write_group_store_conformance!(
533 mod_name = write_group_conformance,
534 emit = $crate::emit_write_group_tokio,
535 fixture = $fixture
536 );
537 };
538}
539
540/// Generates the sync conformance suite for a peer adapter.
541///
542/// Takes an expression that produces a [`SyncFixture`]. The rule list is not
543/// written here; it comes from
544/// [`for_each_sync_peer_rule!`](crate::for_each_sync_peer_rule), which is the
545/// only place it is written at all.
546///
547/// # Examples
548///
549/// The default harness, `#[tokio::test]`:
550///
551/// ```
552/// # macro_rules! ignore { ($($t:tt)*) => {} }
553/// # ignore! {
554/// happenstance_sync_testkit::sync_peer_conformance!(
555/// happenstance_sync_testkit::MemorySyncFixture::new()
556/// );
557/// # }
558/// ```
559///
560/// A different harness, and a module name of your own so two mounts can share
561/// a file:
562///
563/// ```
564/// # macro_rules! ignore { ($($t:tt)*) => {} }
565/// # ignore! {
566/// happenstance_sync_testkit::sync_peer_conformance!(
567/// mod_name = blocking_sync_conformance,
568/// emit = happenstance_sync_testkit::emit_sync_blocking,
569/// fixture = super::MyFixture::new()
570/// );
571/// # }
572/// ```
573#[macro_export]
574macro_rules! sync_peer_conformance {
575 (mod_name = $mod_name:ident, emit = $emit:path, fixture = $fixture:expr) => {
576 mod $mod_name {
577 // Hoisted behind a function, as in the event-store family, so an
578 // emitter needs to know nothing about the fixture's type; `async`
579 // because a real fixture's construction is I/O. Re-evaluated per
580 // test, so every rule gets its own fixture.
581 async fn __conformance_fixture() -> impl $crate::__private::SyncFixture {
582 $fixture
583 }
584
585 // CF-18's machine-checked half, emitted here rather than through
586 // `$emit` so a caller's emitter cannot drop it, as the ingest
587 // family's is.
588 #[cfg_attr(not(target_arch = "wasm32"), test)]
589 #[cfg_attr(target_arch = "wasm32", ::wasm_bindgen_test::wasm_bindgen_test)]
590 fn every_declined_capability_is_stated_by_this_fixture()
591 -> ::core::result::Result<(), $crate::Violation> {
592 $crate::sync_declensions_are_stated(__conformance_fixture)
593 }
594
595 $crate::for_each_sync_peer_rule!($emit);
596 }
597 };
598 (mod_name = $mod_name:ident, fixture = $fixture:expr) => {
599 $crate::sync_peer_conformance!(
600 mod_name = $mod_name,
601 emit = $crate::emit_sync_tokio,
602 fixture = $fixture
603 );
604 };
605 ($fixture:expr) => {
606 $crate::sync_peer_conformance!(
607 mod_name = sync_conformance,
608 emit = $crate::emit_sync_tokio,
609 fixture = $fixture
610 );
611 };
612}
613
614/// Generates the restore conformance suite for a peer adapter.
615///
616/// Takes an expression that produces a [`RestoreFixture`]. The rule list comes
617/// from [`for_each_restore_rule!`](crate::for_each_restore_rule).
618///
619/// # Examples
620///
621/// The default harness, `#[tokio::test]`:
622///
623/// ```
624/// # macro_rules! ignore { ($($t:tt)*) => {} }
625/// # ignore! {
626/// happenstance_sync_testkit::restore_conformance!(
627/// happenstance_sync_testkit::MemoryRestoreFixture::new()
628/// );
629/// # }
630/// ```
631///
632/// A different harness, and a module name of your own:
633///
634/// ```
635/// # macro_rules! ignore { ($($t:tt)*) => {} }
636/// # ignore! {
637/// happenstance_sync_testkit::restore_conformance!(
638/// mod_name = blocking_restore_conformance,
639/// emit = happenstance_sync_testkit::emit_restore_blocking,
640/// fixture = super::MyFixture::new()
641/// );
642/// # }
643/// ```
644#[macro_export]
645macro_rules! restore_conformance {
646 (mod_name = $mod_name:ident, emit = $emit:path, fixture = $fixture:expr) => {
647 mod $mod_name {
648 // Hoisted as in the other families. Re-evaluated per rule, so
649 // every rule gets its own fixture.
650 async fn __restore_fixture() -> impl $crate::__private::RestoreFixture {
651 $fixture
652 }
653
654 $crate::for_each_restore_rule!($emit);
655 }
656 };
657 (mod_name = $mod_name:ident, fixture = $fixture:expr) => {
658 $crate::restore_conformance!(
659 mod_name = $mod_name,
660 emit = $crate::emit_restore_tokio,
661 fixture = $fixture
662 );
663 };
664 ($fixture:expr) => {
665 $crate::restore_conformance!(
666 mod_name = restore_conformance,
667 emit = $crate::emit_restore_tokio,
668 fixture = $fixture
669 );
670 };
671}
672
673/// What the macro expansions name, so a caller need not have this crate's
674/// dependencies in scope under any particular name. Not promised.
675#[doc(hidden)]
676pub mod __private {
677 pub use crate::fixture::SyncFixture;
678 pub use crate::ingest_fixture::IngestFixture;
679 pub use crate::ingest_suite::ingest_rules;
680 pub use crate::restore_fixture::RestoreFixture;
681 pub use crate::restore_suite::restore_rules;
682 #[cfg(all(feature = "proptest", not(target_arch = "wasm32")))]
683 pub use crate::sync_model::rules as model_rules;
684 pub use crate::sync_suite::rules;
685 pub use crate::write_group_suite::write_group_rules;
686 pub use happenstance_sync::WriteGroupStore;
687 pub use happenstance_testkit::block_on;
688}