ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
//! THE ROOT-KEY REGISTRY: a deployment's own timing for it, the per-key state machine it runs, and
//! the framework-held component that tables one machine per root family.
//!
//! Three files under this one, and each is a layer of the same thing:
//!
//! * [`state`] — ONE KEY'S life, as pure transitions over a value. No clock, no lock, no write.
//! * [`tables`] — [`Registry<Root>`] per family and the [`Registries`] that holds them, which is
//!   where the interior mutability and the durable-act seat live.
//! * [`projection`] — [`RootProjection<T>`], the value an emitted per-record root projection is
//!   written on, so that a family has a typed key at all.
//! * [`driver`] — [`RegistryDriver`], the ONE long-lived body that owns the debounce and the batch
//!   on a family's behalf and is the only writer of the head node's keyed feed.
//!
//! The rest of this file is the OPTIONS grain, which is where the module started and which the
//! sections below describe.
//!
//! ```ignore
//! [registry]                 # defaults for every root family
//! debounce        = "300ms"  # humantime — a field name carries NO unit suffix
//! batch_max_items = 10
//! batch_max_wait  = "500ms"
//! retire_drain    = "30s"
//! settle          = "0ms"
//! [registry.media]           # one family's own override — the rest still read the defaults above
//! debounce = "1s"
//! ```
//!
//! # A SECOND reserved key, beside `resources`
//!
//! [`crate::NodeSection`]'s rack is per-MOUNT; this is not. The registry is graph-level — one root,
//! one set of defaults — so it rides its own reserved word at the spine's top level rather than a
//! block under any node's own section, exactly as `resources` groups the document-sourced resources
//! under its own key one field over. A member mounted `registry` would be a second meaning for that
//! key, and the derive refuses one by name — see `ingraph-derive`'s `graph.rs`.
//!
//! # Two grains held by ONE type
//!
//! [`RegistryOptions`] is both the document a deployment writes and the value a family resolves to.
//! `<Root>Options::registry()` hands back the first grain — the defaults, and whatever family
//! overrides this deployment wrote beside them — and [`RegistryOptions::for_family`] hands back the
//! second: the SAME five knobs, with one family's own words folded over the defaults and no override
//! table left to carry, since a resolved value has nothing further to resolve.
//!
//! # Family names are OPEN, and validating them is not this seat's job
//!
//! A family is the lowercase spelling of a lineage's own root type — `media` for `MediaId` — and
//! which spellings are REAL is a fact about the graph this options value is handed to, which a bare
//! `RegistryOptions` cannot see: it is a document type, read before any graph exists to check a
//! spelling against. So the family table here is OPEN, exactly as [`crate::Channels`]'s node table
//! is: any string may carry an override, [`RegistryOptions::for_family`] never refuses one, and a
//! deployment that wrote `[registry.medai]` for a graph with no such family has written an override
//! nothing will ever ask for — inert rather than wrong. Catching that typo is the later seat's that
//! actually knows the roster (the registry's own installation, once it exists).
//!
//! What THIS seat refuses is narrower and needs no roster at all: a family override naming a knob
//! this type does not have (`deny_unknown_fields` on the override shape, same law as everywhere
//! else), and a family whose NAME collides with one of the five reserved knob words — `[registry.
//! debounce]` reads as the scalar field `debounce` taking a table where a duration string belongs,
//! and is refused as that type mismatch.
//!
//! # `deny_unknown_fields` does NOT sit on `RegistryOptions` itself, and that is deliberate
//!
//! Every other document type in this crate carries it. This one cannot: `#[serde(flatten)]` is what
//! lets `[registry.media]` sit beside `debounce` in one TOML table, and serde does not honour
//! `deny_unknown_fields` on a struct that also flattens a catch-all map — the two attributes
//! together silently refuse EVERY family override as an unknown field, which was measured before
//! this shape was chosen and is the reason the container omits the word. The protection moves one
//! level down instead: [`RegistryOverride`] keeps `deny_unknown_fields` for its own five keys, so a
//! typo INSIDE a family's override is still refused by name.
//!
//! # `humantime`, not the request-tier grammar
//!
//! [`crate::batch`]'s own module note already named this file's choice: "a default, a `[registry]`
//! section in a startup file, a knob on a request — is the options layer's business, and the text
//! form a person wrote is `humantime`'s." The `every = "…"` cron word and the request-tier
//! `DurationFilter` operand speak jiff's grammar; this is the OTHER tier, the startup document, and
//! it speaks `humantime`'s — `"300ms"`, `"1s"`, `"2m"`, never a bare number.

use core::{num::NonZeroUsize, time::Duration};
use std::collections::BTreeMap;

use smol_bytes::Utf8Bytes;

pub(crate) mod driver;
// `dynamic` is GATED WHOLE rather than left unconditional on `BatchDoor`'s own precedent: that seam
// has an UNCONDITIONAL consumer — an emitted resolver names the door in every build, binding or not
// — and this one does not. Every reference to `DynRegistry` lives inside `graphql::registry`, which
// is itself behind the SAME feature, so there is no build in which that module's own items are ever
// reached without it — and an unconditional copy would be exactly that: dead code, honestly, in a
// build that names no wire library at all.
#[cfg(feature = "async-graphql")]
pub(crate) mod dynamic;
pub(crate) mod projection;
pub(crate) mod state;
pub(crate) mod tables;

pub use driver::{DriverEngine, RegistryDriver};
#[cfg(feature = "async-graphql")]
pub(crate) use dynamic::DynRegistry;
pub use projection::RootProjection;
pub use state::{Flip, RetireOrigin, Retirement, RootAction, RootAdvance, RootState, Stamp};
pub(crate) use tables::Counting;
pub use tables::{GenerationLedger, Registries, Registry, RegistryCounts, RetiredLedger, RootKey};

/// The debounce window a document does not name — see [`RegistryOptions::debounce`].
pub const DEFAULT_DEBOUNCE: Duration = Duration::from_millis(300);

/// The batch item ceiling a document does not name — see [`RegistryOptions::batch_max_items`].
pub const DEFAULT_BATCH_MAX_ITEMS: NonZeroUsize = NonZeroUsize::new(10).expect("10 is not zero");

/// The batch wait a document does not name — see [`RegistryOptions::batch_max_wait`].
pub const DEFAULT_BATCH_MAX_WAIT: Duration = Duration::from_millis(500);

/// The retiring drain ceiling a document does not name — see [`RegistryOptions::retire_drain`].
pub const DEFAULT_RETIRE_DRAIN: Duration = Duration::from_secs(30);

/// The settle smoothing a document does not name — see [`RegistryOptions::settle`].
///
/// Zero, which is *no smoothing at all*: the knob is an OUTWARD courtesy over an inflight count that
/// is already correct the instant it reaches zero, never a correctness requirement, so the shipped
/// posture is to report that instant rather than hold it back.
pub const DEFAULT_SETTLE: Duration = Duration::ZERO;

/// A deployment's own timing for the root-key registry: the defaults every family reads, and
/// whichever families this document wrote their own words for.
///
/// # `new` holds the shipped defaults, and `Default` delegates
///
/// Unlike [`crate::MongoOptions`]'s empty-is-ordinary shape, every knob here has a real, non-zero
/// shipped value — see the [`DEFAULT_DEBOUNCE`] family of constants — so [`new`](Self::new) states
/// them rather than a zero a `#[derive(Default)]` would have reached for.
///
/// # Presence, one level down from the node rack's
///
/// [`crate::NodeSection`]'s presence is ENABLEMENT — a missing section is a node that does not
/// launch. A family's presence in this type's own table is not that: EVERY family runs, whether or
/// not a deployment wrote it a section, because the registry needs some tuning for the families it
/// was never told about. So the axis here is OVERRIDE, not enablement, and [`for_family`](Self::for_family)
/// never returns an absence — the shipped defaults are what a family gets when nobody wrote it one.
#[derive(Debug, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
pub struct RegistryOptions {
  /// The quiet window a burst on one root key must fall silent for before it is taken as one intake
  /// — see [`crate::batch::Debounce`].
  #[cfg_attr(
    feature = "serde",
    serde(default = "default_debounce", with = "humantime_serde")
  )]
  debounce: Duration,
  /// The item count that flushes a batch on its own, and the ceiling a batch cannot grow past — see
  /// [`crate::batch::Batcher`].
  #[cfg_attr(feature = "serde", serde(default = "default_batch_max_items"))]
  batch_max_items: NonZeroUsize,
  /// The wait that flushes a batch even where nothing filled it — see [`crate::batch::Batcher`].
  #[cfg_attr(
    feature = "serde",
    serde(default = "default_batch_max_wait", with = "humantime_serde")
  )]
  batch_max_wait: Duration,
  /// How long a `Retiring` key waits for its inflight count to reach zero before the sweep marks it
  /// retired anyway, with the tail flagged rather than waited on forever.
  #[cfg_attr(
    feature = "serde",
    serde(default = "default_retire_drain", with = "humantime_serde")
  )]
  retire_drain: Duration,
  /// Outward smoothing before an `Idle` transition is REPORTED — never before it is true. Zero is
  /// *no smoothing*, which is the shipped posture; see [`DEFAULT_SETTLE`].
  #[cfg_attr(
    feature = "serde",
    serde(default = "default_settle", with = "humantime_serde")
  )]
  settle: Duration,
  /// Every family this document wrote its own words for, keyed by the family's own lowercase
  /// spelling — open, and unchecked against any roster; see the module note for why.
  ///
  /// `flatten`, which is what lets `[registry.media]` sit beside `debounce` in one TOML table rather
  /// than under a second key this document would have to name. It is also why the CONTAINER carries
  /// no `deny_unknown_fields` — see the module note.
  #[cfg_attr(feature = "serde", serde(flatten))]
  families: BTreeMap<Utf8Bytes, RegistryOverride>,
}

impl RegistryOptions {
  /// The shipped defaults, with no family override written yet.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self {
      debounce: DEFAULT_DEBOUNCE,
      batch_max_items: DEFAULT_BATCH_MAX_ITEMS,
      batch_max_wait: DEFAULT_BATCH_MAX_WAIT,
      retire_drain: DEFAULT_RETIRE_DRAIN,
      settle: DEFAULT_SETTLE,
      families: BTreeMap::new(),
    }
  }

  /// The debounce window every family reads, absent a family override that names its own.
  #[inline]
  #[must_use]
  pub const fn debounce(&self) -> Duration {
    self.debounce
  }

  /// Run at `debounce`, whatever a family override says.
  #[inline]
  #[must_use]
  pub const fn with_debounce(mut self, debounce: Duration) -> Self {
    self.set_debounce(debounce);
    self
  }

  /// [`with_debounce`](Self::with_debounce), in place.
  #[inline]
  pub const fn set_debounce(&mut self, debounce: Duration) -> &mut Self {
    self.debounce = debounce;
    self
  }

  /// The item ceiling every family reads, absent a family override that names its own.
  #[inline]
  #[must_use]
  pub const fn batch_max_items(&self) -> NonZeroUsize {
    self.batch_max_items
  }

  /// Run at `batch_max_items`, whatever a family override says.
  #[inline]
  #[must_use]
  pub const fn with_batch_max_items(mut self, batch_max_items: NonZeroUsize) -> Self {
    self.set_batch_max_items(batch_max_items);
    self
  }

  /// [`with_batch_max_items`](Self::with_batch_max_items), in place.
  #[inline]
  pub const fn set_batch_max_items(&mut self, batch_max_items: NonZeroUsize) -> &mut Self {
    self.batch_max_items = batch_max_items;
    self
  }

  /// The wait every family reads, absent a family override that names its own.
  #[inline]
  #[must_use]
  pub const fn batch_max_wait(&self) -> Duration {
    self.batch_max_wait
  }

  /// Run at `batch_max_wait`, whatever a family override says.
  #[inline]
  #[must_use]
  pub const fn with_batch_max_wait(mut self, batch_max_wait: Duration) -> Self {
    self.set_batch_max_wait(batch_max_wait);
    self
  }

  /// [`with_batch_max_wait`](Self::with_batch_max_wait), in place.
  #[inline]
  pub const fn set_batch_max_wait(&mut self, batch_max_wait: Duration) -> &mut Self {
    self.batch_max_wait = batch_max_wait;
    self
  }

  /// The retiring drain ceiling every family reads, absent a family override that names its own.
  #[inline]
  #[must_use]
  pub const fn retire_drain(&self) -> Duration {
    self.retire_drain
  }

  /// Run at `retire_drain`, whatever a family override says.
  #[inline]
  #[must_use]
  pub const fn with_retire_drain(mut self, retire_drain: Duration) -> Self {
    self.set_retire_drain(retire_drain);
    self
  }

  /// [`with_retire_drain`](Self::with_retire_drain), in place.
  #[inline]
  pub const fn set_retire_drain(&mut self, retire_drain: Duration) -> &mut Self {
    self.retire_drain = retire_drain;
    self
  }

  /// The settle smoothing every family reads, absent a family override that names its own.
  #[inline]
  #[must_use]
  pub const fn settle(&self) -> Duration {
    self.settle
  }

  /// Run at `settle`, whatever a family override says.
  #[inline]
  #[must_use]
  pub const fn with_settle(mut self, settle: Duration) -> Self {
    self.set_settle(settle);
    self
  }

  /// [`with_settle`](Self::with_settle), in place.
  #[inline]
  pub const fn set_settle(&mut self, settle: Duration) -> &mut Self {
    self.settle = settle;
    self
  }

  /// State `family`'s own override in code — the door a deployment assembling its options
  /// programmatically comes through, rather than a document's `[registry.<family>]`.
  ///
  /// A second call for one family REPLACES the first, a family's override being one statement
  /// rather than an accumulation — [`crate::Channels::tuned`]'s own rule, one door over.
  #[inline]
  #[must_use]
  pub fn with_family(mut self, family: impl Into<Utf8Bytes>, over: RegistryOverride) -> Self {
    self.families.insert(family.into(), over);
    self
  }

  /// Every family this document wrote its own words for — what an unknown-family cross-check reads,
  /// once something exists to check against.
  #[inline]
  pub fn families(&self) -> impl Iterator<Item = &str> {
    self.families.keys().map(Utf8Bytes::as_str)
  }

  /// `family`'s own resolved options: the defaults, with whatever `family` wrote of its own folded
  /// over them one knob at a time.
  ///
  /// Total on `family` — every string resolves, a family with no override reading the defaults
  /// whole. See the module note for why an unknown spelling is not this call's refusal to make.
  #[must_use]
  pub fn for_family(&self, family: &str) -> Self {
    let over = self.families.get(family);
    Self {
      debounce: over
        .and_then(RegistryOverride::debounce)
        .unwrap_or(self.debounce),
      batch_max_items: over
        .and_then(RegistryOverride::batch_max_items)
        .unwrap_or(self.batch_max_items),
      batch_max_wait: over
        .and_then(RegistryOverride::batch_max_wait)
        .unwrap_or(self.batch_max_wait),
      retire_drain: over
        .and_then(RegistryOverride::retire_drain)
        .unwrap_or(self.retire_drain),
      settle: over
        .and_then(RegistryOverride::settle)
        .unwrap_or(self.settle),
      families: BTreeMap::new(),
    }
  }
}

impl Default for RegistryOptions {
  #[inline]
  fn default() -> Self {
    Self::new()
  }
}

/// One family's OWN words — every knob optional, and an absence reading whatever
/// [`RegistryOptions`]'s own defaults (or THIS document's overridden defaults) say.
///
/// The partial twin of [`RegistryOptions`]'s five knobs: where the whole type states a value for
/// every field, this states only the ones a family's own `[registry.<family>]` table wrote, which is
/// what makes `[registry.media]\ndebounce = "1s"` leave `batch_max_items` and the rest reading the
/// `[registry]` table's own values rather than some second, independent default.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
pub struct RegistryOverride {
  #[cfg_attr(feature = "serde", serde(default, with = "humantime_serde::option"))]
  debounce: Option<Duration>,
  #[cfg_attr(feature = "serde", serde(default))]
  batch_max_items: Option<NonZeroUsize>,
  #[cfg_attr(feature = "serde", serde(default, with = "humantime_serde::option"))]
  batch_max_wait: Option<Duration>,
  #[cfg_attr(feature = "serde", serde(default, with = "humantime_serde::option"))]
  retire_drain: Option<Duration>,
  #[cfg_attr(feature = "serde", serde(default, with = "humantime_serde::option"))]
  settle: Option<Duration>,
}

impl RegistryOverride {
  /// A family override naming nothing of its own — every knob reads whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self {
      debounce: None,
      batch_max_items: None,
      batch_max_wait: None,
      retire_drain: None,
      settle: None,
    }
  }

  /// This family's own debounce, or [`None`] for whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn debounce(&self) -> Option<Duration> {
    self.debounce
  }

  /// Name `debounce` as this family's own.
  #[inline]
  #[must_use]
  pub const fn with_debounce(mut self, debounce: Duration) -> Self {
    self.set_debounce(Some(debounce));
    self
  }

  /// [`with_debounce`](Self::with_debounce), in place — INCLUDING back to [`None`], which is what
  /// lets a holder narrowing a value parsed off a document say so.
  #[inline]
  pub const fn set_debounce(&mut self, debounce: Option<Duration>) -> &mut Self {
    self.debounce = debounce;
    self
  }

  /// This family's own item ceiling, or [`None`] for whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn batch_max_items(&self) -> Option<NonZeroUsize> {
    self.batch_max_items
  }

  /// Name `batch_max_items` as this family's own.
  #[inline]
  #[must_use]
  pub const fn with_batch_max_items(mut self, batch_max_items: NonZeroUsize) -> Self {
    self.set_batch_max_items(Some(batch_max_items));
    self
  }

  /// [`with_batch_max_items`](Self::with_batch_max_items), in place — including back to [`None`].
  #[inline]
  pub const fn set_batch_max_items(&mut self, batch_max_items: Option<NonZeroUsize>) -> &mut Self {
    self.batch_max_items = batch_max_items;
    self
  }

  /// This family's own wait, or [`None`] for whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn batch_max_wait(&self) -> Option<Duration> {
    self.batch_max_wait
  }

  /// Name `batch_max_wait` as this family's own.
  #[inline]
  #[must_use]
  pub const fn with_batch_max_wait(mut self, batch_max_wait: Duration) -> Self {
    self.set_batch_max_wait(Some(batch_max_wait));
    self
  }

  /// [`with_batch_max_wait`](Self::with_batch_max_wait), in place — including back to [`None`].
  #[inline]
  pub const fn set_batch_max_wait(&mut self, batch_max_wait: Option<Duration>) -> &mut Self {
    self.batch_max_wait = batch_max_wait;
    self
  }

  /// This family's own retiring drain ceiling, or [`None`] for whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn retire_drain(&self) -> Option<Duration> {
    self.retire_drain
  }

  /// Name `retire_drain` as this family's own.
  #[inline]
  #[must_use]
  pub const fn with_retire_drain(mut self, retire_drain: Duration) -> Self {
    self.set_retire_drain(Some(retire_drain));
    self
  }

  /// [`with_retire_drain`](Self::with_retire_drain), in place — including back to [`None`].
  #[inline]
  pub const fn set_retire_drain(&mut self, retire_drain: Option<Duration>) -> &mut Self {
    self.retire_drain = retire_drain;
    self
  }

  /// This family's own settle smoothing, or [`None`] for whatever the defaults say.
  #[inline]
  #[must_use]
  pub const fn settle(&self) -> Option<Duration> {
    self.settle
  }

  /// Name `settle` as this family's own.
  #[inline]
  #[must_use]
  pub const fn with_settle(mut self, settle: Duration) -> Self {
    self.set_settle(Some(settle));
    self
  }

  /// [`with_settle`](Self::with_settle), in place — including back to [`None`].
  #[inline]
  pub const fn set_settle(&mut self, settle: Option<Duration>) -> &mut Self {
    self.settle = settle;
    self
  }
}

/// [`RegistryOptions::debounce`]'s own `#[serde(default = …)]` — a duration a document did not name.
#[cfg(feature = "serde")]
fn default_debounce() -> Duration {
  DEFAULT_DEBOUNCE
}

/// [`RegistryOptions::batch_max_items`]'s own `#[serde(default = …)]`.
#[cfg(feature = "serde")]
fn default_batch_max_items() -> NonZeroUsize {
  DEFAULT_BATCH_MAX_ITEMS
}

/// [`RegistryOptions::batch_max_wait`]'s own `#[serde(default = …)]`.
#[cfg(feature = "serde")]
fn default_batch_max_wait() -> Duration {
  DEFAULT_BATCH_MAX_WAIT
}

/// [`RegistryOptions::retire_drain`]'s own `#[serde(default = …)]`.
#[cfg(feature = "serde")]
fn default_retire_drain() -> Duration {
  DEFAULT_RETIRE_DRAIN
}

/// [`RegistryOptions::settle`]'s own `#[serde(default = …)]`.
#[cfg(feature = "serde")]
fn default_settle() -> Duration {
  DEFAULT_SETTLE
}

#[cfg(test)]
mod tests;