Skip to main content

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}