happenstance_sync_testkit/sync_suite.rs
1//! The sync rules, their one enumeration, and the three emitters.
2//!
3//! Private: what a caller reaches is [`rules`], re-exported at the crate root,
4//! and the macros, which `#[macro_export]` puts there regardless.
5
6/// The `capability` SY-37's rule reports when the peer never showed it a
7/// second page: the two declared limits that decide how much one pull carries.
8///
9/// Not a fixture constant, which is why it is spelled with its path: the
10/// limits are the peer's own declaration, and they are what an adapter author
11/// changes (or a fixture narrows) to let the rule see a page boundary.
12pub const NO_SECOND_PAGE: &str = "PeerLimits::max_batch_events, PeerLimits::max_batch_bytes";
13
14/// The reason SY-37's rule reports when the peer never showed it a second page.
15///
16/// Written by this crate rather than by the fixture, as
17/// `happenstance_testkit::NO_CEILING_REASON` is, because it is the same
18/// sentence for every peer that earns it. What the skip leaves unverified is
19/// the whole of SY-37: the rule cannot fail a peer whose every answer fits in
20/// one pull.
21///
22/// A peer that refused one of the rule's logs earns [`LOG_REFUSED`] instead,
23/// because the fix is the opposite one: not narrower limits, but a push that
24/// honours the limits already declared.
25pub const NO_SECOND_PAGE_REASON: &str = "this peer showed no page boundary: one pull carried everything the rule \
26 wrote, so a `Nothing` answered at a boundary could not be checked; narrow \
27 the declared batch limits to let the rule see a page. SY-37 is unverified \
28 for this peer";
29
30/// The `capability` SY-37's rule reports when the peer showed no page boundary
31/// and refused a push of one of its logs that its own declaration admits.
32///
33/// Distinct from [`NO_SECOND_PAGE`] because the two need opposite fixes: that
34/// one asks for smaller limits, this one for a peer that takes what its limits
35/// already say it takes. Which log was refused is in the reason:
36/// [`COUNT_LOG_REFUSED_REASON`] or [`BYTE_LOG_REFUSED_REASON`].
37pub const LOG_REFUSED: &str = "SyncPeer::push, within the peer's own PeerLimits";
38
39/// The reason SY-37's rule reports when the peer refused its count-cut log.
40///
41/// That log pushes at most [`PeerLimits::max_batch_events`] events of at most
42/// three payload bytes to a push, so a refusal is the peer stating batch
43/// limits it does not impose. **SY-18's batch rule judges that:**
44/// [`peer_takes_a_batch_at_its_declared_limits`] pushes `max_batch_events`
45/// events at once, at least as many as any push of this log carries, since
46/// [`MAX_PROVOKED_BATCH_EVENTS`] is above the log's 257, and fails a peer that
47/// refuses them. This skip names the refusal for SY-37's own sake, and only
48/// when the byte-cut log did not page: a byte-cut log that paged makes the
49/// rule [`RuleOutcome::Ran`]. When both logs are refused this is the reason
50/// given, because a refused byte-cut log fails `peer_declares_its_own_limits`
51/// as well.
52///
53/// [`RuleOutcome::Ran`]: happenstance_testkit::RuleOutcome::Ran
54/// [`peer_takes_a_batch_at_its_declared_limits`]: rules::peer_takes_a_batch_at_its_declared_limits
55/// [`MAX_PROVOKED_BATCH_EVENTS`]: crate::MAX_PROVOKED_BATCH_EVENTS
56///
57/// [`PeerLimits::max_batch_events`]: happenstance_sync::PeerLimits::max_batch_events
58pub const COUNT_LOG_REFUSED_REASON: &str = "this peer refused a push of the count-cut log, whose pushes carry at \
59 most `max_batch_events` events of at most three bytes each: its declared \
60 batch limits are not the limits it imposes, which SY-18's \
61 `peer_takes_a_batch_at_its_declared_limits` judges, and the log showed no \
62 page; SY-37 is unverified for this peer";
63
64/// The reason SY-37's rule reports when the peer refused its byte-cut log, and
65/// the count-cut log showed no page.
66///
67/// That log pushes one event to a push, its payload
68/// [`PeerLimits::max_event_bytes`] capped by `max_batch_bytes`: no larger than
69/// the boundary event `peer_declares_its_own_limits` pushes alone. So a
70/// refusal is the peer taking smaller events than it declares, SY-18's
71/// subject, and a peer that refuses it on size fails that rule too. Because
72/// each push holds one event, a peer that overstates only `max_batch_bytes`
73/// takes the log and pages it, which no rule could otherwise judge.
74///
75/// [`PeerLimits::max_event_bytes`]: happenstance_sync::PeerLimits::max_event_bytes
76pub const BYTE_LOG_REFUSED_REASON: &str = "this peer refused a one-event push of the byte-cut log, whose events are \
77 sized from its declared `max_event_bytes`: it takes smaller events than \
78 it declares (SY-18's subject, judged by its rule), and the count-cut log \
79 showed no page; SY-37 is unverified for this peer";
80
81/// The `capability` SY-31's rule reports when the peer's
82/// acknowledgement confirmed none of what the rule pushed.
83///
84/// Not a fixture constant, as [`NO_SECOND_PAGE`] is not: it names the field
85/// whose value left the rule nothing to check.
86pub const NO_CONFIRMATION: &str = "Ack::confirmed";
87
88/// The reason SY-31's rule reports when the peer confirmed none of what it
89/// pushed.
90///
91/// Written by this crate rather than by the fixture, because it is the same
92/// sentence for every peer that earns it. Confirming nothing is safe, since a
93/// spoke re-pushes and a re-delivery is a no-op, but it leaves the rule no
94/// confirmation to hold to the log.
95pub const NO_CONFIRMATION_REASON: &str = "this peer acknowledged the rule's push and confirmed none of the events \
96 in it, so no confirmation could be held to what a fresh handle reads \
97 back; confirming nothing is safe, because a spoke re-pushes and a \
98 re-delivery is a no-op, but SY-31's durability half is unverified for \
99 this peer";
100
101/// The sync rules. See the [crate documentation](crate) for what each covers.
102///
103/// Each rule is an async function taking `impl AsyncFn() -> F` — not a fixture
104/// but how to make one, as in the event-store family — and returning
105/// `Result<RuleOutcome, Violation>`.
106///
107/// # What no rule here does
108///
109/// **Decode a payload** (SY-35). Events are compared whole — identity, recorded
110/// time and the opaque bytes — and never parsed. A suite that parsed `data`
111/// would certify a peer that does, and ADR-0003's guarantee is that no peer
112/// needs to.
113///
114/// **Hold two peers** (SY-8). Where a clause speaks of two peers, the rule plays
115/// one of them itself: it is the side that pushes and pulls, and the fixture's
116/// peer is the far side.
117pub mod rules {
118 use alloc::collections::BTreeMap;
119 use alloc::format;
120 use alloc::string::String;
121 use alloc::vec;
122 use alloc::vec::Vec;
123
124 use happenstance_core::{
125 AppendCondition, Event, EventId, EventType, MAX_EVENT_TYPE_LEN, MAX_TAG_LEN,
126 MIN_SUPPORTED_EVENT_DATA_LEN, MIN_SUPPORTED_TAGS_PER_EVENT, Query, QueryItem, RecordedAt,
127 SequencePosition, StoreId, Tag, Tags,
128 };
129 use happenstance_sync::{
130 Ack, Classify, EventGroup, PeerLimits, PushBatch, ReplicatedEvent, SyncPeer, Waiting,
131 };
132 use happenstance_testkit::{Reopened, RuleOutcome};
133
134 use crate::kv_capped::turnstile_seat_map;
135 use crate::violation::{Violation, ensure};
136 use crate::{MAX_PROVOKED_BATCH_BYTES, MAX_PROVOKED_BATCH_EVENTS, SyncFixture};
137
138 mod retention;
139 mod whole_log;
140
141 /// The most pulls a rule makes before it decides the peer will never say
142 /// it has caught up. Far above what two or three tiny groups need under the
143 /// minimum conformant limits; its job is to turn a peer that loops into a
144 /// failure rather than a hang (H-13).
145 const MAX_PULLS: usize = 64;
146
147 /// The most groups past one that SY-37's rule writes to a peer in one log,
148 /// whatever limits the peer declares (H-13). Twice the minimum conformant
149 /// `max_batch_events`, so the reference peer pages more than once.
150 const FILL_CAP: usize = 256;
151
152 const SEAT_CLAIMED: EventType = EventType::from_static("SeatClaimed");
153 const CLAIM_REVERSED: EventType = EventType::from_static("ClaimReversed");
154 const READING_TAKEN: EventType = EventType::from_static("ReadingTaken");
155
156 /// Two origins and an adjudicating hub, as raw store identities.
157 const ORIGIN_A: StoreId = StoreId::from_bytes([0x11; 16]);
158 const ORIGIN_B: StoreId = StoreId::from_bytes([0x22; 16]);
159 const HUB: StoreId = StoreId::from_bytes([0x33; 16]);
160
161 /// SY-18's three origins: the one that committed the seat map, and the two
162 /// whose events sit at the declared boundary, in data and in metadata.
163 const SEAT_MAP_ORIGIN: StoreId = StoreId::from_bytes([0x44; 16]);
164 const BOUNDARY_ORIGIN: StoreId = StoreId::from_bytes([0x55; 16]);
165 const METADATA_ORIGIN: StoreId = StoreId::from_bytes([0x66; 16]);
166
167 /// SY-31's two origins, whose events the rule pushes in one batch.
168 const DURABLE_ORIGIN: StoreId = StoreId::from_bytes([0x81; 16]);
169 const DURABLE_TWIN: StoreId = StoreId::from_bytes([0x82; 16]);
170
171 /// SY-23's three origins, in `EventId` order: the derive sorts a
172 /// [`StoreId`] by its bytes.
173 const ORDER_LOW: StoreId = StoreId::from_bytes([0xA1; 16]);
174 const ORDER_MID: StoreId = StoreId::from_bytes([0xA2; 16]);
175 const ORDER_HIGH: StoreId = StoreId::from_bytes([0xA3; 16]);
176
177 /// The type of every event SY-18's batch rule pushes.
178 const BATCH_FILLED: EventType = EventType::from_static("BatchFilled");
179
180 /// SY-18's batch rule's two origins: the push at the declared event count
181 /// with empty payloads, and the push at that count and the declared bytes.
182 const COUNT_CORNER_ORIGIN: StoreId = StoreId::from_bytes([0x91; 16]);
183 const BYTE_CORNER_ORIGIN: StoreId = StoreId::from_bytes([0x92; 16]);
184
185 /// SY-30's origin, whose three groups the envelope rule pushes in one batch.
186 const GROUPS_ORIGIN: StoreId = StoreId::from_bytes([0x93; 16]);
187 /// The type of every event SY-30's rule pushes.
188 const GROUP_WRITTEN: EventType = EventType::from_static("GroupWritten");
189 /// The types SY-30's two guards name. Nothing the suite writes carries
190 /// either, so a peer that evaluated the guards would find nothing to refuse
191 /// and only SY-1's rule judges that mistake.
192 const GUARDED_FIRST: EventType = EventType::from_static("GroupGuardedFirst");
193 const GUARDED_LAST: EventType = EventType::from_static("GroupGuardedLast");
194
195 /// SY-1: a peer appends every replicated event it does not already hold,
196 /// and never evaluates an append condition — the origin's or its own — as a
197 /// precondition.
198 ///
199 /// Two origins each claim the same seat under **byte-identical,
200 /// position-free** guards: each decision was valid where it was made, and
201 /// together they conflict. The rule pushes both, as the two origins would,
202 /// and then pulls the peer's whole log. Both claims must be there.
203 ///
204 /// # Rejects
205 ///
206 /// A peer that evaluates the travelling guard against what it holds and
207 /// refuses — or silently drops — the second claim. It is the natural first
208 /// cut, because the guard arrives on the wire already, and it produces a
209 /// peer set that never converges. `tests/wrong_peers.rs` carries both
210 /// spellings: one that acknowledges the dropped claim as nothing appended,
211 /// which the ack check catches, and one that acknowledges it as appended
212 /// and drops it anyway, which only the pull of the whole log can see.
213 ///
214 /// # Errors
215 ///
216 /// A [`Violation`] of SY-1 if the peer refuses either push, reports either
217 /// claim as anything but newly appended, or does not hand both back.
218 pub async fn ingest_never_rejects<F: SyncFixture>(
219 open: impl AsyncFn() -> F,
220 ) -> Result<RuleOutcome, Violation> {
221 const CLAUSE: &str = "SY-1";
222 let fixture = open().await;
223 let peer = fixture.connect().await;
224 let guard = seat_guard(CLAUSE)?;
225
226 let mine = claim(ORIGIN_A, CLAUSE)?;
227 let theirs = claim(ORIGIN_B, CLAUSE)?;
228 for event in [&mine, &theirs] {
229 let batch = PushBatch::new(vec![EventGroup::new(
230 Some(guard.clone()),
231 vec![event.clone()],
232 )]);
233 let ack = peer.push(&batch).await.map_err(|error| {
234 Violation::new(
235 CLAUSE,
236 format!(
237 "the peer refused a replicated claim from {}: {error}",
238 event.id
239 ),
240 )
241 })?;
242 ensure(ack.appended == 1 && ack.skipped == 0, CLAUSE, || {
243 format!(
244 "the peer acknowledged the claim from {} as {} appended and {} skipped; \
245 it held nothing with that identity, so it must append it",
246 event.id, ack.appended, ack.skipped
247 )
248 })?;
249 }
250
251 let held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
252 .await?
253 .into_iter()
254 .flat_map(|group| group.events)
255 .collect();
256 for expected in [&mine, &theirs] {
257 ensure(held.contains(expected), CLAUSE, || {
258 format!(
259 "the claim from {} is not in the peer's log, byte for byte; a conflicting \
260 claim already there is not a reason to drop it",
261 expected.id
262 )
263 })?;
264 }
265 Ok(RuleOutcome::Ran)
266 }
267
268 /// SY-2, the transport's half: a losing event and the compensation that
269 /// answers it travel as one group, and a peer hands them back as one group.
270 ///
271 /// A hub has adjudicated a conflict: one claim won, and the other is sent on
272 /// together with the reversal the hub wrote for it, in one
273 /// [`EventGroup`]. Whoever pulls that from this peer ingests a group at a
274 /// time, atomically (`IngestStore::ingest`), so a peer that splits the group
275 /// hands its reader a log where the losing claim stands with nothing
276 /// resolving it. The store-side half — one ingest commits the group whole —
277 /// rides on ES-18 and on the ingest suite.
278 ///
279 /// # Rejects
280 ///
281 /// A peer that flattens what it is pushed into one group per event, or
282 /// that pages by event count and ends a pull between the two.
283 /// `tests/wrong_peers.rs` carries both.
284 ///
285 /// # Does not reject
286 ///
287 /// **Compensate-after-commit**, the defect SY-2's own `Rejects` paragraph
288 /// names: ingest the losing event, return, and author the compensation
289 /// afterwards. That is the authoring side's mistake, made before anything
290 /// reaches a peer, and a rule that holds only a peer cannot see it — this
291 /// rule hands the peer a group that is already whole. The authoring half is
292 /// tracked by #320; until it lands, a green run here certifies the
293 /// transport and nothing upstream of it.
294 ///
295 /// # Errors
296 ///
297 /// A [`Violation`] of SY-2 if the peer refuses the pushes, or if the group
298 /// it hands back with the losing claim does not also hold its reversal.
299 pub async fn compensation_is_atomic_with_the_losing_event<F: SyncFixture>(
300 open: impl AsyncFn() -> F,
301 ) -> Result<RuleOutcome, Violation> {
302 const CLAUSE: &str = "SY-2";
303 let fixture = open().await;
304 let peer = fixture.connect().await;
305
306 let winner = claim(ORIGIN_A, CLAUSE)?;
307 let losing = claim(ORIGIN_B, CLAUSE)?;
308 let reversal = replicated(HUB, CLAIM_REVERSED, CLAUSE)?;
309 let batch = PushBatch::new(vec![
310 EventGroup::new(None, vec![winner]),
311 EventGroup::new(None, vec![losing.clone(), reversal.clone()]),
312 ]);
313 peer.push(&batch).await.map_err(|error| {
314 Violation::new(
315 CLAUSE,
316 format!("the peer refused a batch well inside the minimum limits: {error}"),
317 )
318 })?;
319
320 let groups = pull_everything(&peer, CLAUSE).await?;
321 let Some(carrying) = groups.iter().find(|group| group.events.contains(&losing)) else {
322 return Err(Violation::new(
323 CLAUSE,
324 format!("the losing claim {} never came back", losing.id),
325 ));
326 };
327 ensure(carrying.events.contains(&reversal), CLAUSE, || {
328 format!(
329 "the losing claim {} came back in a group without its reversal {}; a reader \
330 ingesting that group commits the claim with nothing resolving it",
331 losing.id, reversal.id
332 )
333 })?;
334 Ok(RuleOutcome::Ran)
335 }
336
337 /// SY-18: a peer declares the limits it imposes, synchronously, and the
338 /// declaration is true: an event it admits lands, so a runner that read it
339 /// learns of an event that cannot land *before* pushing, not at ingest.
340 ///
341 /// The rule plays that runner. It reads [`SyncPeer::limits`] before it
342 /// pushes anything, and then:
343 ///
344 /// 1. reads it again, because a declaration that changes between two reads
345 /// cannot be relied on before a push;
346 /// 2. holds `max_event_bytes` to VT-21's floor,
347 /// [`MIN_SUPPORTED_EVENT_DATA_LEN`]. Every peer the suite is mounted on
348 /// passes this line, which is where the floor is compared across the
349 /// peer set;
350 /// 3. runs the Turnstile experiment: a 340,000-byte seat map, already
351 /// committed at its origin. If the declaration admits it, it is pushed
352 /// and must land. If not, the runner parks it without a round trip,
353 /// which is the prevention, and nothing is pushed;
354 /// 4. pushes two events at the declaration's own boundary and at the
355 /// contract's envelope floors at once: `max_event_bytes` of opaque bytes
356 /// (capped by `max_batch_bytes`), carried once in data and once in
357 /// metadata, because the declaration bounds the two together; a type of
358 /// [`MAX_EVENT_TYPE_LEN`] bytes; and [`MIN_SUPPORTED_TAGS_PER_EVENT`]
359 /// tags of [`MAX_TAG_LEN`] bytes each. The declaration must admit each,
360 /// and each must land, acknowledged as appended. A limit on the envelope
361 /// or on metadata that the peer imposes without declaring it is a limit
362 /// discovered at ingest;
363 /// 5. pulls the whole log back: every event that landed is held, byte for
364 /// byte, which rejects a peer that accepts and truncates.
365 ///
366 /// The asynchronous form of the declaration, which SY-18 also rejects,
367 /// cannot be written: `limits` is not `async` on the port, so the compiler
368 /// is that check and no mutant is needed for it.
369 ///
370 /// A peer that declares more than [`MAX_PROVOKED_BATCH_BYTES`] has its
371 /// boundary tested at that ceiling rather than at its declaration, because
372 /// the event is allocated whole (H-13). The rule still runs.
373 ///
374 /// # Rejects
375 ///
376 /// `tests/wrong_limits.rs` carries eight mistakes over the KV-capped
377 /// reference peer, one for each check above:
378 ///
379 /// * declarations rewritten over unchanged behaviour: no value cap, which
380 /// admits the seat map that ingest then parks; the raw 131,072-byte value
381 /// cap, as if a value held the payload alone, which admits a boundary
382 /// event ingest refuses; a byte below VT-21's floor; a declaration that
383 /// changes between two reads; and `max_batch_events` of zero, which
384 /// admits no event at all;
385 /// * behaviour changed under an honest declaration: a cap of 1,024 bytes on
386 /// metadata, Workers KV's, that the declaration does not state; data
387 /// truncated on a large push and acknowledged as appended; and a large
388 /// event stored whole and acknowledged as skipped.
389 ///
390 /// # Does not reject
391 ///
392 /// A runner that ignores `limits()`. That is the runner's defect, and #244
393 /// owns it; a peer can only make its declaration true. Nor limits that go
394 /// stale between the read and the push: [`PeerLimits::admits`] is advisory,
395 /// and what keeps that survivable is the `Park` and `Split` classes SY-36
396 /// checks.
397 ///
398 /// Nor a lie about `max_batch_bytes` or `max_batch_events` alone. This rule
399 /// holds the limits a peer imposes on *an event*, and reads the batch
400 /// limits only to size the boundary event. A batch at them that is refused
401 /// is [`peer_takes_a_batch_at_its_declared_limits`]'s to judge, and a
402 /// batch over them is SY-36's `Split`, not a fact that can never land.
403 ///
404 /// [`PeerLimits::admits`]: happenstance_sync::PeerLimits::admits
405 ///
406 /// # Errors
407 ///
408 /// A [`Violation`] of SY-18 if the declaration changes between two reads,
409 /// declares below VT-21's floor, or admits no event at its own boundary;
410 /// or if an event the declaration admits is refused, acknowledged as
411 /// anything but one appended, or not handed back whole. The floor breach
412 /// cites VT-21 in its message.
413 pub async fn peer_declares_its_own_limits<F: SyncFixture>(
414 open: impl AsyncFn() -> F,
415 ) -> Result<RuleOutcome, Violation> {
416 const CLAUSE: &str = "SY-18";
417 let fixture = open().await;
418 let peer = fixture.connect().await;
419
420 let limits = peer.limits();
421 let again = peer.limits();
422 ensure(again == limits, CLAUSE, || {
423 format!(
424 "the peer declared {limits:?} and then {again:?}; a declaration that changes \
425 between two reads cannot be relied on before a push"
426 )
427 })?;
428 ensure(
429 limits.max_event_bytes >= MIN_SUPPORTED_EVENT_DATA_LEN,
430 CLAUSE,
431 || {
432 format!(
433 "the peer declares max_event_bytes of {}, below VT-21's floor of \
434 {MIN_SUPPORTED_EVENT_DATA_LEN}",
435 limits.max_event_bytes
436 )
437 },
438 )?;
439
440 let mut landed = Vec::new();
441 let seat_map = one_event(turnstile_seat_map(SEAT_MAP_ORIGIN, CLAUSE)?);
442 if limits.admits(&seat_map) {
443 push_admitted(&peer, &seat_map, "the 340,000-byte seat map", CLAUSE).await?;
444 landed.push(seat_map);
445 }
446
447 let size = limits
448 .max_event_bytes
449 .min(limits.max_batch_bytes)
450 .min(MAX_PROVOKED_BATCH_BYTES);
451 for carrier in [Carrier::Data, Carrier::Metadata] {
452 let boundary = one_event(event_at_the_envelope_floors(size, carrier, CLAUSE)?);
453 ensure(limits.admits(&boundary), CLAUSE, || {
454 format!(
455 "the declaration {limits:?} admits no event of {size} bytes in its \
456 {carrier:?}, the size it states it accepts"
457 )
458 })?;
459 push_admitted(&peer, &boundary, carrier.describe(), CLAUSE).await?;
460 landed.push(boundary);
461 }
462
463 let held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
464 .await?
465 .into_iter()
466 .flat_map(|group| group.events)
467 .collect();
468 for expected in landed.iter().flat_map(PushBatch::events) {
469 ensure(held.contains(expected), CLAUSE, || {
470 format!(
471 "event {} of {} bytes was acknowledged and is not in the peer's log, \
472 byte for byte",
473 expected.id,
474 expected.payload_len()
475 )
476 })?;
477 }
478 Ok(RuleOutcome::Ran)
479 }
480
481 /// SY-36: every error a peer reports states its failure class, and the
482 /// class is the one its adapter says it is.
483 ///
484 /// The fixture drives a fresh handle into every refusal it can produce and
485 /// declares each one's class ([`SyncFixture::refusals`]); the rule checks
486 /// that each provocation was refused, and that the error's
487 /// [`Classify::class`] answers what was declared. The class is read twice
488 /// from the same value, because SY-36 makes it a function of the error
489 /// alone.
490 ///
491 /// # Rejects
492 ///
493 /// A peer that reports every failure as one class — the opaque error
494 /// ADR-0026 rejected, with a trait impl bolted on so it compiles.
495 /// `tests/wrong_peers.rs` carries it, as `Transient` for everything, which
496 /// retries a batch that can only ever be split.
497 ///
498 /// The rule's other three refusals each have a mutant there too: a fixture
499 /// that declares no refusal, a peer that accepts the push its fixture says
500 /// it refuses, and an error whose class changes between two reads.
501 ///
502 /// # Errors
503 ///
504 /// A [`Violation`] of SY-36 if the fixture declares no refusal, if a
505 /// provocation succeeds, or if a refusal's class is not the declared one or
506 /// changes between two reads.
507 pub async fn every_refusal_states_its_class<F: SyncFixture>(
508 open: impl AsyncFn() -> F,
509 ) -> Result<RuleOutcome, Violation> {
510 const CLAUSE: &str = "SY-36";
511 let fixture = open().await;
512 let peer = fixture.connect().await;
513
514 let refusals = fixture.refusals(&peer).await?;
515 ensure(!refusals.is_empty(), CLAUSE, || {
516 String::from(
517 "the fixture declared no refusal; every peer can be refused something, and a \
518 rule checked against nothing has checked nothing",
519 )
520 })?;
521 for refusal in refusals {
522 let Err(error) = refusal.outcome else {
523 return Err(Violation::new(
524 CLAUSE,
525 format!(
526 "the peer accepted {}, which its fixture says it refuses",
527 refusal.provoked_by
528 ),
529 ));
530 };
531 let (first, second) = (error.class(), error.class());
532 ensure(first == second, CLAUSE, || {
533 format!(
534 "the refusal of {} answered {first:?} and then {second:?}; the class must \
535 be a function of the error alone",
536 refusal.provoked_by
537 )
538 })?;
539 ensure(first == refusal.declared, CLAUSE, || {
540 format!(
541 "the refusal of {} ({error}) states {first:?}, and its fixture declares \
542 {:?}",
543 refusal.provoked_by, refusal.declared
544 )
545 })?;
546 }
547 Ok(RuleOutcome::Ran)
548 }
549
550 /// SY-37: a peer that answers a pull with [`Waiting::Nothing`] hands back
551 /// an empty batch on the next pull from the token that answer carried.
552 ///
553 /// The rule writes two logs, each to a fresh peer from `open`:
554 ///
555 /// 1. **Cut by count**: 257 single-event groups of a few bytes, pushed at
556 /// most [`PeerLimits::max_batch_events`] to a push, so a peer that pages
557 /// at any event count up to 256 shows a page boundary.
558 /// 2. **Cut by bytes**: single-event groups whose payloads are sized from
559 /// the declared limits so [`PeerLimits::max_batch_bytes`] ends a page
560 /// before the event count does, one group past that page, pushed one
561 /// event to a push so the pull alone draws the boundary. Written only
562 /// where the bytes do cut first, and the log fits in 257 groups and
563 /// 64 MiB.
564 ///
565 /// On each it follows the peer's tokens from the start, and on the first
566 /// `Nothing` pulls once more from that token. That pull must be empty. A
567 /// peer that never says `Nothing` passes: it costs its runner the empty
568 /// pull, and never a missed event.
569 ///
570 /// A log the peer refuses to take is not built, and shows no page. Whose
571 /// failure the refusal is depends on the log. The byte-cut log goes one
572 /// event to a push, each sized from [`PeerLimits::max_event_bytes`] and no
573 /// larger than SY-18's boundary event, so refusing it is SY-18's subject,
574 /// and `peer_declares_its_own_limits` judges it; a peer that overstates
575 /// only `max_batch_bytes` takes it. The count-cut log is tiny events, at
576 /// most `max_batch_events` to a push, so refusing it is a lie about the
577 /// batch limits, which that rule says it does not judge and
578 /// [`peer_takes_a_batch_at_its_declared_limits`] judges.
579 ///
580 /// If neither log showed a second non-empty page, the rule could not have
581 /// failed the peer, and it reports a skip rather than a pass: naming
582 /// [`LOG_REFUSED`] if the peer refused a log, with
583 /// [`COUNT_LOG_REFUSED_REASON`] or [`BYTE_LOG_REFUSED_REASON`] saying which
584 /// (the count-cut one if both), and [`NO_SECOND_PAGE`] if it took every log
585 /// the rule wrote and one pull carried each. The two need opposite fixes: a
586 /// push that honours the declared limits, and narrower limits. One log that
587 /// paged is enough for the rule to have run, so a refusal of the other is
588 /// not reported over it.
589 ///
590 /// The bound on pulls — one more than the log has groups — is the suite's
591 /// liveness guard, not SY-37's claim: a peer that ignores its token and
592 /// keeps handing back groups is reported here, and fails SY-1's and SY-2's
593 /// rules too.
594 ///
595 /// [`NO_SECOND_PAGE`]: crate::NO_SECOND_PAGE
596 /// [`LOG_REFUSED`]: crate::LOG_REFUSED
597 /// [`COUNT_LOG_REFUSED_REASON`]: crate::COUNT_LOG_REFUSED_REASON
598 /// [`BYTE_LOG_REFUSED_REASON`]: crate::BYTE_LOG_REFUSED_REASON
599 ///
600 /// # Rejects
601 ///
602 /// A peer that says `Nothing` because its page ran out rather than its log
603 /// — the natural slip for an adapter that reports "this page is the last
604 /// one I fetched" — so a runner that believes it stops short and the rest
605 /// of the log waits for the next wake. `tests/wrong_peers.rs` carries two:
606 /// a peer that says `Nothing` on every pull, which the count-cut log
607 /// catches, and one that says it whenever a page carried fewer events than
608 /// `max_batch_events`, which only the byte-cut log can catch.
609 ///
610 /// # Does not reject
611 ///
612 /// A wrong [`Waiting::Events`] count: it is advisory, and checking it would
613 /// need a snapshot of the far side the port does not offer. Nor a peer
614 /// that says `Nothing` while stalled behind a group too large for any pull:
615 /// SY-37 forbids it, but a conformant push cannot put such a group on the
616 /// far side, so the rule cannot build the case. Nor a peer whose single
617 /// pull carries all of both logs, which it reports as a skip; the caps
618 /// bound the work against a peer that declares huge limits (H-13), at that
619 /// price.
620 ///
621 /// # Errors
622 ///
623 /// A [`Violation`] of SY-37 if the peer refuses a pull, keeps handing back
624 /// groups past the log the rule wrote, or hands back events on the pull
625 /// after it said nothing was waiting.
626 pub async fn nothing_waiting_means_the_next_pull_is_empty<F: SyncFixture>(
627 open: impl AsyncFn() -> F,
628 ) -> Result<RuleOutcome, Violation> {
629 const CLAUSE: &str = "SY-37";
630
631 let by_count = {
632 let fixture = open().await;
633 let peer = fixture.connect().await;
634 write_log(&peer, Fill::cut_by_count(&peer.limits()), CLAUSE).await?
635 };
636
637 let fixture = open().await;
638 let peer = fixture.connect().await;
639 let by_bytes = match Fill::cut_by_bytes(&peer.limits()) {
640 Some(fill) => write_log(&peer, fill, CLAUSE).await?,
641 // Not written: the count cuts first, or the log would pass a cap.
642 None => Log::NoPage,
643 };
644
645 Ok(match (by_count, by_bytes) {
646 (Log::Paged, _) | (_, Log::Paged) => RuleOutcome::Ran,
647 // The count-cut refusal first: it is the batch-limit lie, which
648 // SY-18's batch rule judges, while its per-event rule reports the
649 // byte-cut one.
650 (Log::Refused, _) => RuleOutcome::Skipped {
651 capability: crate::LOG_REFUSED,
652 reason: crate::COUNT_LOG_REFUSED_REASON,
653 },
654 (Log::NoPage, Log::Refused) => RuleOutcome::Skipped {
655 capability: crate::LOG_REFUSED,
656 reason: crate::BYTE_LOG_REFUSED_REASON,
657 },
658 (Log::NoPage, Log::NoPage) => RuleOutcome::Skipped {
659 capability: crate::NO_SECOND_PAGE,
660 reason: crate::NO_SECOND_PAGE_REASON,
661 },
662 })
663 }
664
665 /// SY-31: an [`Ack`] confirms only what the far side still holds once the
666 /// handle that acknowledged is gone.
667 ///
668 /// SY-31's confirmation watermark is advanced to [`Ack::confirmed`], "what
669 /// the far side has now durably seen", and SY-24's forwarding never offers
670 /// anything at or below it again. So a confirmation sent before the write
671 /// is durable loses that write for good: the spoke's watermark has passed
672 /// it, and nothing re-sends it.
673 ///
674 /// The rule pushes one batch of two groups from two origins, at origin
675 /// positions 3 and 7 and 2, drops the handle that pushed, reopens the
676 /// fixture when it can, connects a fresh handle onto it and pulls
677 /// everything. Then every pushed event at or below the confirmed mark for
678 /// its origin is held, byte for byte, and every confirmed mark names an
679 /// event the fresh handle holds. `confirmed` is read as a high-water mark,
680 /// never as everything up to: no position below a mark that the rule did
681 /// not push is assumed held.
682 ///
683 /// "Not durable" is observed as "gone once the acking handle is dropped",
684 /// and, when the fixture declares [`SyncFixture::REOPEN`], as "gone once
685 /// the fixture is reopened", the process crash CF-17 lets a fixture stage.
686 /// The reopen must answer [`Reopened::Discarded`]; a fixture that declares
687 /// the capability and keeps the provided `reopen` is a violation here. A
688 /// fixture that declines it is run as before, and a peer that buffers in
689 /// memory every handle shares, and would lose it to a crash, passes: that
690 /// is what the declension costs, and its reason is the fixture's to state.
691 ///
692 /// [`Reopened::Discarded`]: happenstance_testkit::Reopened::Discarded
693 ///
694 /// A peer whose ack confirms none of the pushed events has given the rule
695 /// nothing to check, so the rule reports
696 /// [`Skipped`](RuleOutcome::Skipped) with
697 /// [`NO_CONFIRMATION`](crate::NO_CONFIRMATION) rather than a pass.
698 ///
699 /// [`Ack`]: happenstance_sync::Ack
700 /// [`Ack::confirmed`]: happenstance_sync::Ack::confirmed
701 ///
702 /// # Rejects
703 ///
704 /// A write-behind cache that acknowledges a push on admission and commits
705 /// it later, so a handle dropped in between has confirmed what the peer
706 /// never held. `tests/wrong_peers.rs` carries it, and the peer that
707 /// confirms nothing, which this rule must skip. `tests/wrong_reopens.rs`
708 /// carries the same cache in memory every handle shares, which only a
709 /// reopen can show.
710 ///
711 /// # Errors
712 ///
713 /// A [`Violation`] of SY-31 if the peer refuses the push or a pull, if a
714 /// fixture declaring [`SyncFixture::REOPEN`] reopened nothing, if a
715 /// confirmed event is not held by a fresh handle, or if a confirmed mark
716 /// names no event the fresh handle holds.
717 pub async fn ack_never_confirms_a_non_durable_event<F: SyncFixture>(
718 open: impl AsyncFn() -> F,
719 ) -> Result<RuleOutcome, Violation> {
720 const CLAUSE: &str = "SY-31";
721 let fixture = open().await;
722 let first = durable_reading(DURABLE_ORIGIN, 3, b"sy31-p-3", CLAUSE)?;
723 let second = durable_reading(DURABLE_ORIGIN, 7, b"sy31-p-7", CLAUSE)?;
724 let other = durable_reading(DURABLE_TWIN, 2, b"sy31-q-2", CLAUSE)?;
725 let batch = PushBatch::new(vec![
726 EventGroup::new(None, vec![first, second]),
727 EventGroup::new(None, vec![other]),
728 ]);
729
730 let ack = {
731 let peer = fixture.connect().await;
732 peer.push(&batch).await.map_err(|error| {
733 Violation::new(
734 CLAUSE,
735 format!("the peer refused a batch well inside the minimum limits: {error}"),
736 )
737 })?
738 // The acking handle is dropped here: what it confirmed must
739 // outlive it.
740 };
741 if F::REOPEN.is_supported() {
742 ensure(
743 fixture.reopen().await == Reopened::Discarded,
744 CLAUSE,
745 || {
746 String::from(
747 "the fixture declares REOPEN supported and its reopen answered \
748 `Nothing`: `SyncFixture::reopen` is not overridden, or its override \
749 reopened nothing, so the crash this rule stages never happened",
750 )
751 },
752 )?;
753 }
754
755 let fresh = fixture.connect().await;
756 let held: Vec<ReplicatedEvent> = pull_everything(&fresh, CLAUSE)
757 .await?
758 .into_iter()
759 .flat_map(|group| group.events)
760 .collect();
761 let covered: Vec<&ReplicatedEvent> = batch
762 .events()
763 .filter(|event| {
764 ack.confirmed
765 .get(event.id.store())
766 .is_some_and(|confirmed| event.id.position() <= confirmed)
767 })
768 .collect();
769 if covered.is_empty() {
770 return Ok(RuleOutcome::Skipped {
771 capability: crate::NO_CONFIRMATION,
772 reason: crate::NO_CONFIRMATION_REASON,
773 });
774 }
775 for event in covered {
776 ensure(held.contains(event), CLAUSE, || {
777 format!(
778 "the peer confirmed {} and a fresh handle onto it does not hold it, byte for \
779 byte; a spoke's watermark passes it, so it is never pushed again",
780 event.id
781 )
782 })?;
783 }
784 // The high-water reading: each mark names a position the peer holds,
785 // and nothing is inferred about the positions below it.
786 for (origin, position) in ack.confirmed.iter() {
787 let id = EventId::new(origin, position);
788 ensure(held.iter().any(|event| event.id == id), CLAUSE, || {
789 format!(
790 "the peer confirmed {id} as the highest position it holds from {origin}, \
791 and a fresh handle onto it holds no event with that identity"
792 )
793 })?;
794 }
795 Ok(RuleOutcome::Ran)
796 }
797
798 /// SY-18: a peer's declared batch limits are the limits it imposes: a push
799 /// at the declared corner, which the declaration admits, lands whole.
800 ///
801 /// [`peer_declares_its_own_limits`] holds the declaration to one event at a
802 /// time. This rule holds its other half, [`PeerLimits::max_batch_events`]
803 /// and [`PeerLimits::max_batch_bytes`], to a push as large as they say. A
804 /// runner that honours them and is refused anyway has been told a limit
805 /// that is not the one imposed, and learns the real one at ingest. The
806 /// rule plays that runner. It reads [`SyncPeer::limits`] once, and then:
807 ///
808 /// 1. takes the corner's event count, `max_batch_events` capped by
809 /// [`MAX_PROVOKED_BATCH_EVENTS`], and its bytes, `max_batch_bytes`
810 /// capped by [`MAX_PROVOKED_BATCH_BYTES`] and by what that many events
811 /// can carry with none over `max_event_bytes`;
812 /// 2. pushes the **count corner**: that many single-event groups with
813 /// empty payloads. The declaration must admit it, and it must land,
814 /// every event acknowledged as appended;
815 /// 3. pushes the **full corner**, when it has any bytes: as many
816 /// single-event groups again, from a second origin, whose payloads
817 /// total exactly the corner's bytes and differ by at most one byte. The
818 /// same must hold;
819 /// 4. pulls the whole log back: every event of both pushes is held, byte
820 /// for byte, which rejects a peer that acknowledges what it dropped.
821 ///
822 /// Two pushes rather than one, so a refusal names the limit that was not
823 /// imposed: the count corner carries no bytes. And the events are as small
824 /// as the corner allows, with no guard, tags or metadata, so a lie about a
825 /// per-event limit, which is [`peer_declares_its_own_limits`]'s to judge,
826 /// cannot fail this rule as well.
827 ///
828 /// [`PeerLimits::max_batch_events`]: happenstance_sync::PeerLimits::max_batch_events
829 /// [`PeerLimits::max_batch_bytes`]: happenstance_sync::PeerLimits::max_batch_bytes
830 /// [`MAX_PROVOKED_BATCH_EVENTS`]: crate::MAX_PROVOKED_BATCH_EVENTS
831 /// [`MAX_PROVOKED_BATCH_BYTES`]: crate::MAX_PROVOKED_BATCH_BYTES
832 ///
833 /// # Rejects
834 ///
835 /// `tests/wrong_peers.rs` carries five, each over the reference peer:
836 /// a peer that takes fewer events to a push than it declares, and one that
837 /// declares twice the `max_batch_bytes` it enforces, which SY-37's rule
838 /// also uses to attribute its skips; two that refuse *at* the declared
839 /// limit, `>=` where the declaration means `>`, one on the event count and
840 /// one on the bytes, which pin each corner to the declaration exactly; and
841 /// a peer that stores only the head of a large push and acknowledges all
842 /// of it, which only the pull-back sees.
843 ///
844 /// # Does not reject
845 ///
846 /// A peer that *accepts* more than it declares: a runner that reads the
847 /// declaration never sends more, so nothing is lost. Nor the refusal of a
848 /// push one byte over the declaration, which is SY-36's `Split` and
849 /// [`every_refusal_states_its_class`]'s to judge. Nor a pull larger than
850 /// the declaration: the batch limits bind a push. Nor a declaration of
851 /// `max_batch_events` of zero, which [`peer_declares_its_own_limits`]
852 /// fails and this rule has no corner to push into, so it pushes nothing
853 /// and runs. Nor a peer whose limits are true up to the caps and false
854 /// above them, because the corner is built at the caps.
855 ///
856 /// # Errors
857 ///
858 /// A [`Violation`] of SY-18 if the declaration does not admit one of the
859 /// corners, if the peer refuses either push or acknowledges it as anything
860 /// but every event appended, or if an event of either is not handed back
861 /// whole; or if the peer refuses a pull or keeps handing back groups past
862 /// one pull per event pushed.
863 pub async fn peer_takes_a_batch_at_its_declared_limits<F: SyncFixture>(
864 open: impl AsyncFn() -> F,
865 ) -> Result<RuleOutcome, Violation> {
866 const CLAUSE: &str = "SY-18";
867 let fixture = open().await;
868 let peer = fixture.connect().await;
869
870 let limits = peer.limits();
871 let events = limits.max_batch_events.min(MAX_PROVOKED_BATCH_EVENTS);
872 if events == 0 {
873 // A declaration that admits no event: `peer_declares_its_own_limits`
874 // fails it, and there is no corner here to push into.
875 return Ok(RuleOutcome::Ran);
876 }
877
878 // The most bytes `events` events carry with none over `max_event_bytes`.
879 let bytes = limits
880 .max_batch_bytes
881 .min(MAX_PROVOKED_BATCH_BYTES)
882 .min(events.saturating_mul(limits.max_event_bytes));
883
884 let mut landed =
885 vec![push_the_corner(&peer, &limits, COUNT_CORNER_ORIGIN, events, 0, CLAUSE).await?];
886 if bytes > 0 {
887 landed.push(
888 push_the_corner(&peer, &limits, BYTE_CORNER_ORIGIN, events, bytes, CLAUSE).await?,
889 );
890 }
891
892 // One pull per event pushed, and the empty one that ends the log: a
893 // peer that pages one event at a time still fits (H-13).
894 let pushed = landed
895 .iter()
896 .map(|batch| batch.events().count())
897 .sum::<usize>();
898 let held: BTreeMap<EventId, ReplicatedEvent> =
899 pull_up_to(&peer, pushed.saturating_add(1), CLAUSE)
900 .await?
901 .into_iter()
902 .flat_map(|group| group.events)
903 .map(|event| (event.id, event))
904 .collect();
905 for expected in landed.iter().flat_map(PushBatch::events) {
906 ensure(held.get(&expected.id) == Some(expected), CLAUSE, || {
907 format!(
908 "event {} of {} bytes, in a push at the declared batch limits, was \
909 acknowledged and is not in the peer's log, byte for byte",
910 expected.id,
911 expected.payload_len()
912 )
913 })?;
914 }
915 Ok(RuleOutcome::Ran)
916 }
917
918 /// SY-30: the decomposition into independently conditioned groups is kept
919 /// end to end. What a peer is pushed as three groups it hands back as
920 /// those three groups: the same boundaries, the same events in order, and
921 /// the same guards.
922 ///
923 /// One push of `[a1, a2]` under a guard, `[b1]` under none, and `[c1, c2]`
924 /// under a second guard, all from one origin, well inside the minimum
925 /// limits; then a pull of the whole log. Both guards are position-free, so
926 /// SY-6's refusal of a guard carrying `after` never reaches them, and they
927 /// name types nothing in the suite writes, so a peer that evaluated them
928 /// would refuse nothing here.
929 ///
930 /// A peer that relays is what makes this the transport's obligation and not
931 /// only the envelope's: a hub that forwards a spoke's group merged with its
932 /// neighbours, or without its guard, publishes a decomposition the origin
933 /// never made, and the next hop can no longer tell which events were
934 /// decided together, or under what (SY-39 is the store's half).
935 ///
936 /// # Rejects
937 ///
938 /// The page-as-one-group peer #420 replaced, which hands a pull back as one
939 /// unguarded group, and a peer that keeps every boundary and drops the
940 /// guard. `tests/wrong_peers.rs` carries both, and SY-2's two mutants, the
941 /// flattener and the peer that pages by event, fail this rule too.
942 ///
943 /// # Errors
944 ///
945 /// A [`Violation`] of SY-30 if the peer refuses the push or a pull, or hands
946 /// back anything but the groups it was pushed.
947 pub async fn push_envelope_preserves_group_boundaries<F: SyncFixture>(
948 open: impl AsyncFn() -> F,
949 ) -> Result<RuleOutcome, Violation> {
950 const CLAUSE: &str = "SY-30";
951 let fixture = open().await;
952 let peer = fixture.connect().await;
953
954 let first = guard_on(GUARDED_FIRST, CLAUSE)?;
955 let last = guard_on(GUARDED_LAST, CLAUSE)?;
956 let pushed = vec![
957 EventGroup::new(Some(first), vec![grouped(1, CLAUSE)?, grouped(2, CLAUSE)?]),
958 EventGroup::new(None, vec![grouped(3, CLAUSE)?]),
959 EventGroup::new(Some(last), vec![grouped(4, CLAUSE)?, grouped(5, CLAUSE)?]),
960 ];
961 let batch = PushBatch::new(pushed);
962 peer.push(&batch).await.map_err(|error| {
963 Violation::new(
964 CLAUSE,
965 format!("the peer refused three groups well inside the minimum limits: {error}"),
966 )
967 })?;
968
969 let held = pull_everything(&peer, CLAUSE).await?;
970 let shape = |groups: &[EventGroup]| -> Vec<(usize, bool)> {
971 groups
972 .iter()
973 .map(|group| (group.events.len(), group.guard.is_some()))
974 .collect()
975 };
976 ensure(held == batch.groups, CLAUSE, || {
977 format!(
978 "the peer was pushed groups of (events, guarded) {:?} and handed back {:?}; a \
979 reader of that log cannot tell which events were decided together, or under \
980 what",
981 shape(&batch.groups),
982 shape(&held)
983 )
984 })?;
985 Ok(RuleOutcome::Ran)
986 }
987
988 /// SY-28, and SY-27 beneath it: a round trip preserves the whole log. Once
989 /// the two sides have pushed and pulled to quiescence, each holds the same
990 /// set of `EventId`s, each event with byte-identical type, tags, data and
991 /// metadata, and the recorded time it was pushed with (VT-9).
992 ///
993 /// The rule plays one side (SY-8). It pushes a log spread over both axes
994 /// a filter on `Query`'s surface cuts along, types and tags — two origins,
995 /// three event types, two regions, a confidential pricing slice in a
996 /// two-event group, an untagged event and one with metadata — pulls from
997 /// the start until the peer hands back an empty batch, and holds what came
998 /// back to what went: every identity, every byte. It compares no position
999 /// (SY-19): an identity is the origin's, compared whole, and the origin
1000 /// positions leave gaps, as a conformant origin may.
1001 ///
1002 /// # Rejects
1003 ///
1004 /// A peer that replicates a slice: one that withholds from its
1005 /// counterpart the events a type or tag filter matches, among the types
1006 /// and tags the rule's own log carries — the scoped hub or filtered spoke
1007 /// ADR-0027 kept off the 1.0 port. It stores and acknowledges every
1008 /// push truthfully, so no other rule sees it. `tests/wrong_scopes.rs`
1009 /// carries it with three filters, by tag, by type, and by type and tag.
1010 ///
1011 /// # Does not reject
1012 ///
1013 /// An identity the rule never pushed: on a far side that holds more, the
1014 /// rule's side would hold it too once it had pulled, and the two sets would
1015 /// still agree. Nor a peer that hands an event back twice, byte-identical:
1016 /// redelivery is SY-11's, and the model family judges it. Nor a filter that
1017 /// matches none of the rule's events, such as one on a tag its log never
1018 /// carries: the rule sees only what it pushed.
1019 ///
1020 /// # Errors
1021 ///
1022 /// A [`Violation`] of SY-28 if the peer refuses the push or a pull, keeps
1023 /// handing back groups past the suite's pull bound, withholds a pushed
1024 /// event, hands one back changed, or hands one identity back as two
1025 /// different events.
1026 pub async fn round_trip_preserves_the_whole_log<F: SyncFixture>(
1027 open: impl AsyncFn() -> F,
1028 ) -> Result<RuleOutcome, Violation> {
1029 const CLAUSE: &str = "SY-28";
1030 let fixture = open().await;
1031 let peer = fixture.connect().await;
1032 let log = whole_log::sliced_log(CLAUSE)?;
1033 peer.push(&log).await.map_err(|error| {
1034 Violation::new(
1035 CLAUSE,
1036 format!("the peer refused a batch well inside the minimum limits: {error}"),
1037 )
1038 })?;
1039 let handed_back = pull_everything(&peer, CLAUSE).await?;
1040 whole_log::holds_the_whole_log(
1041 &log,
1042 handed_back.into_iter().flat_map(|group| group.events),
1043 CLAUSE,
1044 )?;
1045 Ok(RuleOutcome::Ran)
1046 }
1047
1048 /// SY-32: a peer that has forgotten history reports the floor, and
1049 /// refuses a resume token below it with class
1050 /// [`Reseed`](happenstance_sync::FailureClass::Reseed), so a peer that was
1051 /// offline longer than its retention window is told it cannot converge
1052 /// rather than converging on a strict subset in silence.
1053 ///
1054 /// The rule plays the vessel (SY-8). A shore origin's log is pushed one
1055 /// group per day, on a test clock: days 0 and 10, then a pull to the end
1056 /// whose token is the vessel that goes offline on day 10; days 20, 50 and
1057 /// 70, then a pull from that token to the end whose token is a vessel that
1058 /// last synced on day 70; then days 100 and 125. On day 130 the fixture
1059 /// compacts on a 90-day window, forgetting days 0 to 20. Then:
1060 ///
1061 /// * the peer's [`retention_floor`](happenstance_sync::PeerLimits::retention_floor)
1062 /// names one of the events it was asked to forget;
1063 /// * a pull from the day-10 token is refused with class `Reseed`;
1064 /// * so is a pull from the start: a peer that has compacted cannot hand a
1065 /// strict subset to an edge that lost its token, or to a runner that
1066 /// drops its token on a stop;
1067 /// * a pull from the day-70 token hands back exactly the events of days 100
1068 /// and 125, compared whole (SY-35), each once.
1069 ///
1070 /// A fixture that declines [`COMPACTION`](crate::SyncFixture::COMPACTION)
1071 /// is reported [`Skipped`](RuleOutcome::Skipped) with its stated reason.
1072 ///
1073 /// # Rejects
1074 ///
1075 /// A peer that compacts and answers the stale token anyway: one that
1076 /// drains its log without an offset, so the old index lands on a later
1077 /// group, and one that declares a floor and answers a stale token from
1078 /// it, and one that serves a pull from the start from its floor. Each
1079 /// converges on a strict subset in silence. Also a peer that refuses and
1080 /// declares no floor or its oldest retained event as one, one that refuses
1081 /// as `Transient`, which a runner retries for ever, and one that refuses
1082 /// every token once compacted. `tests/wrong_retention.rs` carries all seven.
1083 ///
1084 /// # Does not reject
1085 ///
1086 /// A floor naming the wrong forgotten event: any event the rule asked the
1087 /// peer to forget passes, and the reference peer's unit tests pin which
1088 /// one. Nor a scattered purge, which SY-32 does not report in 1.x.
1089 ///
1090 /// # Errors
1091 ///
1092 /// A [`Violation`] of SY-32 if the peer refuses a push or a resumable
1093 /// pull, declares no floor or a floor it was not asked to forget, answers
1094 /// the stale token or a pull from the start, refuses either with a class
1095 /// other than `Reseed`, or hands
1096 /// back anything but the events written after the recent token.
1097 pub async fn retention_gap_is_reported_not_silent<F: SyncFixture>(
1098 open: impl AsyncFn() -> F,
1099 ) -> Result<RuleOutcome, Violation> {
1100 let fixture = open().await;
1101 if let Some(reason) = F::COMPACTION.reason() {
1102 return Ok(RuleOutcome::Skipped {
1103 capability: "COMPACTION",
1104 reason,
1105 });
1106 }
1107 let peer = fixture.connect().await;
1108 retention::reported_not_silent(&fixture, &peer).await?;
1109 Ok(RuleOutcome::Ran)
1110 }
1111
1112 /// What one log SY-37's rule wrote showed it.
1113 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1114 enum Log {
1115 /// Built, and a second non-empty page was seen: a `Nothing` at a
1116 /// boundary could have been a lie, and was checked.
1117 Paged,
1118 /// Built, or not written at all, and no page boundary was seen.
1119 NoPage,
1120 /// The peer refused a push of it, so it was not built.
1121 Refused,
1122 }
1123
1124 /// Whether the peer took every push of a log.
1125 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
1126 enum Pushed {
1127 All,
1128 Refused,
1129 }
1130
1131 /// Writes `fill` to `peer` and, if the peer took it, follows its tokens.
1132 async fn write_log<P: SyncPeer>(
1133 peer: &P,
1134 fill: Fill,
1135 clause: &'static str,
1136 ) -> Result<Log, Violation> {
1137 Ok(match fill_with_readings(peer, fill, clause).await? {
1138 Pushed::Refused => Log::Refused,
1139 Pushed::All if follow_tokens(peer, fill.groups, clause).await? => Log::Paged,
1140 Pushed::All => Log::NoPage,
1141 })
1142 }
1143
1144 /// One log SY-37's rule writes: how many single-event groups, how many
1145 /// payload bytes each carries at least, and how many groups go in a push.
1146 #[derive(Debug, Clone, Copy)]
1147 struct Fill {
1148 groups: usize,
1149 payload: usize,
1150 per_push: usize,
1151 }
1152
1153 impl Fill {
1154 /// The cap plus one groups with tiny payloads, whatever the peer
1155 /// declares: a peer that pages at any count up to the cap shows a
1156 /// second page, including one whose declaration understates it.
1157 fn cut_by_count(limits: &PeerLimits) -> Self {
1158 Self {
1159 groups: FILL_CAP.saturating_add(1),
1160 payload: 0,
1161 per_push: limits.max_batch_events.max(1),
1162 }
1163 }
1164
1165 /// One group more than `max_batch_bytes` admits at the largest payload
1166 /// the peer takes, when that is fewer events than `max_batch_events`;
1167 /// `None` when the count cuts first or the log would pass either cap.
1168 ///
1169 /// Pushed one event at a time. The page boundary is the pull's to
1170 /// draw, and a push of one event no larger than SY-18's boundary event
1171 /// can be refused only for a per-event limit, which SY-18's rule
1172 /// judges. A push of a full page would also be refused by a peer that
1173 /// overstates `max_batch_bytes` alone, which is SY-18's batch rule's
1174 /// to judge, not this log's.
1175 fn cut_by_bytes(limits: &PeerLimits) -> Option<Self> {
1176 let payload = limits.max_event_bytes.min(limits.max_batch_bytes);
1177 let per_page = limits.max_batch_bytes.checked_div(payload)?;
1178 let groups = per_page.checked_add(1)?;
1179 let bytes = groups.checked_mul(payload)?;
1180 let fits = per_page < limits.max_batch_events
1181 && groups <= FILL_CAP.saturating_add(1)
1182 && bytes <= MAX_PROVOKED_BATCH_BYTES;
1183 fits.then_some(Self {
1184 groups,
1185 payload,
1186 per_push: 1,
1187 })
1188 }
1189 }
1190
1191 /// Follows `peer`'s tokens from the start of a log of `groups` groups, and
1192 /// checks the pull after the first `Nothing`. Answers whether a second
1193 /// non-empty page was seen, which is when a `Nothing` could have been a
1194 /// lie about a page boundary.
1195 async fn follow_tokens<P: SyncPeer>(
1196 peer: &P,
1197 groups: usize,
1198 clause: &'static str,
1199 ) -> Result<bool, Violation> {
1200 let refused = |error| Violation::new(clause, format!("the peer refused a pull: {error}"));
1201 let mut resume = None;
1202 let mut pages = 0_usize;
1203 // The suite's liveness guard: a log of `groups` groups cannot fill more
1204 // non-empty pulls than that unless the peer repeats itself; one more for
1205 // the pull that ends it.
1206 for _ in 0..=groups {
1207 let pulled = peer.pull(resume.as_ref()).await.map_err(refused)?;
1208 if !pulled.batch.groups.is_empty() {
1209 pages = pages.saturating_add(1);
1210 }
1211 match pulled.waiting {
1212 Waiting::Nothing => {
1213 let next = peer.pull(Some(&pulled.resume)).await.map_err(refused)?;
1214 let missed = next.batch.events().count();
1215 ensure(missed == 0, clause, || {
1216 format!(
1217 "the peer said nothing was waiting, and the next pull from the token \
1218 it returned carried {missed} event(s); a runner that believed it \
1219 stopped short of them"
1220 )
1221 })?;
1222 return Ok(pages >= 2);
1223 }
1224 Waiting::Unknown | Waiting::Events(_) if pulled.batch.groups.is_empty() => {
1225 return Ok(pages >= 2);
1226 }
1227 Waiting::Unknown | Waiting::Events(_) => resume = Some(pulled.resume),
1228 }
1229 }
1230 Err(Violation::new(
1231 clause,
1232 format!(
1233 "the peer was still handing back groups of a {groups}-group log after {} pulls",
1234 groups.saturating_add(1)
1235 ),
1236 ))
1237 }
1238
1239 /// SY-23: the order a deployment may rely on peer-independently,
1240 /// [`EventId`] order, is the same on this peer as on every other, whatever
1241 /// order the events arrived in.
1242 ///
1243 /// The rule plays the other peer, which holds the events as their origins
1244 /// wrote them. Three origins number their events with gaps, which the
1245 /// contract allows, and the rule pushes them one to a push in an arrival
1246 /// order unlike their `EventId` order, in which an origin's higher position
1247 /// arrives before its lower one, as a delayed page lands after a later one.
1248 /// It then pulls the peer's whole log, sorts it by `EventId` and compares
1249 /// it with its own copy, sorted the same way, event by event and byte for
1250 /// byte. Nothing is decoded (SY-35), and the rule never asks the peer for
1251 /// an order: where it hands events back in arrival order, SY-25's subject,
1252 /// the sort makes that irrelevant.
1253 ///
1254 /// # Rejects
1255 ///
1256 /// A peer that dedupes by the highest origin position it has seen from
1257 /// each origin rather than by identity: the cheap shortcut its own
1258 /// [`Ack::confirmed`] watermark invites. It drops an origin's lower event
1259 /// when it arrives after a higher one, so its `EventId` order is missing
1260 /// an event every other peer's has, and a deployment sorting by it
1261 /// produces different output there. `tests/wrong_orders.rs` carries it,
1262 /// beside its faithful control.
1263 ///
1264 /// # Does not reject
1265 ///
1266 /// An `Ord` on [`EventId`] other than `(origin, origin_position)`, sorted
1267 /// with the origin first, which is the other half of SY-23. That order is
1268 /// `happenstance-core`'s derive (`identity.rs`, VT-5), and no peer can
1269 /// supply its own. The rule sorts with it, so a change there would move
1270 /// the order on every peer together, which this rule cannot see.
1271 ///
1272 /// # Errors
1273 ///
1274 /// A [`Violation`] of SY-23 if the peer refuses a push or a pull, or if
1275 /// its log, sorted by `EventId`, is not the pushed events sorted the same
1276 /// way.
1277 pub async fn event_id_order_is_identical_on_every_peer<F: SyncFixture>(
1278 open: impl AsyncFn() -> F,
1279 ) -> Result<RuleOutcome, Violation> {
1280 const CLAUSE: &str = "SY-23";
1281 let fixture = open().await;
1282 let peer = fixture.connect().await;
1283 let arriving = arrival_order(CLAUSE)?;
1284 for event in &arriving {
1285 peer.push(&one_event(event.clone()))
1286 .await
1287 .map_err(|error| {
1288 Violation::new(
1289 CLAUSE,
1290 format!("the peer refused a one-event push of {}: {error}", event.id),
1291 )
1292 })?;
1293 }
1294
1295 let mut held: Vec<ReplicatedEvent> = pull_everything(&peer, CLAUSE)
1296 .await?
1297 .into_iter()
1298 .flat_map(|group| group.events)
1299 .collect();
1300 held.sort_by_key(|event| event.id);
1301 let mut origins = arriving;
1302 origins.sort_by_key(|event| event.id);
1303 let ids = |events: &[ReplicatedEvent]| -> Vec<EventId> {
1304 events.iter().map(|event| event.id).collect()
1305 };
1306 ensure(ids(&held) == ids(&origins), CLAUSE, || {
1307 format!(
1308 "sorted by EventId, the peer holds {:?} and its origins wrote {:?}; a \
1309 deployment that sorts by EventId gets different output on this peer",
1310 ids(&held),
1311 ids(&origins)
1312 )
1313 })?;
1314 for (kept, written) in held.iter().zip(&origins) {
1315 ensure(kept == written, CLAUSE, || {
1316 format!(
1317 "{} is held with a recorded time or bytes other than its origin's; sorted \
1318 by EventId, the two logs agree on identities and not on content",
1319 kept.id
1320 )
1321 })?;
1322 }
1323 Ok(RuleOutcome::Ran)
1324 }
1325
1326 /// Pushes `fill.groups` single-event groups from [`ORIGIN_A`], at most
1327 /// `fill.per_push` to a push. Answers whether the peer took them all.
1328 async fn fill_with_readings<P: SyncPeer>(
1329 peer: &P,
1330 fill: Fill,
1331 clause: &'static str,
1332 ) -> Result<Pushed, Violation> {
1333 let Fill {
1334 groups: count,
1335 payload,
1336 per_push: chunk,
1337 } = fill;
1338 let mut position = SequencePosition::FIRST;
1339 let mut groups = Vec::with_capacity(chunk.min(count));
1340 for reading in 1..=count {
1341 // Distinct opaque bytes per event, padded to the fill's payload
1342 // size, and never parsed (SY-35).
1343 let mut data = reading.to_string().into_bytes();
1344 data.resize(data.len().max(payload), 0);
1345 let event = Event::new(READING_TAKEN, data).map_err(|error| {
1346 Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1347 })?;
1348 groups.push(EventGroup::new(
1349 None,
1350 vec![ReplicatedEvent::new(
1351 EventId::new(ORIGIN_A, position),
1352 RecordedAt::from_millis(1_800_000_000_000),
1353 event,
1354 )],
1355 ));
1356 position = position
1357 .next()
1358 .ok_or_else(|| Violation::new(clause, "the rule's log ran out of positions"))?;
1359
1360 if groups.len() == chunk || reading == count {
1361 let batch = PushBatch::new(core::mem::take(&mut groups));
1362 // A refusal here is the peer disagreeing with its own
1363 // declaration. Whose failure that is depends on the log: for
1364 // the byte-cut log, one event sized from `max_event_bytes` to a
1365 // push, it is SY-18's per-event rule's to judge; for the
1366 // count-cut log, tiny events at most `max_batch_events` to a
1367 // push, it is a lie about batch limits, SY-18's batch rule's
1368 // to judge. The caller reports which, as a skip, unless the
1369 // other log paged.
1370 if peer.push(&batch).await.is_err() {
1371 return Ok(Pushed::Refused);
1372 }
1373 }
1374 }
1375 Ok(Pushed::All)
1376 }
1377
1378 /// Pulls from the start of the peer's log until it hands back an empty
1379 /// batch, which the port defines as caught up.
1380 ///
1381 /// It ignores [`Pulled::waiting`](happenstance_sync::Pulled::waiting) on
1382 /// purpose, so a peer wrong about it fails SY-37's rule and only that one.
1383 async fn pull_everything<P: SyncPeer>(
1384 peer: &P,
1385 clause: &'static str,
1386 ) -> Result<Vec<EventGroup>, Violation> {
1387 pull_up_to(peer, MAX_PULLS, clause).await
1388 }
1389
1390 /// [`pull_everything`], giving up after `max_pulls` pulls rather than
1391 /// [`MAX_PULLS`]: for a rule whose log is too long for that bound.
1392 async fn pull_up_to<P: SyncPeer>(
1393 peer: &P,
1394 max_pulls: usize,
1395 clause: &'static str,
1396 ) -> Result<Vec<EventGroup>, Violation> {
1397 let mut groups = Vec::new();
1398 let mut resume: Option<P::Resume> = None;
1399 for _ in 0..max_pulls {
1400 let pulled = peer.pull(resume.as_ref()).await.map_err(|error| {
1401 Violation::new(clause, format!("the peer refused a pull: {error}"))
1402 })?;
1403 if pulled.batch.groups.is_empty() {
1404 return Ok(groups);
1405 }
1406 groups.extend(pulled.batch.groups);
1407 resume = Some(pulled.resume);
1408 }
1409 Err(Violation::new(
1410 clause,
1411 format!("the peer was still handing back groups after {max_pulls} pulls"),
1412 ))
1413 }
1414
1415 /// SY-23's log, in the order it arrives: three origins, each numbering
1416 /// its events with gaps, interleaved unlike their `EventId` order, and the
1417 /// low origin's and the high origin's higher position each arriving before
1418 /// its lower one. The positions are what the origins chose to send, never
1419 /// a claim about what a peer assigns.
1420 fn arrival_order(clause: &'static str) -> Result<Vec<ReplicatedEvent>, Violation> {
1421 [
1422 (ORDER_LOW, 5),
1423 (ORDER_MID, 3),
1424 (ORDER_HIGH, 4),
1425 (ORDER_LOW, 2),
1426 (ORDER_HIGH, 1),
1427 (ORDER_MID, 8),
1428 ]
1429 .into_iter()
1430 .map(|(origin, position)| {
1431 let data = format!("sy23 {origin} {position}");
1432 durable_reading(origin, position, data.as_bytes(), clause)
1433 })
1434 .collect()
1435 }
1436
1437 /// `event` as a batch of one group.
1438 fn one_event(event: ReplicatedEvent) -> PushBatch {
1439 PushBatch::new(vec![EventGroup::new(None, vec![event])])
1440 }
1441
1442 /// Pushes `batch`, which the peer's declaration admits, and requires it to
1443 /// land as one event appended. A refusal here is the failure SY-18 exists
1444 /// to move: found at ingest, after the origin committed.
1445 async fn push_admitted<P: SyncPeer>(
1446 peer: &P,
1447 batch: &PushBatch,
1448 what: &str,
1449 clause: &'static str,
1450 ) -> Result<(), Violation> {
1451 let ack = push_or_report(
1452 peer,
1453 batch,
1454 what,
1455 "the failure was relocated to ingest, not prevented",
1456 clause,
1457 )
1458 .await?;
1459 ensure(ack.appended == 1 && ack.skipped == 0, clause, || {
1460 format!(
1461 "the peer acknowledged {what} as {} appended and {} skipped; it held nothing \
1462 with that identity, so it must append it",
1463 ack.appended, ack.skipped
1464 )
1465 })
1466 }
1467
1468 /// Pushes `batch`, which the peer's declaration admits, and reports a
1469 /// refusal as `what` refused, followed by `meaning`: what the refusal says
1470 /// about the peer.
1471 async fn push_or_report<P: SyncPeer>(
1472 peer: &P,
1473 batch: &PushBatch,
1474 what: &str,
1475 meaning: &str,
1476 clause: &'static str,
1477 ) -> Result<Ack, Violation> {
1478 peer.push(batch).await.map_err(|error| {
1479 Violation::new(
1480 clause,
1481 format!(
1482 "the declared limits admit {what} and the push refused it ({error}, class \
1483 {:?}): {meaning}",
1484 error.class()
1485 ),
1486 )
1487 })
1488 }
1489
1490 /// Builds the batch at a corner of `limits` — `events` single-event
1491 /// groups carrying `bytes` payload bytes between them — checks that the
1492 /// declaration admits it, and pushes it: it must land whole, every event
1493 /// acknowledged as appended. Answers the batch, for the pull-back.
1494 async fn push_the_corner<P: SyncPeer>(
1495 peer: &P,
1496 limits: &PeerLimits,
1497 origin: StoreId,
1498 events: usize,
1499 bytes: usize,
1500 clause: &'static str,
1501 ) -> Result<PushBatch, Violation> {
1502 let batch = batch_at_the_corner(origin, events, bytes, clause)?;
1503 let what = format!("a push of {events} events and {bytes} payload bytes");
1504 ensure(limits.admits(&batch), clause, || {
1505 format!(
1506 "the declaration {limits:?} does not admit {what}, a batch at the limits \
1507 it states"
1508 )
1509 })?;
1510 let ack = push_or_report(
1511 peer,
1512 &batch,
1513 &what,
1514 "a declared batch limit this peer does not impose",
1515 clause,
1516 )
1517 .await?;
1518 let expected = u64::try_from(events).map_err(|error| {
1519 Violation::new(
1520 clause,
1521 format!("the rule's own event count is too large: {error}"),
1522 )
1523 })?;
1524 ensure(ack.appended == expected && ack.skipped == 0, clause, || {
1525 format!(
1526 "the peer acknowledged {what} as {} appended and {} skipped; it held none of \
1527 those identities, so it must append all {expected}",
1528 ack.appended, ack.skipped
1529 )
1530 })?;
1531 Ok(batch)
1532 }
1533
1534 /// `events` single-event groups from `origin`, at its positions from the
1535 /// first, whose payloads total exactly `bytes`: each `bytes / events`
1536 /// long, and the first `bytes % events` one byte longer. The bytes are
1537 /// zeros and are never parsed (SY-35).
1538 ///
1539 /// Single-event groups with no guard, no tags and no metadata, so a peer
1540 /// has nothing to cut, evaluate or cap but the batch itself.
1541 fn batch_at_the_corner(
1542 origin: StoreId,
1543 events: usize,
1544 bytes: usize,
1545 clause: &'static str,
1546 ) -> Result<PushBatch, Violation> {
1547 let no_events = || Violation::new(clause, "the rule built a corner of no events");
1548 let base = bytes.checked_div(events).ok_or_else(no_events)?;
1549 let longer = bytes.checked_rem(events).ok_or_else(no_events)?;
1550
1551 let mut position = SequencePosition::FIRST;
1552 let mut groups = Vec::with_capacity(events);
1553 for index in 0..events {
1554 let size = if index < longer {
1555 base.saturating_add(1)
1556 } else {
1557 base
1558 };
1559 let event = Event::new(BATCH_FILLED, vec![0_u8; size]).map_err(|error| {
1560 Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1561 })?;
1562 groups.push(EventGroup::new(
1563 None,
1564 vec![ReplicatedEvent::new(
1565 EventId::new(origin, position),
1566 RecordedAt::from_millis(1_800_000_000_000),
1567 event,
1568 )],
1569 ));
1570 position = position
1571 .next()
1572 .ok_or_else(|| Violation::new(clause, "the rule's corner ran out of positions"))?;
1573 }
1574 Ok(PushBatch::new(groups))
1575 }
1576
1577 /// Which of an event's two opaque fields carries a boundary event's bytes.
1578 ///
1579 /// Both, one event each, because `max_event_bytes` bounds
1580 /// [`ReplicatedEvent::payload_len`], which is data and metadata together:
1581 /// a peer that stores metadata somewhere smaller has a limit its
1582 /// declaration does not state.
1583 #[derive(Debug, Clone, Copy)]
1584 enum Carrier {
1585 Data,
1586 Metadata,
1587 }
1588
1589 impl Carrier {
1590 /// What the violation message calls the event this carrier builds.
1591 const fn describe(self) -> &'static str {
1592 match self {
1593 Self::Data => "an event at the declared boundary, in its data",
1594 Self::Metadata => "an event at the declared boundary, in its metadata",
1595 }
1596 }
1597
1598 /// Each boundary event's origin, so the two are distinct facts.
1599 const fn origin(self) -> StoreId {
1600 match self {
1601 Self::Data => BOUNDARY_ORIGIN,
1602 Self::Metadata => METADATA_ORIGIN,
1603 }
1604 }
1605 }
1606
1607 /// An event at every envelope floor the contract sets, carrying `size`
1608 /// opaque bytes (SY-35) in `carrier`: a type of [`MAX_EVENT_TYPE_LEN`]
1609 /// bytes and [`MIN_SUPPORTED_TAGS_PER_EVENT`] distinct tags of
1610 /// [`MAX_TAG_LEN`] bytes.
1611 fn event_at_the_envelope_floors(
1612 size: usize,
1613 carrier: Carrier,
1614 clause: &'static str,
1615 ) -> Result<ReplicatedEvent, Violation> {
1616 let event_type = EventType::new("L".repeat(MAX_EVENT_TYPE_LEN)).map_err(|error| {
1617 Violation::new(clause, format!("the rule's own type is invalid: {error}"))
1618 })?;
1619 let tags = (0..MIN_SUPPORTED_TAGS_PER_EVENT)
1620 .map(|i| Tag::new(format!("{i:0>MAX_TAG_LEN$}")))
1621 .collect::<Result<Tags, _>>()
1622 .map_err(|error| {
1623 Violation::new(clause, format!("the rule's own tag is invalid: {error}"))
1624 })?;
1625 let bytes = vec![0_u8; size];
1626 let event = match carrier {
1627 Carrier::Data => Event::new(event_type, bytes),
1628 Carrier::Metadata => {
1629 Event::new(event_type, Vec::new()).map(|event| event.with_metadata(bytes))
1630 }
1631 }
1632 .map_err(|error| {
1633 Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1634 })?
1635 .with_tags(tags);
1636 Ok(ReplicatedEvent::new(
1637 EventId::new(carrier.origin(), SequencePosition::FIRST),
1638 RecordedAt::from_millis(1_800_000_000_000),
1639 event,
1640 ))
1641 }
1642
1643 /// The guard both claims travel under: "nobody has claimed seat s1", with
1644 /// no position, so it is byte-identical wherever it was written.
1645 fn seat_guard(clause: &'static str) -> Result<AppendCondition, Violation> {
1646 let item = QueryItem::new([SEAT_CLAIMED], seat()).map_err(|error| {
1647 Violation::new(clause, format!("the rule's own query is invalid: {error}"))
1648 })?;
1649 Ok(AppendCondition::new(Query::from_item(item)))
1650 }
1651
1652 fn seat() -> Tags {
1653 [Tag::from_static("seat:s1")].into_iter().collect()
1654 }
1655
1656 /// A position-free guard naming `event_type`, for SY-30's groups.
1657 fn guard_on(event_type: EventType, clause: &'static str) -> Result<AppendCondition, Violation> {
1658 let item = QueryItem::of_types([event_type]).map_err(|error| {
1659 Violation::new(clause, format!("the rule's own query is invalid: {error}"))
1660 })?;
1661 Ok(AppendCondition::new(Query::from_item(item)))
1662 }
1663
1664 /// The SY-30 origin's event at its own `position`, with a payload of its
1665 /// own so "the same events" means byte for byte (SY-35).
1666 fn grouped(position: u64, clause: &'static str) -> Result<ReplicatedEvent, Violation> {
1667 let at = SequencePosition::new(position)
1668 .ok_or_else(|| Violation::new(clause, "the rule's origin position is zero"))?;
1669 let event = Event::new(GROUP_WRITTEN, format!("group-{position}").into_bytes()).map_err(
1670 |error| Violation::new(clause, format!("the rule's own event is invalid: {error}")),
1671 )?;
1672 Ok(ReplicatedEvent::new(
1673 EventId::new(GROUPS_ORIGIN, at),
1674 RecordedAt::from_millis(1_800_000_000_000),
1675 event,
1676 ))
1677 }
1678
1679 /// `origin`'s claim on the seat, the first event in its log.
1680 fn claim(origin: StoreId, clause: &'static str) -> Result<ReplicatedEvent, Violation> {
1681 replicated(origin, SEAT_CLAIMED, clause)
1682 }
1683
1684 /// A reading `origin` recorded at its own `position`, carrying `data` as
1685 /// opaque bytes (SY-35).
1686 fn durable_reading(
1687 origin: StoreId,
1688 position: u64,
1689 data: &[u8],
1690 clause: &'static str,
1691 ) -> Result<ReplicatedEvent, Violation> {
1692 let position = SequencePosition::new(position)
1693 .ok_or_else(|| Violation::new(clause, "the rule's origin position is zero"))?;
1694 let event = Event::new(READING_TAKEN, data.to_vec()).map_err(|error| {
1695 Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1696 })?;
1697 Ok(ReplicatedEvent::new(
1698 EventId::new(origin, position),
1699 RecordedAt::from_millis(1_800_000_000_000),
1700 event,
1701 ))
1702 }
1703
1704 fn replicated(
1705 origin: StoreId,
1706 event_type: EventType,
1707 clause: &'static str,
1708 ) -> Result<ReplicatedEvent, Violation> {
1709 // The payload is opaque bytes and stays that way (SY-35): a distinct
1710 // value per origin, so "byte for byte" means something.
1711 let event = Event::new(event_type, origin.to_string().into_bytes())
1712 .map_err(|error| {
1713 Violation::new(clause, format!("the rule's own event is invalid: {error}"))
1714 })?
1715 .with_tags(seat());
1716 Ok(ReplicatedEvent::new(
1717 EventId::new(origin, SequencePosition::FIRST),
1718 RecordedAt::from_millis(1_800_000_000_000),
1719 event,
1720 ))
1721 }
1722
1723 #[cfg(test)]
1724 mod tests {
1725 use alloc::collections::BTreeSet;
1726
1727 use happenstance_sync::ReplicatedEvent;
1728
1729 use super::{BYTE_CORNER_ORIGIN, batch_at_the_corner};
1730
1731 /// The corner's arithmetic at its edges: no bytes, an exact multiple,
1732 /// a remainder of one, fewer bytes than events, and a large corner.
1733 #[test]
1734 fn a_corner_carries_exactly_its_events_and_bytes_spread_evenly() {
1735 let cases: [(usize, usize); 6] = [
1736 (1, 0),
1737 (128, 0),
1738 (128, 65_536),
1739 (128, 65_537),
1740 (3, 2),
1741 (10, 1_048_576),
1742 ];
1743 for (events, bytes) in cases {
1744 let batch = batch_at_the_corner(BYTE_CORNER_ORIGIN, events, bytes, "SY-18")
1745 .expect("a corner of at least one event builds");
1746 let sizes: Vec<usize> = batch.events().map(ReplicatedEvent::payload_len).collect();
1747 let ids: BTreeSet<_> = batch.events().map(|event| event.id).collect();
1748 let case = format!("{events} events, {bytes} bytes");
1749
1750 assert_eq!(sizes.len(), events, "{case}: the event count");
1751 assert_eq!(batch.payload_len(), bytes, "{case}: the payload total");
1752 let spread = sizes.iter().max().zip(sizes.iter().min());
1753 assert!(
1754 spread.is_some_and(|(max, min)| max - min <= 1),
1755 "{case}: sizes {sizes:?} differ by more than one byte"
1756 );
1757 assert_eq!(ids.len(), events, "{case}: every identity is distinct");
1758 assert!(
1759 batch.groups.iter().all(|group| group.events.len() == 1),
1760 "{case}: every group carries one event"
1761 );
1762 }
1763 }
1764
1765 /// The remainder goes to the first events, one byte each.
1766 #[test]
1767 fn a_corner_with_a_remainder_lengthens_its_first_events() {
1768 let batch = batch_at_the_corner(BYTE_CORNER_ORIGIN, 128, 65_537, "SY-18")
1769 .expect("a corner of 128 events builds");
1770 let sizes: Vec<usize> = batch.events().map(ReplicatedEvent::payload_len).collect();
1771 assert_eq!(sizes.first(), Some(&513));
1772 assert!(sizes.iter().skip(1).all(|size| *size == 512), "{sizes:?}");
1773 }
1774
1775 /// A corner of no events is the rule's own mistake, reported as a
1776 /// violation rather than a division by zero.
1777 #[test]
1778 fn a_corner_of_no_events_is_a_violation_not_a_panic() {
1779 for bytes in [0, 1, 65_536] {
1780 let built = batch_at_the_corner(BYTE_CORNER_ORIGIN, 0, bytes, "SY-18");
1781 assert_eq!(
1782 built
1783 .map(|batch| batch.payload_len())
1784 .map_err(|v| v.clause()),
1785 Err("SY-18"),
1786 "0 events, {bytes} bytes"
1787 );
1788 }
1789 }
1790 }
1791}
1792
1793/// Hands the complete sync rule set to `$callback`.
1794///
1795/// This family's single enumeration. `$callback` is the path of a macro that
1796/// accepts a comma-separated list of identifiers, and it is invoked once, with
1797/// every rule in [`rules`].
1798///
1799/// # Examples
1800///
1801/// ```
1802/// macro_rules! rule_names {
1803/// ($($name:ident),* $(,)?) => { [ $( stringify!($name) ),* ] };
1804/// }
1805///
1806/// let names = happenstance_sync_testkit::for_each_sync_peer_rule!(rule_names);
1807/// assert!(names.contains(&"ingest_never_rejects"));
1808/// ```
1809#[macro_export]
1810macro_rules! for_each_sync_peer_rule {
1811 // Raw token trees rather than `$cb:path`, for the reason the event-store
1812 // family's enumeration records: a parsed `path` cannot sit in callee
1813 // position inside an expression.
1814 ($($callback:tt)+) => {
1815 $($callback)+! {
1816 // --- Ingest never refuses (SY-1) --------------------------------
1817 ingest_never_rejects,
1818
1819 // --- A group travels whole (SY-2) -------------------------------
1820 compensation_is_atomic_with_the_losing_event,
1821
1822 // --- EventId order is the same on every peer (SY-23) ------------
1823 event_id_order_is_identical_on_every_peer,
1824
1825 // --- A peer declares its own limits (SY-18) ---------------------
1826 peer_declares_its_own_limits,
1827 peer_takes_a_batch_at_its_declared_limits,
1828
1829 // --- Every refusal states its class (SY-36) ---------------------
1830 every_refusal_states_its_class,
1831
1832 // --- Nothing waiting means nothing waiting (SY-37) --------------
1833 nothing_waiting_means_the_next_pull_is_empty,
1834
1835 // --- An ack confirms only what is durable (SY-31) ---------------
1836 ack_never_confirms_a_non_durable_event,
1837
1838 // --- The group decomposition survives the peer (SY-30) ----------
1839 push_envelope_preserves_group_boundaries,
1840
1841 // --- A round trip preserves the whole log (SY-27, SY-28) --------
1842 round_trip_preserves_the_whole_log,
1843
1844 // --- A retention gap is reported, not silent (SY-32) ------------
1845 retention_gap_is_reported_not_silent,
1846 }
1847 };
1848}
1849
1850/// Emits one `#[tokio::test]` per sync rule.
1851///
1852/// The caller's crate needs `tokio` with `macros` and `rt` in its
1853/// `dev-dependencies`. The default emitter of
1854/// [`sync_peer_conformance!`](crate::sync_peer_conformance).
1855#[macro_export]
1856macro_rules! emit_sync_tokio {
1857 ($($name:ident),* $(,)?) => {
1858 $(
1859 #[tokio::test]
1860 async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1861 $crate::__private::rules::$name(__conformance_fixture)
1862 .await?
1863 .report(::core::stringify!($name));
1864 Ok(())
1865 }
1866 )*
1867 };
1868}
1869
1870/// Emits one plain `#[test]` per sync rule, driven by
1871/// [`happenstance_testkit::block_on`].
1872///
1873/// No runtime and no `Send` bound, so this is the harness a `!Send` peer runs
1874/// under — and the one SY-17's rule names.
1875#[macro_export]
1876macro_rules! emit_sync_blocking {
1877 ($($name:ident),* $(,)?) => {
1878 $(
1879 #[test]
1880 fn $name() -> ::core::result::Result<(), $crate::Violation> {
1881 $crate::__private::block_on($crate::__private::rules::$name(__conformance_fixture))?
1882 .report(::core::stringify!($name));
1883 Ok(())
1884 }
1885 )*
1886 };
1887}
1888
1889/// Emits one `#[wasm_bindgen_test]` per sync rule.
1890///
1891/// The caller's crate needs `wasm-bindgen-test` in its `dev-dependencies`,
1892/// gated on `cfg(target_arch = "wasm32")`. A skip is logged through
1893/// `console_log!` rather than reported on stdout, which writes nowhere on that
1894/// target — the event-store family's `emit_wasm` says why at length.
1895#[macro_export]
1896macro_rules! emit_sync_wasm {
1897 ($($name:ident),* $(,)?) => {
1898 $(
1899 #[::wasm_bindgen_test::wasm_bindgen_test]
1900 async fn $name() -> ::core::result::Result<(), $crate::Violation> {
1901 let __outcome = $crate::__private::rules::$name(__conformance_fixture).await?;
1902 if let Some(__line) = __outcome.skip_line(::core::stringify!($name)) {
1903 ::wasm_bindgen_test::console_log!("{}", __line);
1904 }
1905 Ok(())
1906 }
1907 )*
1908 };
1909}
1910
1911/// Expands to a `[&str; N]` of the rule names, for the orphan meta-test.
1912///
1913/// Not an emitter and not promised; exported only because `macro_rules!` has no
1914/// other way to reach another crate's tests.
1915#[doc(hidden)]
1916#[macro_export]
1917macro_rules! __sync_rule_names {
1918 ($($name:ident),* $(,)?) => { [ $( ::core::stringify!($name) ),* ] };
1919}
1920
1921/// Every `pub async fn` declared at the top level of this file's `rules`
1922/// module — the same four-space prefix `cargo xtask spec-trace` reads.
1923#[cfg(test)]
1924fn declared_rules() -> Vec<&'static str> {
1925 const SOURCE: &str = include_str!("sync_suite.rs");
1926 const PREFIX: &str = " pub async fn ";
1927
1928 SOURCE
1929 .lines()
1930 .filter_map(|line| line.strip_prefix(PREFIX))
1931 .filter_map(|rest| {
1932 rest.split(|c: char| !c.is_alphanumeric() && c != '_')
1933 .next()
1934 })
1935 .collect()
1936}
1937
1938/// No rule exists without appearing in the enumeration, and none is
1939/// enumerated without existing — the event-store family's `no_orphan_rules`,
1940/// one family over.
1941#[cfg(test)]
1942#[test]
1943fn no_orphan_sync_rules() {
1944 let registered = crate::for_each_sync_peer_rule!(crate::__sync_rule_names);
1945 let declared = declared_rules();
1946
1947 assert!(
1948 !declared.is_empty(),
1949 "the source scan matched no rule at all"
1950 );
1951 let orphans: Vec<_> = declared
1952 .iter()
1953 .filter(|name| !registered.contains(*name))
1954 .collect();
1955 assert!(
1956 orphans.is_empty(),
1957 "these rules are absent from `for_each_sync_peer_rule!`, so no harness runs them: \
1958 {orphans:?}"
1959 );
1960 let missing: Vec<_> = registered
1961 .iter()
1962 .filter(|name| !declared.contains(*name))
1963 .collect();
1964 assert!(
1965 missing.is_empty(),
1966 "these rules are registered but not declared in `sync_suite.rs`: {missing:?}"
1967 );
1968}