Skip to main content

happenstance_core/
limits.rs

1//! Capacity floors every store must clear, and the name a store uses when it
2//! refuses beyond one.
3//!
4//! These are **floors, never ceilings** (VT-21 – VT-24). A single
5//! `MAX_EVENT_DATA_LEN` would be either a straitjacket on Postgres — which will
6//! hold a 340 KB seat map without noticing — or a lie on a KV-backed peer that
7//! cannot hold it at all, and freezing one at 0.1 would fix the number for
8//! good. A floor instead tells an application what it may write and still
9//! expect to replicate, and gives the sync layer something to compare a peer's
10//! declared limit against *before* it starts pushing.
11//!
12//! A store MAY accept more than any floor here, MUST document what it actually
13//! accepts, and MUST refuse beyond that with
14//! [`AppendError::ExceedsStoreLimit`](crate::AppendError::ExceedsStoreLimit)
15//! rather than by truncating.
16//!
17//! # What the floors cost together
18//!
19//! **VT-21, VT-22 and VT-24 are three SIMULTANEOUS obligations, not three
20//! independent ones.** A conformant store has to satisfy all of them at once, so
21//! the smallest append it must accept is their *product* — and that product is
22//! nowhere in the specification, because each clause states one factor.
23//!
24//! At the floors below, one append carries:
25//!
26//! | factor | arithmetic | bytes |
27//! | --- | --- | --- |
28//! | `data` | 128 × 65,536 | 8,388,608 |
29//! | tags | 128 × 64 × 255 | 2,088,960 |
30//! | event types | 128 × 255 | 32,640 |
31//! | `metadata` | unbounded | — |
32//!
33//! The first two factors of the tags row, 128 × 64, are
34//! [`MIN_SUPPORTED_TAGS_PER_BATCH`]: the total tag count one append must carry,
35//! which a store may also declare a ceiling on (VT-36).
36//!
37//! So **the composed floor has a stated lower bound of 10,510,208 bytes and no
38//! upper bound**, and `[FROZEN]` ES-18 makes the whole of it one atomic unit:
39//! every event of that append lands, or none does.
40//!
41//! That is worth knowing before choosing a backing store. It is larger than a
42//! `FoundationDB` transaction and past `DynamoDB`'s `TransactWriteItems` budget
43//! a store in either family cannot be conformant at these floors, and the place
44//! to discover that is here rather than in production.
45//!
46//! [`MIN_SUPPORTED_EVENTS_PER_BATCH`] already does this multiplication once, and
47//! the contrast between the two is the point: that one multiplies into *bound
48//! parameters*, an axis SQLite's driver forced somebody to compute. This one
49//! multiplies into *bytes*, an axis nothing forced — which is why it went
50//! uncomputed until the release that published these numbers.
51
52/// Smallest `data` payload every store must accept, in bytes.
53///
54/// The tightest target in the plan is the Cloudflare Durable Object, whose
55/// legacy KV-backed form caps a value at 128 KiB — this clears it with room for
56/// the envelope.
57pub const MIN_SUPPORTED_EVENT_DATA_LEN: usize = 65_536;
58
59/// Smallest number of tags on one event every store must accept.
60///
61/// The richest event in the six worked scenarios carries eight.
62pub const MIN_SUPPORTED_TAGS_PER_EVENT: usize = 64;
63
64/// Smallest number of query items every store must be able to evaluate.
65///
66/// The largest decision model in the six worked scenarios uses four.
67pub const MIN_SUPPORTED_QUERY_ITEMS: usize = 128;
68
69/// Smallest number of events in one append every store must accept.
70///
71/// Worth doing the multiplication once, because two floors meet here and an
72/// adapter inherits the product rather than either factor. A multi-row tag
73/// insert at these floors binds `128 × 64 × 3 = 24,576` parameters, against
74/// SQLite's `SQLITE_MAX_VARIABLE_NUMBER` of 32,766 — leaving 8,190 for the
75/// event rows themselves. The pair fits, with 23% headroom rather than the 41%
76/// a hundred-event batch would have implied, so an adapter that binds one extra
77/// parameter per tag is within a factor of 1.3 of the ceiling.
78pub const MIN_SUPPORTED_EVENTS_PER_BATCH: usize = 128;
79
80/// Smallest total number of tags, summed over every event of one append, every
81/// store must accept (VT-36).
82///
83/// Not a new obligation. VT-22 and VT-24 hold at once, so a store already
84/// accepts 128 events of 64 tags each, and this constant is that product
85/// written down. It exists so that a store which bounds the transaction rather
86/// than any one event has a floor to declare its ceiling against: such a store
87/// may refuse a larger total, as
88/// [`StoreLimit::TagsPerBatch`], and never a smaller one.
89///
90/// Written as the product rather than the literal `8_192` so the two floors
91/// that define it cannot drift away from it; a unit test pins the literal.
92pub const MIN_SUPPORTED_TAGS_PER_BATCH: usize =
93    MIN_SUPPORTED_EVENTS_PER_BATCH * MIN_SUPPORTED_TAGS_PER_EVENT;
94
95/// Which capacity limit an append exceeded.
96///
97/// Five variants, and no `QueryItems`: a query-item refusal is not an append
98/// outcome, so that variant would name a refusal no `append` could produce, and
99/// a store that will not evaluate a large query fails it through its own error.
100/// [`MetadataLen`](Self::MetadataLen) is the one variant with no floor behind
101/// it (ADR-0043): a refusal channel, with no capacity guaranteed.
102///
103/// # The variant this enum does not have
104///
105/// Every variant here but one names **one factor**. The exception,
106/// [`TagsPerBatch`](Self::TagsPerBatch), is a batch-scope *count* (ADR-0100).
107/// None of them can express a refusal of the batch's *total size in bytes* —
108/// the product the module documentation works out above — and that is the
109/// refusal a store in the `FoundationDB` or `DynamoDB` family would need,
110/// because what those systems bound is the transaction's bytes rather than any
111/// one row in it or any one count across it.
112///
113/// Such a store cannot route the refusal elsewhere either: `[FROZEN]` VT-25
114/// forbids reporting a capacity refusal through
115/// [`AppendError::Store`](crate::AppendError::Store), which is the channel it
116/// would otherwise reach for.
117///
118/// This enum is `#[non_exhaustive]`, so a variant for it is additive at **any**
119/// time and is not owed to a release. Naming the gap is what is owed now: the
120/// decision it waits on is what floor such a variant would state, and no
121/// adapter in this workspace is in that family to inform the number.
122#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
123#[non_exhaustive]
124pub enum StoreLimit {
125    /// One event's `data` payload was larger than the store accepts.
126    EventDataLen,
127    /// One event carried more tags than the store accepts.
128    TagsPerEvent,
129    /// The batch held more events than the store accepts in one append.
130    EventsPerBatch,
131    /// One event's `metadata` was larger than the store accepts.
132    ///
133    /// Distinct from [`EventDataLen`](Self::EventDataLen), which is about
134    /// `data` alone: a store refusing an event for its metadata and naming
135    /// `EventDataLen` would be naming the wrong field. Its
136    /// [`guaranteed_minimum`](Self::guaranteed_minimum) is `0`, because the
137    /// contract guarantees no metadata capacity (ADR-0043). Whether `data` and
138    /// `metadata` should share one budget instead is open, and is phase 13's.
139    MetadataLen,
140    /// The batch carried more tags in total, summed over all its events, than
141    /// the store accepts in one append.
142    ///
143    /// Distinct from [`TagsPerEvent`](Self::TagsPerEvent): every event of the
144    /// batch may be within its own ceiling while their sum is not. Its
145    /// [`guaranteed_minimum`](Self::guaranteed_minimum) is
146    /// [`MIN_SUPPORTED_TAGS_PER_BATCH`], which VT-22 and VT-24 already imply
147    /// (VT-36, ADR-0100). A batch refused for it can be split and retried; one
148    /// refused for a per-event limit cannot.
149    TagsPerBatch,
150}
151
152impl StoreLimit {
153    /// The floor every store must clear for this limit.
154    ///
155    /// A caller that has hit a store's actual limit can compare against this to
156    /// tell "this store is stricter than the contract allows" — a conformance
157    /// bug — from "this payload was always going to be too big to replicate".
158    ///
159    /// For [`MetadataLen`](Self::MetadataLen) it is `0`, so that comparison
160    /// can never report a conformance bug: no metadata capacity is guaranteed.
161    #[must_use]
162    pub const fn guaranteed_minimum(self) -> usize {
163        match self {
164            Self::EventDataLen => MIN_SUPPORTED_EVENT_DATA_LEN,
165            Self::TagsPerEvent => MIN_SUPPORTED_TAGS_PER_EVENT,
166            Self::EventsPerBatch => MIN_SUPPORTED_EVENTS_PER_BATCH,
167            Self::MetadataLen => 0,
168            Self::TagsPerBatch => MIN_SUPPORTED_TAGS_PER_BATCH,
169        }
170    }
171}
172
173impl core::fmt::Display for StoreLimit {
174    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
175        let name = match self {
176            Self::EventDataLen => "event data length",
177            Self::TagsPerEvent => "tags per event",
178            Self::EventsPerBatch => "events per batch",
179            Self::MetadataLen => "metadata length",
180            Self::TagsPerBatch => "tags per batch",
181        };
182        f.write_str(name)
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::{
189        MIN_SUPPORTED_EVENT_DATA_LEN, MIN_SUPPORTED_EVENTS_PER_BATCH, MIN_SUPPORTED_TAGS_PER_BATCH,
190        MIN_SUPPORTED_TAGS_PER_EVENT, StoreLimit,
191    };
192
193    #[test]
194    fn every_limit_names_its_floor() {
195        assert_eq!(
196            StoreLimit::EventDataLen.guaranteed_minimum(),
197            MIN_SUPPORTED_EVENT_DATA_LEN
198        );
199        assert_eq!(
200            StoreLimit::TagsPerEvent.guaranteed_minimum(),
201            MIN_SUPPORTED_TAGS_PER_EVENT
202        );
203        assert_eq!(
204            StoreLimit::EventsPerBatch.guaranteed_minimum(),
205            MIN_SUPPORTED_EVENTS_PER_BATCH
206        );
207        assert_eq!(
208            StoreLimit::TagsPerBatch.guaranteed_minimum(),
209            MIN_SUPPORTED_TAGS_PER_BATCH
210        );
211    }
212
213    /// VT-36: the tags-per-batch floor is not a new obligation. It is the
214    /// product VT-22 and VT-24 already impose together, held to a literal so
215    /// that raising either factor fails here, beside the prose that quotes it.
216    #[test]
217    fn the_tags_per_batch_floor_is_two_floors() {
218        assert_eq!(MIN_SUPPORTED_TAGS_PER_BATCH, 8_192);
219        assert_eq!(
220            MIN_SUPPORTED_TAGS_PER_BATCH,
221            MIN_SUPPORTED_EVENTS_PER_BATCH * MIN_SUPPORTED_TAGS_PER_EVENT
222        );
223    }
224
225    #[test]
226    fn tags_per_batch_names_itself() {
227        assert_eq!(StoreLimit::TagsPerBatch.to_string(), "tags per batch");
228    }
229
230    /// ADR-0043: the metadata channel is a refusal path with no floor, so a
231    /// store may refuse one byte of metadata and still be conformant.
232    #[test]
233    fn metadata_len_guarantees_no_capacity() {
234        assert_eq!(StoreLimit::MetadataLen.guaranteed_minimum(), 0);
235        assert_eq!(StoreLimit::MetadataLen.to_string(), "metadata length");
236    }
237
238    /// The composed floor is the number the module documentation states.
239    ///
240    /// Held to a literal rather than recomputed from the constants, on the same
241    /// argument as its sibling below: the value of this test is that raising any
242    /// floor fails HERE, beside the prose that quotes the total, rather than at
243    /// an adapter that discovers it cannot hold one append.
244    #[test]
245    fn the_three_floors_compose_to_a_stated_number() {
246        let data = MIN_SUPPORTED_EVENTS_PER_BATCH * MIN_SUPPORTED_EVENT_DATA_LEN;
247        let tags =
248            MIN_SUPPORTED_EVENTS_PER_BATCH * MIN_SUPPORTED_TAGS_PER_EVENT * crate::MAX_TAG_LEN;
249        let types = MIN_SUPPORTED_EVENTS_PER_BATCH * crate::MAX_EVENT_TYPE_LEN;
250
251        assert_eq!(data, 8_388_608);
252        assert_eq!(tags, 2_088_960);
253        assert_eq!(types, 32_640);
254        assert_eq!(
255            data + tags + types,
256            10_510_208,
257            "the module documentation states this total, and ES-18 makes the \
258             whole of it one atomic unit. If this moved, a conformant store's \
259             smallest guaranteed append moved with it"
260        );
261    }
262
263    #[test]
264    fn the_two_floors_fit_inside_sqlites_parameter_ceiling() {
265        // The arithmetic in `MIN_SUPPORTED_EVENTS_PER_BATCH`'s docs, asserted so
266        // that raising either floor fails here rather than at an adapter's
267        // write path in phase 8.
268        const SQLITE_MAX_VARIABLE_NUMBER: usize = 32_766;
269        let tag_parameters = MIN_SUPPORTED_EVENTS_PER_BATCH * MIN_SUPPORTED_TAGS_PER_EVENT * 3;
270        assert_eq!(tag_parameters, 24_576);
271        assert!(tag_parameters < SQLITE_MAX_VARIABLE_NUMBER);
272    }
273}