happenstance_core/append.rs
1//! The append condition: DCB's consistency mechanism.
2
3use alloc::boxed::Box;
4use alloc::vec::Vec;
5
6use crate::event::SequencePosition;
7use crate::query::Query;
8
9/// The consistency boundary an append is checked against.
10///
11/// This is the whole point of DCB. Rather than locking an aggregate, a command
12/// handler declares *what it looked at* when it made its decision. The store
13/// then refuses the append if anything matching that description has landed
14/// since — which is precisely the set of writes that could have changed the
15/// decision.
16///
17/// A condition is a non-empty sequence of [`Guard`]s, each pairing a query with
18/// its own boundary. The store **must** reject the append if **any** guard is
19/// violated — that is, if the store holds an event matching that guard's query
20/// at a position strictly greater than that guard's `after`. A guard whose
21/// `after` is `None` is violated by any match at all.
22///
23/// Most conditions have exactly one guard, which is what
24/// [`new`](Self::new) builds and what every example below shows. More than one
25/// is for a decision model assembled from fragments read separately: four reads
26/// produce four boundaries, and there is no single boundary that is correct for
27/// all four.
28///
29/// # A claim about one store's log, not about the world
30///
31/// A condition is evaluated against the events the evaluating store still
32/// holds, and against nothing else. A conditional append is therefore sound
33/// only where that store holds **every** event the condition's query ranges
34/// over, and the contract promises nothing beyond that.
35///
36/// Where matching history has been removed (pruned, archived, truncated, or
37/// never replicated here) the store MAY admit an append it would otherwise have
38/// rejected. That MAY is the caller's reading: a caller must not rely on a
39/// refusal. A conformant store admits: the condition passes **vacuously**,
40/// because the information is missing from the store, not merely from the API,
41/// and a pruned store and a young one are the same value at every seam of this
42/// port. The testkit's `condition_over_removed_history_does_not_reject` (ES-40)
43/// checks it, requiring the append once the condition's only match is removed.
44///
45/// The sharp consequence is for replication: re-evaluating an origin's condition
46/// against a partial local log answers "nothing matched" for history that exists
47/// elsewhere, and a decision taken on that answer may miss the events it names.
48///
49/// # The usual shape
50///
51/// A command handler reads with some query, notes the last position it saw, and
52/// appends with the *same* query and that position:
53///
54/// ```
55/// # use happenstance_core::{AppendCondition, Query, QueryItem, Tags};
56/// let query = Query::from_item(QueryItem::of_types(["StudentSubscribed"])?);
57///
58/// // ... read with `query`, ending at `last_seen` ...
59/// let last_seen = None; // nothing matched
60///
61/// let condition = AppendCondition::new(query).after_every_guard_opt(last_seen);
62/// # Ok::<(), Box<dyn core::error::Error>>(())
63/// ```
64///
65/// # Examples
66///
67/// Asserting that a course has never been defined — the classic uniqueness
68/// check, expressed without an aggregate:
69///
70/// ```
71/// use happenstance_core::{AppendCondition, Query, QueryItem, Tags};
72///
73/// let condition = AppendCondition::new(Query::from_item(QueryItem::new(
74/// ["CourseDefined"],
75/// Tags::from_pairs([("course", "c1")])?,
76/// )?));
77///
78/// assert_eq!(condition.guards().len(), 1);
79/// assert!(condition.guards()[0].after.is_none());
80/// # Ok::<(), Box<dyn core::error::Error>>(())
81/// ```
82///
83/// Two fragments read separately, each carrying its own boundary — the shape a
84/// `min(p₁, p₂)` collapse gets wrong:
85///
86/// ```
87/// use happenstance_core::{AppendCondition, Query, QueryItem, SequencePosition};
88///
89/// let busy = Query::from_item(QueryItem::of_types(["MeterReadingTaken"])?);
90/// let quiet = Query::from_item(QueryItem::of_types(["TariffPublished"])?);
91///
92/// let condition = AppendCondition::new(busy)
93/// .after_every_guard_opt(SequencePosition::new(9_000))
94/// .and_guard(quiet, SequencePosition::new(12));
95///
96/// assert_eq!(condition.guards().len(), 2);
97/// // The quiet fragment's stale boundary does not govern the busy one.
98/// assert_eq!(condition.guards()[0].after, SequencePosition::new(9_000));
99/// assert_eq!(condition.guards()[1].after, SequencePosition::new(12));
100/// # Ok::<(), Box<dyn core::error::Error>>(())
101/// ```
102#[derive(Debug, Clone, PartialEq, Eq)]
103#[non_exhaustive]
104pub struct AppendCondition {
105 // Private, and this is the one place the shape is stricter than it looks
106 // like it needs to be. `#[non_exhaustive]` blocks the struct-literal
107 // *expression* and exhaustive matching; it does **not** block assignment to
108 // a public field of a value the caller already owns. With a public field,
109 // one line of safe downstream code —
110 //
111 // let mut c = AppendCondition::new(q);
112 // c.guards = Box::new([]);
113 //
114 // — builds a condition with no guards, which nothing can ever violate. That
115 // is a conditional append that is silently unconditional: a lost update,
116 // with no diagnostic anywhere. The accessor below keeps the read that an
117 // ingest policy needs and removes the expression that reaches zero guards.
118 guards: Box<[Guard]>,
119}
120
121/// One clause of an [`AppendCondition`]: a query and the boundary it is checked
122/// from.
123///
124/// `#[non_exhaustive]` with public fields, which is a deliberate asymmetry
125/// rather than an oversight: a replication hub must be able to **read** `after`
126/// on a peer-supplied condition in order to refuse it, and must not be able to
127/// **fabricate** one. Downstream, `Guard { query, .. }` in a pattern and
128/// `guard.after` as a read both compile; `Guard { query, after }` as an
129/// expression is `error[E0639]`.
130#[derive(Debug, Clone, PartialEq, Eq)]
131#[non_exhaustive]
132pub struct Guard {
133 /// The append is rejected if the store holds any event matching this.
134 pub query: Query,
135 /// Restricts this guard to events *after* this position, exclusive.
136 ///
137 /// `None` checks the entire log. Set it to the last position the caller
138 /// observed *for this query*, so that events it already accounted for do
139 /// not reject its own append.
140 pub after: Option<SequencePosition>,
141}
142
143impl AppendCondition {
144 /// A condition with one unbounded guard, checking the whole log.
145 #[must_use]
146 pub fn new(fail_if_events_match: Query) -> Self {
147 Self {
148 guards: Box::new([Guard {
149 query: fail_if_events_match,
150 after: None,
151 }]),
152 }
153 }
154
155 /// Adds a guard with its own boundary.
156 ///
157 /// This is what makes the specification's advice to "issue one read per
158 /// fragment" sound. Four reads produce four boundaries, and collapsing them
159 /// to `min(p₁…p₄)` — the obvious application-side workaround — means the
160 /// quietest fragment's stale boundary governs the busiest one, so a busy
161 /// consistency boundary rejects appends that never conflicted and the
162 /// deployment reads the rejection rate as contention.
163 ///
164 /// A later `after_every_guard` or `after_every_guard_opt` **erases** the
165 /// `after` given here, because each rewrites every guard already present:
166 /// call them before `and_guard`, never after.
167 ///
168 /// Allocation note, since this is the trade a reader coming from a language
169 /// with a growable list will not expect: `guards` is a boxed slice, which
170 /// carries no spare capacity, so this unboxes, pushes and re-boxes. A chain
171 /// of *n* calls is quadratic in allocation. For the counts this exists to
172 /// serve — four in the worked case — that is the right side of the trade
173 /// against carrying capacity in every cloned condition forever.
174 #[must_use]
175 pub fn and_guard(self, query: Query, after: Option<SequencePosition>) -> Self {
176 let mut guards = Vec::from(self.guards);
177 guards.push(Guard { query, after });
178 Self {
179 guards: guards.into_boxed_slice(),
180 }
181 }
182
183 /// The guards, in the order they were added. Never empty.
184 #[must_use]
185 pub fn guards(&self) -> &[Guard] {
186 &self.guards
187 }
188
189 /// Restricts **every** guard to events after `position`, exclusive, erasing
190 /// any boundary `and_guard` set: `after_every_guard_opt(Some(position))`.
191 #[must_use]
192 pub fn after_every_guard(self, position: SequencePosition) -> Self {
193 self.after_every_guard_opt(Some(position))
194 }
195
196 /// Restricts **every** guard to events after `position`, exclusive, or
197 /// checks the whole log when `position` is `None`.
198 ///
199 /// The `Option`-taking form exists because callers usually hold the last
200 /// position they read, which is `None` when their query matched nothing.
201 ///
202 /// Applying to every guard is what keeps a single-guard condition — the
203 /// shape every existing caller builds — behaving exactly as it always has.
204 /// For per-guard boundaries, use [`and_guard`](Self::and_guard). Called
205 /// **after** `and_guard`, this **erases** the boundary it attached, so a
206 /// quiet guard takes `position` and the condition tolerates more.
207 #[must_use]
208 pub fn after_every_guard_opt(self, position: Option<SequencePosition>) -> Self {
209 let mut guards = self.guards;
210 guards.iter_mut().for_each(|guard| guard.after = position);
211 Self { guards }
212 }
213
214 /// Whether an event at `position` with this type and these tags would
215 /// violate the condition.
216 ///
217 /// Violated if **any** guard is violated — the guards are a conjunction of
218 /// constraints, so one broken clause rejects the append.
219 ///
220 /// Adapters should push this down into storage; this is the reference
221 /// definition the conformance suite holds them to. An adapter generating SQL
222 /// must parenthesise each guard explicitly — `(item AND position > p) OR …`
223 /// — because the precedence bug that already threatens the single-boundary
224 /// form becomes *n* times more likely here.
225 pub fn is_violated_by(
226 &self,
227 position: SequencePosition,
228 event_type: &crate::EventType,
229 tags: &crate::Tags,
230 ) -> bool {
231 self.guards
232 .iter()
233 .any(|guard| guard.is_violated_by(position, event_type, tags))
234 }
235}
236
237impl Guard {
238 /// Whether an event at `position` would violate this guard alone.
239 pub fn is_violated_by(
240 &self,
241 position: SequencePosition,
242 event_type: &crate::EventType,
243 tags: &crate::Tags,
244 ) -> bool {
245 // Written as a match rather than a let-chain because the two arms read
246 // as the two rules they are, not because the floor forbids one: ADR-0029
247 // raised the MSRV to 1.97.1 and let-chains have been available since
248 // 1.88.
249 match self.after {
250 Some(after) if position <= after => false,
251 _ => self.query.matches(event_type, tags),
252 }
253 }
254}
255
256#[cfg(feature = "serde")]
257mod serde_impls {
258 use super::{AppendCondition, Guard};
259 use crate::event::SequencePosition;
260 use crate::query::Query;
261 use alloc::vec::Vec;
262 use serde::{Deserialize, Deserializer, Serialize, Serializer};
263
264 /// Field-for-field mirror of [`Guard`]. Both fields are written on every
265 /// serialisation and neither may stop being (WF-2; ADR-0016 §3).
266 ///
267 /// WF-4 as amended by ADR-0016 §2: the MUST is about the **presence** of the
268 /// two fields, not their spelling. VT-30 moved the query boundary into
269 /// `Guard`, so the wire field is `query`, and the clause's older name for it
270 /// no longer exists to be checked.
271 ///
272 /// **Neither `query` here nor `guards` on `Wire` may take
273 /// `#[serde(default)]`.** Their absence is the whole mechanism: now that
274 /// `Query` is externally tagged, `{"guards":[{}]}` fails with ``missing
275 /// field `query` `` and `{"guards":[{"query":null}]}` with `expected value`.
276 /// Before, both decoded to a guard that matches everything since the
277 /// beginning of the log — the one append condition that can never fail, and
278 /// therefore a silent lost update. "Add a default so `{}` parses" is exactly
279 /// the patch that restores it, and it will look like a kindness.
280 ///
281 /// `after` is different and is left as it is: serde routes an absent
282 /// `Option` through `missing_field` with no attribute at all, so
283 /// `{"guards":[{"query":"All"}]}` still decodes to `after: None`. ADR-0016
284 /// §5 accepts that, because `None` checks the *whole* log and so fails
285 /// closed — a spurious rejection, never a spurious acceptance.
286 #[derive(Serialize, Deserialize)]
287 #[serde(rename = "Guard")]
288 struct GuardWire {
289 query: Query,
290 after: Option<SequencePosition>,
291 }
292
293 #[derive(Serialize, Deserialize)]
294 #[serde(rename = "AppendCondition")]
295 struct Wire {
296 guards: Vec<GuardWire>,
297 }
298
299 /// The borrowing counterpart of [`GuardWire`], used on the way **out**.
300 ///
301 /// Same `rename`, same two fields in the same order. `&Query` serialises
302 /// through the blanket `impl Serialize for &T`, which forwards to `Query`'s
303 /// own impl, so the bytes are unchanged; what goes is `guard.query.clone()`,
304 /// which deep-cloned every `QueryItem` in the guard.
305 #[derive(Serialize)]
306 #[serde(rename = "Guard")]
307 struct GuardRef<'a> {
308 query: &'a Query,
309 after: Option<SequencePosition>,
310 }
311
312 /// The guard sequence, written straight from the slice.
313 ///
314 /// A hand-written `Serialize` rather than a `Vec<GuardRef<'_>>` field on a
315 /// borrowing [`Wire`], because a `Vec` would be one allocation this does not
316 /// need. `collect_seq` takes the length from the iterator's `size_hint`,
317 /// which a slice iterator supplies exactly, so postcard writes the same
318 /// length prefix the `Vec` wrote.
319 struct GuardsRef<'a>(&'a [Guard]);
320
321 impl Serialize for GuardsRef<'_> {
322 fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
323 serializer.collect_seq(self.0.iter().map(|guard| GuardRef {
324 query: &guard.query,
325 after: guard.after,
326 }))
327 }
328 }
329
330 /// The borrowing counterpart of [`Wire`].
331 #[derive(Serialize)]
332 #[serde(rename = "AppendCondition")]
333 struct WireRef<'a> {
334 guards: GuardsRef<'a>,
335 }
336
337 impl Serialize for AppendCondition {
338 fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
339 WireRef {
340 guards: GuardsRef(self.guards()),
341 }
342 .serialize(serializer)
343 }
344 }
345
346 impl<'de> Deserialize<'de> for AppendCondition {
347 /// Rejects an empty guard sequence.
348 ///
349 /// Deserialisation is the other door into the private field, and a
350 /// validity invariant that the constructor enforces and the decoder does
351 /// not is not an invariant. An empty condition decoded from a peer would
352 /// be a condition nothing can violate — the same silent lost update the
353 /// private field exists to prevent, arriving over the wire instead of
354 /// through an assignment.
355 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
356 let wire = Wire::deserialize(deserializer)?;
357 if wire.guards.is_empty() {
358 return Err(serde::de::Error::custom(
359 "an append condition must carry at least one guard",
360 ));
361 }
362 let guards = wire
363 .guards
364 .into_iter()
365 .map(|guard| Guard {
366 query: guard.query,
367 after: guard.after,
368 })
369 .collect::<Vec<_>>();
370 Ok(Self {
371 guards: guards.into_boxed_slice(),
372 })
373 }
374 }
375}
376
377/// The two spellings ADR-0054 renamed, kept through 1.x.
378///
379/// A separate `impl` block, after everything else, so that adding them moved no
380/// line a citation names. Each forwards to the name that says its scope.
381impl AppendCondition {
382 /// Restricts **every** guard to events after `position`, exclusive.
383 ///
384 /// Renamed [`after_every_guard`](Self::after_every_guard), because the old
385 /// name did not say that it overwrites the boundary of every guard already
386 /// present. The behaviour is identical, and this spelling is kept through
387 /// 1.x.
388 #[deprecated(
389 since = "0.4.2",
390 note = "use `after_every_guard`, which names its scope; `after` is kept through 1.x"
391 )]
392 #[must_use]
393 pub fn after(self, position: SequencePosition) -> Self {
394 self.after_every_guard(position)
395 }
396
397 /// Restricts **every** guard to events after `position`, exclusive, or
398 /// checks the whole log when `position` is `None`.
399 ///
400 /// Renamed [`after_every_guard_opt`](Self::after_every_guard_opt), because
401 /// the old name did not say its scope. Called **after**
402 /// [`and_guard`](Self::and_guard), it **erases** the boundary `and_guard`
403 /// attached, moving a quiet guard's boundary to `position` and widening what
404 /// the condition tolerates. The behaviour is identical, and this spelling is
405 /// kept through 1.x.
406 #[deprecated(
407 since = "0.4.2",
408 note = "use `after_every_guard_opt`, which names its scope; `after_opt` is kept through 1.x"
409 )]
410 #[must_use]
411 pub fn after_opt(self, position: Option<SequencePosition>) -> Self {
412 self.after_every_guard_opt(position)
413 }
414}
415
416#[cfg(test)]
417mod tests {
418 #![allow(clippy::unwrap_used)]
419
420 use super::*;
421 use crate::{EventType, QueryItem, Tags};
422
423 fn pos(value: u64) -> SequencePosition {
424 SequencePosition::new(value).unwrap()
425 }
426
427 fn ty(value: &str) -> EventType {
428 EventType::new(value).unwrap()
429 }
430
431 #[test]
432 fn without_after_any_match_violates() {
433 let condition = AppendCondition::new(Query::from_item(QueryItem::of_types(["A"]).unwrap()));
434
435 assert!(condition.is_violated_by(pos(1), &ty("A"), &Tags::empty()));
436 assert!(!condition.is_violated_by(pos(1), &ty("B"), &Tags::empty()));
437 }
438
439 #[test]
440 fn after_is_exclusive() {
441 let condition = AppendCondition::new(Query::from_item(QueryItem::of_types(["A"]).unwrap()))
442 .after_every_guard(pos(5));
443
444 // Strictly before the boundary: already accounted for.
445 assert!(!condition.is_violated_by(pos(4), &ty("A"), &Tags::empty()));
446 // Exactly at the boundary: also already accounted for — `after` is exclusive.
447 assert!(!condition.is_violated_by(pos(5), &ty("A"), &Tags::empty()));
448 // Strictly after: a write the caller never saw.
449 assert!(condition.is_violated_by(pos(6), &ty("A"), &Tags::empty()));
450 }
451
452 #[test]
453 fn non_matching_events_after_the_boundary_are_ignored() {
454 let condition = AppendCondition::new(Query::from_item(QueryItem::of_types(["A"]).unwrap()))
455 .after_every_guard(pos(5));
456
457 assert!(!condition.is_violated_by(pos(99), &ty("B"), &Tags::empty()));
458 }
459
460 fn of_type(value: &str) -> Query {
461 Query::from_item(QueryItem::of_types([value]).unwrap())
462 }
463
464 fn boundaries(condition: &AppendCondition) -> Vec<Option<SequencePosition>> {
465 condition.guards().iter().map(|guard| guard.after).collect()
466 }
467
468 /// ADR-0054's first pin: the hazardous order. A blanket setter called after
469 /// `and_guard` overwrites the boundary `and_guard` attached, so the quiet
470 /// guard's `p2` becomes `p1`. The wrong implementation it rejects fills only
471 /// guards whose `after` is `None`, which would leave `[p1, p2]`.
472 #[test]
473 fn after_every_guard_after_and_guard_overwrites_every_boundary() {
474 let condition = AppendCondition::new(of_type("A"))
475 .and_guard(of_type("B"), Some(pos(2)))
476 .after_every_guard(pos(1));
477
478 assert_eq!(boundaries(&condition), [Some(pos(1)), Some(pos(1))]);
479
480 let cleared = AppendCondition::new(of_type("A"))
481 .and_guard(of_type("B"), Some(pos(2)))
482 .after_every_guard_opt(None);
483
484 assert_eq!(boundaries(&cleared), [None, None]);
485 }
486
487 /// ADR-0054's second pin: the safe order. The blanket setter before any
488 /// `and_guard` leaves each later guard with the boundary it was given.
489 #[test]
490 fn after_every_guard_opt_before_and_guard_keeps_boundaries_independent() {
491 let condition = AppendCondition::new(of_type("A"))
492 .after_every_guard_opt(Some(pos(9_000)))
493 .and_guard(of_type("B"), Some(pos(12)))
494 .and_guard(of_type("C"), None);
495
496 assert_eq!(
497 boundaries(&condition),
498 [Some(pos(9_000)), Some(pos(12)), None]
499 );
500 }
501
502 /// The deprecated spellings are kept through 1.x with the same behaviour,
503 /// so they are pinned on the same hazardous order as their replacements.
504 #[test]
505 #[expect(
506 deprecated,
507 reason = "pins `after` and `after_opt`, which ADR-0054 deprecates and keeps through 1.x"
508 )]
509 fn deprecated_after_and_after_opt_still_overwrite_every_guard() {
510 let hazardous = || AppendCondition::new(of_type("A")).and_guard(of_type("B"), Some(pos(2)));
511
512 assert_eq!(
513 hazardous().after(pos(1)),
514 hazardous().after_every_guard(pos(1))
515 );
516 assert_eq!(boundaries(&hazardous().after(pos(1))), [Some(pos(1)); 2]);
517 assert_eq!(
518 hazardous().after_opt(Some(pos(1))),
519 hazardous().after_every_guard_opt(Some(pos(1)))
520 );
521 assert_eq!(boundaries(&hazardous().after_opt(None)), [None, None]);
522 }
523}