ingraph_codegen/aggregate.rs
1//! The AGGREGATE declaration's model — the three parts every aggregation has, read off a grammar
2//! and held until the emission arrives.
3//!
4//! ```ignore
5//! #[ingraph::aggregate(
6//! upstream(node = "demux::Track"),
7//! group(codec = "codec"),
8//! measure(count = counting, bytes(fold = summing, from = "size")),
9//! poll(recount, every = "10m", light),
10//! sqlite,
11//! )]
12//! pub struct CodecCensus {
13//! #[ingraph(group)] codec: Codec,
14//! #[ingraph(measure)] count: ingraph::Count,
15//! #[ingraph(measure)] bytes: u64,
16//! }
17//! ```
18//!
19//! # The grammar NAMES the sentence, and the sentence is `SELECT count(*) FROM t GROUP BY codec`
20//!
21//! `upstream(…)` is the `FROM`, [`GROUP`] is the `GROUP BY`, and [`MEASURE`] is the aggregate
22//! functions. The two words beside them are the ones SQL has no room for and a running system
23//! cannot do without: the CLOCK that decides when the answer is recomputed, and the STORE the
24//! answer lands in.
25//!
26//! # It consumes TABLES rather than messages, which is the whole safety argument
27//!
28//! The framework's delivery correctness is at-least-once plus keyed replace, so duplicates are
29//! NORMAL operation — fan-out clones per edge, a rewind re-delivering the unacked tail, a retry
30//! re-sending — and no app-visible message id exists to dedup on. An incremental `count += 1`
31//! cannot inherit that theorem. So a trigger reads the upstream's ROWS, groups them, folds each
32//! group and upserts one row per group: immune to duplicates by construction, self-healing on every
33//! tick, and deletion-correct for free, a removed upstream row simply ceasing to be counted.
34//!
35//! # THE MODEL IS HERE AND THE EMISSION IS BESIDE IT
36//!
37//! The grammar in `ingraph-derive` builds this model and every rule a declaration can break is
38//! refused there by name; the front end then MOUNTS it — the `(group…, measure…)` columns, keyed by
39//! the group projection, handed to the ordinary record pass — and hands both halves back as
40//! [`Mounted`], which is what expands. Sentences stay the front end's, sentences being the front
41//! end's; what belongs here is the model, and beside it in [`emit`] the one thing a record cannot
42//! say: what a group's rows fold into.
43
44/// The head block that names the GROUP columns, and the field marker that wears the same word.
45///
46/// ONE word in two positions, which is [`MEASURE`]'s shape too and the house's own: `searchable` is
47/// a full-text declaration's field marker and an entry inside a `vector`'s `knn(…)`, meaning the
48/// same thing in both. The block says WHERE a group column is read from, the marker says WHAT THE
49/// FIELD IS, and a declaration whose two halves disagree is refused by name rather than resolved by
50/// precedence.
51pub const GROUP: &str = "group";
52
53/// The head block that names the MEASURE columns, and the field marker that wears the same word.
54///
55/// The word `fold` was unavailable AS A BLOCK WORD — `semantics(fold(…))` is set-similarity
56/// combination, one grammar over — and the collective spelling the design sketch carried (`census`)
57/// was settled against the house register by the grammar task: every block word in this family
58/// names WHAT AN ENTRY IS (`upstream`, `lineage`, `poll`, `graphql`, `group`), never what the
59/// declaration as a whole amounts to, and a census is the whole. So the block takes the entry's own
60/// noun, and takes it in the singular, which is `upstream(<field> = "…")`'s rule for a block holding
61/// N entries.
62///
63/// **`fold` returns one grain in as a PROPERTY of an entry** — `measure(<field>(fold = …, from =
64/// "…"))` — and that is not the collision the block word dodged. A property word is read inside one
65/// entry of one block, where the set-similarity word is an entry of `semantics(…)`; neither reader
66/// can see the other's position, and what the word means in both is the same thing said about a
67/// different subject.
68pub const MEASURE: &str = "measure";
69
70/// A validated aggregate declaration.
71///
72/// PLAIN, for the reason every model in this crate has plain fields: the derive today and a
73/// manifest front end later reach the same emitter.
74///
75/// # Three fields are TOKENS, and the passthrough is the journal's law rather than laziness
76///
77/// [`triggers`](Self::triggers), [`stores`](Self::stores) and [`graphql`](Self::graphql) are the
78/// words this declaration shares with the RECORD grammar, and they are carried UNINTERPRETED. The
79/// aggregate's storage IS a record's — the emission mints the `(group…, measure…)` row shape and
80/// hands it to the record pass, which is `#[ingraph::journal]`'s pattern verbatim — so reading a
81/// database block, a `table = "…"` or a `poll(…)` entry here would be a SECOND authority for one
82/// vocabulary, and two authorities for one vocabulary is how the two of them drift.
83///
84/// What the front end knows about them is only which WORDS start one, which it needs anyway to
85/// refuse a declaration that names no clock. Their teeth arrive with the record pass, at the same
86/// expansion that spends them.
87#[derive(Debug, Clone)]
88pub struct AggregateModel {
89 /// The declaration's own name.
90 pub aggregate: syn::Ident,
91 /// The declaration's visibility, carried for the types the emission mints beside it.
92 pub vis: syn::Visibility,
93 /// Where `ingraph` lives, as `crate = "…"` named it or `::ingraph` where it named none.
94 pub krate: syn::Path,
95 /// The same, AS WRITTEN — the literal the record grammar is handed back when the emission mounts
96 /// this declaration as a record.
97 ///
98 /// Both halves are carried for `#[ingraph::journal]`'s stated reason: one authority for the path,
99 /// and no round trip through a rendered path that could differ from the one that was written.
100 pub krate_spelled: Option<syn::LitStr>,
101 /// `upstream(node = "…")` — the ONE node whose rows are folded.
102 ///
103 /// The edge and NOTHING ELSE, which is where this word differs from the derived indexes' spelling
104 /// of it: theirs carries the projection too, because a document is one upstream message and every
105 /// field of it is read out of that message. Here only the GROUP columns are read out of a row —
106 /// a measure's column is FOLDED into being — so a projection written inside `upstream(…)` would
107 /// claim a totality this kind does not have, and is refused pointing at [`GROUP`].
108 pub upstream: syn::Path,
109 /// The GROUP projection, in the order the declaration wrote its fields.
110 ///
111 /// Never empty: a declaration with no group is refused before a model is built. The key this kind
112 /// mints IS these columns, which is why a groupless aggregate has no shape here — it would be one
113 /// keyless row, and the record family stores rows by key.
114 pub groups: Vec<Grouped>,
115 /// The MEASURE columns, in the order the declaration wrote its fields. Never empty.
116 pub measures: Vec<Measured>,
117 /// Every `poll(…)` entry as written, comma-joined, ready to be handed to the record grammar.
118 ///
119 /// Never empty: an aggregate recomputes ON A TRIGGER, so a declaration naming no clock would
120 /// never run and its table would answer nothing, forever.
121 pub triggers: proc_macro2::TokenStream,
122 /// The store words and their two common entries as written, comma-joined — `sqlite`,
123 /// `postgres(schema = "…")`, `table = "…"`, `rename = "…"`.
124 ///
125 /// May be EMPTY, and the emptiness is answered by the record pass rather than here: *a thing that
126 /// holds rows names where they land* is the record grammar's sentence, and this grammar knowing
127 /// only which words START a store has nothing of its own to add to it.
128 pub stores: proc_macro2::TokenStream,
129 /// `graphql(…)` as written, or [`None`] where the declaration named no backend.
130 pub graphql: Option<proc_macro2::TokenStream>,
131}
132
133/// One GROUP column: a field of this declaration, and the upstream field it is read out of.
134#[derive(Debug, Clone)]
135pub struct Grouped {
136 /// The field of this declaration being filled.
137 pub field: syn::Ident,
138 /// The upstream field it is read out of, carrying the span of the string that named it — so
139 /// every claim the emission makes about the upstream lands where the author wrote it.
140 pub from: syn::Ident,
141 /// The field's declared type.
142 pub ty: syn::Type,
143 /// How an accessor hands this column back — the three projection words, read by the same walk
144 /// every tier with columns reads them with.
145 pub projection: crate::model::Projection,
146}
147
148/// One MEASURE column: a field of this declaration, what folds a group's rows into it, and the
149/// upstream column that fold is handed.
150#[derive(Debug, Clone)]
151pub struct Measured {
152 /// The field of this declaration being filled.
153 pub field: syn::Ident,
154 /// What folds the group into this column.
155 pub by: Measure,
156 /// The upstream column whose values the fold is handed, where the entry named one — carrying the
157 /// span of the string that named it, so every claim the emission makes about the upstream lands
158 /// where the author wrote it.
159 ///
160 /// # [`None`] is a FOLD OVER THE ROWS, and it is a shape rather than a gap
161 ///
162 /// A measure's `from` says WHICH values become the slice a fold is handed. Where it is written,
163 /// that slice is the named column's values; where it is not, the fold is handed the group's ROWS
164 /// — which is exactly what `counting` wants, answering how many there are about items of every
165 /// type there is.
166 ///
167 /// So the two states are two legal declarations and not a filled-or-missing seat, and which of
168 /// them a fold may take is [`Measure::owed`]'s answer: the grammar refuses `counting` a column and
169 /// refuses `summing` none, and leaves a fold the declaring crate wrote to say for itself. **It is
170 /// never DEFAULTED to [`field`](Self::field)** — a measure's own name is this declaration's and
171 /// the column is the upstream's, so a grammar that assumed the two agree would fold the wrong
172 /// column wherever they did not, silently. [`Grouped::from`] is written out for the same reason
173 /// even where the two spellings match.
174 pub from: Option<syn::Ident>,
175 /// The field's declared type.
176 pub ty: syn::Type,
177 /// How an accessor hands this column back — [`Grouped::projection`]'s word at the other role.
178 pub projection: crate::model::Projection,
179}
180
181/// WHAT FOLDS a group's rows into one measure column.
182///
183/// # The axis is CLOSED on the framework's side and OPEN past it
184///
185/// A bare word is one of the framework's own shipped folds, and that vocabulary is closed because a
186/// word is a promise this crate can write the whole binding — which it can only keep for a fold it
187/// SHIPS. A QUOTED PATH is every other fold there is: a type the declaring crate wrote, named the
188/// way this grammar names every type it did not mint, with no vocabulary to be admitted to.
189///
190/// That is the round's own law read at one more position — MINT BARE, REFER QUOTED — and it is why
191/// the two forms are one enum rather than two words: an author choosing between a shipped fold and
192/// their own is choosing a value for one entry, not writing a different entry.
193///
194/// The axis is about the fold's ORIGIN and about nothing else, so it is orthogonal to the entry's
195/// two spellings: both halves are written the same way at `fold = …` inside the full form, and the
196/// sugar `<field> = <fold>` takes both too — where the fold [`owes`](Self::owed) the entry no
197/// column, which is the one thing the short spelling has no seat to say.
198///
199/// # The SHIPPED SPELLINGS are the design's, and the house register disagrees with them
200///
201/// Every other closed VALUE vocabulary in this grammar is a bare short NOUN — `semantics(fold(sum))`
202/// and `fold(max)`, `dedup(hash)` and `dedup(eq)`, the five tracing levels, the four execution
203/// worlds — and `counting`/`summing` are the first gerunds in it. The design law one grammar over
204/// (*a key names the KIND of the value it takes*; same kind, different reach, one word) would make
205/// this position's word for a total `sum`, which is the word `semantics(fold(…))` already spells a
206/// fold with.
207///
208/// The names stand as the closed design wrote them: the design reserved the BLOCK word for the
209/// grammar task's census and named these two itself, and the fold seam that mints the citizens is
210/// its own task. The measurement is recorded here rather than acted on, and it is one line to act
211/// on — [`SHIPPED`](Self::SHIPPED) and [`shipped`](Self::shipped) are the whole of it.
212#[derive(Debug, Clone)]
213pub enum Measure {
214 /// `counting` — how many rows the group holds.
215 Counting,
216 /// `summing` — the total of the upstream column this measure folds.
217 ///
218 /// WHICH column is [`Measured::from`], and the entry names it or is refused: the fold reads one
219 /// and the framework knows it does, so a `summing` with nowhere to read from is an entry with a
220 /// word left out. See [`owed`](Self::owed) for the axis that decides it.
221 Summing,
222 /// A fold the declaring crate wrote, as `measure(<field> = "path::to::Fold")` or the full form's
223 /// `fold = "path::to::Fold"` named it.
224 ///
225 /// Nothing here resolves it, which is the mechanism rather than a limitation: two macro
226 /// expansions cannot see each other, so the path is EMITTED and rustc resolves it at the span of
227 /// the string the author wrote.
228 Declared(syn::Path),
229}
230
231/// WHETHER A FOLD OWES ITS ENTRY A COLUMN — the axis the `from` seat is checked against.
232///
233/// # It exists because the framework's knowledge of a fold is the SHIPPED half and stops there
234///
235/// A word this crate ships is a fold this crate wrote, so what it reads is a fact rather than a
236/// guess: `counting` answers how many rows there are and looks at none of them, `summing` adds up
237/// one column's values. Those two facts are what let the grammar refuse a `counting` that names a
238/// column and a `summing` that names none — one mistake apiece, caught at the declaration rather
239/// than at a fold handed the wrong slice.
240///
241/// A QUOTED path is a type this crate never saw. Refusing it either way would be the framework
242/// deciding on the declaring crate's behalf, so the third answer says so and neither refusal fires.
243#[derive(Debug, Clone, Copy, PartialEq, Eq)]
244pub enum Owed {
245 /// ONE UPSTREAM COLUMN, which the entry must name — `summing`.
246 Column,
247 /// NOTHING: the fold is handed the group's ROWS and reads no column of them — `counting`.
248 Nothing,
249 /// THEIRS to say: a fold the declaring crate wrote, which this crate cannot answer for, so both
250 /// spellings are accepted and the emission hands over whatever the entry named.
251 Theirs,
252}
253
254impl Measure {
255 /// The framework's shipped folds, in the order a refusal lists them.
256 ///
257 /// The near-miss list for a bare word inside [`MEASURE`] is read off this, so the words a
258 /// suggestion offers and the words the sentence names cannot drift apart.
259 pub const SHIPPED: [&'static str; 2] = ["counting", "summing"];
260
261 /// What this fold OWES its entry, which is what the `from` seat is checked against.
262 ///
263 /// One arm per citizen and no default arm, so a third shipped fold cannot be added without its
264 /// author deciding what it reads — which is the whole of what the entry's grammar needs to know
265 /// about it.
266 #[must_use]
267 pub const fn owed(&self) -> Owed {
268 match self {
269 Self::Counting => Owed::Nothing,
270 Self::Summing => Owed::Column,
271 Self::Declared(_) => Owed::Theirs,
272 }
273 }
274
275 /// The shipped fold a bare word names, or [`None`] where the word is none of them.
276 #[must_use]
277 pub fn shipped(word: &str) -> Option<Self> {
278 match word {
279 "counting" => Some(Self::Counting),
280 "summing" => Some(Self::Summing),
281 _ => None,
282 }
283 }
284
285 /// The word this fold was written as — a shipped one's own spelling, or the declared path's.
286 #[must_use]
287 pub fn as_written(&self) -> String {
288 match self {
289 Self::Counting => Self::SHIPPED[0].to_owned(),
290 Self::Summing => Self::SHIPPED[1].to_owned(),
291 Self::Declared(path) => quote::ToTokens::to_token_stream(path).to_string(),
292 }
293 }
294}
295
296impl AggregateModel {
297 /// The declaration's columns in ROW ORDER — every group column, then every measure.
298 ///
299 /// The row shape the emission mints is these columns in this order, so the walk is the model's
300 /// rather than each reader's: two readers ordering one row shape differently is a table whose
301 /// columns depend on who asked. Groups lead because they are the KEY, and a key is a row's first
302 /// columns everywhere else in this framework.
303 pub fn columns(&self) -> impl Iterator<Item = &syn::Ident> {
304 self
305 .groups
306 .iter()
307 .map(|grouped| &grouped.field)
308 .chain(self.measures.iter().map(|measured| &measured.field))
309 }
310}
311
312mod emit;
313
314pub use emit::Mounted;
315
316#[cfg(test)]
317mod tests;