Skip to main content

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;