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
//! The typed graph builder: records nodes/edges as data while the `edge` bound is
//! the compile-time guard.

use core::marker::PhantomData;

use smol_bytes::Utf8Bytes;

use super::{DriverKind, EdgeId, FanoutKind, NodeId};
// `Declared` lives under `drive::launch` and is reached from here, which is the one edge this layer
// draws upward: the mount predicate is spelled through a node's own declared MODE, so the door that
// mounts has to be able to name the trait that states it. The declaration seam is data about a node
// rather than machinery that runs one, so what crosses is a fact and never a driver.
use crate::{
  drive::{Declared, Streams},
  operator::Driven,
};

/// A typed handle to a declared node. Carries `O` (phantom) purely so
/// [`GraphBuilder::edge`] can compile-check `producer::Output == consumer::Input`.
pub struct NodeHandle<O> {
  id: NodeId,
  _op: PhantomData<fn() -> O>,
}

impl<O> NodeHandle<O> {
  // `pub(crate)` rather than private: the launch surface mints one from a source handle's id to
  // reuse the ONE typed edge recorder — a source's out-edge is still typed by its own token — and
  // that surface is not in this crate, so `declare` below is the only caller a build sees today.
  #[inline]
  pub(crate) const fn new(id: NodeId) -> Self {
    Self {
      id,
      _op: PhantomData,
    }
  }

  /// This node's id.
  #[inline]
  pub const fn id(&self) -> NodeId {
    self.id
  }
}

// Hand-written so `O` need not be `Clone`/`Copy` (the handle is a plain id token).
impl<O> Clone for NodeHandle<O> {
  #[inline]
  fn clone(&self) -> Self {
    *self
  }
}

impl<O> Copy for NodeHandle<O> {}

/// A declared node, erased of its operator type (the typed [`NodeHandle`] carries
/// that). The read view [`ChannelGraph`](super::ChannelGraph) exposes.
#[derive(Debug, Clone)]
pub struct Node {
  name: Utf8Bytes,
  driver: DriverKind,
  is_source: bool,
}

impl Node {
  /// The node's declared name.
  #[inline]
  pub fn name(&self) -> &str {
    &self.name
  }

  /// Which driver runs it.
  #[inline]
  pub const fn driver(&self) -> DriverKind {
    self.driver
  }

  /// Whether it is a dataflow head (a source).
  #[inline]
  pub const fn is_source(&self) -> bool {
    self.is_source
  }
}

/// A declared edge `from → to` with its fan-out kind.
#[derive(Debug, Clone, Copy)]
pub struct Edge {
  from: NodeId,
  to: NodeId,
  kind: FanoutKind,
}

impl Edge {
  /// The producer node.
  #[inline]
  pub const fn from(&self) -> NodeId {
    self.from
  }

  /// The consumer node.
  #[inline]
  pub const fn to(&self) -> NodeId {
    self.to
  }

  /// How the output fans to the consumer.
  #[inline]
  pub const fn kind(&self) -> FanoutKind {
    self.kind
  }
}

/// Builds a unit-DAG as data. `node`/`source` declare typed nodes; `edge` records
/// a type-checked edge; `validate` (see the graph module) freezes it into a
/// [`ChannelGraph`](super::ChannelGraph).
pub struct GraphBuilder {
  nodes: Vec<Node>,
  edges: Vec<Edge>,
}

impl GraphBuilder {
  /// An empty builder.
  #[inline]
  pub const fn new() -> Self {
    Self {
      nodes: Vec::new(),
      edges: Vec::new(),
    }
  }

  /// Declare an interior node running operator `O` on `driver`.
  ///
  /// # *IS A NODE* IS A BOUND HERE, and the declaration is what makes it writable
  ///
  /// A unit wears one of TWO faces — [`Operator`] or [`AsyncOperator`](crate::AsyncOperator) — and
  /// *implements one of two traits* is not a predicate stable Rust can spell: a marker
  /// blanket-implemented for each would be two overlapping impls. What CAN be spelled is *implements
  /// the one its declaration chose*, and [`Declared::Mode`](crate::Declared::Mode) is the choice —
  /// so `O: Declared + Driven<<O as Declared>::Mode>` refuses a non-operator AT THE MOUNT rather
  /// than leaving it for whatever downstream call happened to name a face.
  ///
  /// That is one refusal reading two ways. A type that is no node at all misses `Declared` and is
  /// told so; a node whose body wears the face its word did not choose satisfies `Declared` and
  /// misses the `Driven` row, and is told THAT — the lying word correcting itself at the line that
  /// mounted it, rather than at a launch three expansions away.
  ///
  /// The two checks it does not replace stay where they were: [`edge`](Self::edge) compares the two
  /// ends' messages, and the emitted launch's per-node predicate names the mode the declaration's
  /// word selected. This one is EARLIER than both, which is the whole of what it buys.
  #[inline]
  pub fn node<O>(&mut self, name: impl Into<Utf8Bytes>, driver: DriverKind) -> NodeHandle<O>
  where
    O: Declared + Driven<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, false)
  }

  /// Declare a **source** (dataflow head) node running operator `O` on `driver`.
  ///
  /// [`node`](Self::node)'s note on the bound applies here verbatim.
  #[inline]
  pub fn source<O>(&mut self, name: impl Into<Utf8Bytes>, driver: DriverKind) -> NodeHandle<O>
  where
    O: Declared + Driven<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, true)
  }

  /// Declare an interior node whose body wears the **STREAMING** pair — a
  /// [`StreamOperator`](crate::StreamOperator) or an
  /// [`AsyncStreamOperator`](crate::AsyncStreamOperator), driven by a
  /// [`StreamLane`](crate::StreamLane) rather than by a [`Resident`](crate::Resident).
  ///
  /// A door of its own beside [`node`](Self::node) for [`origin`](Self::origin)'s reason: the two
  /// pairs are four traits and a body wears exactly one of them, so the predicate
  /// [`node`](Self::node) carries is one a streaming body could never satisfy. What replaces it is
  /// the same shape read one seam over — [`Declared::Mode`](crate::Declared::Mode) states the mode
  /// its declaration chose and [`Streams`](crate::Streams) is the row that mode's face fills.
  ///
  /// One refusal reading two ways, exactly as [`node`](Self::node)'s does: a type that is no node at
  /// all misses [`Declared`] and is told so; one whose body wears the face its word did not choose
  /// satisfies that and misses the [`Streams`] row.
  #[inline]
  pub fn streaming<O>(&mut self, name: impl Into<Utf8Bytes>, driver: DriverKind) -> NodeHandle<O>
  where
    O: Declared + Streams<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, false)
  }

  /// Declare a streaming **source** (dataflow head).
  ///
  /// [`streaming`](Self::streaming)'s note on the bound applies here verbatim, and the split is
  /// [`node`](Self::node)/[`source`](Self::source)'s: having no upstream IS what makes a node a
  /// head, so the two doors record the one fact this builder keeps about it.
  #[inline]
  pub fn streaming_source<O>(
    &mut self,
    name: impl Into<Utf8Bytes>,
    driver: DriverKind,
  ) -> NodeHandle<O>
  where
    O: Declared + Streams<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, true)
  }

  /// Declare an interior node whose body wears the **AUTONOMOUS** kind — an
  /// [`AutonomousOperator`](crate::AutonomousOperator) or an
  /// [`AsyncAutonomousOperator`](crate::AsyncAutonomousOperator), which OWNS ITS OWN LOOP rather
  /// than being called once per delivery.
  ///
  /// A door of its own beside [`node`](Self::node) and [`streaming`](Self::streaming), for their
  /// shared reason: the three kinds are six traits and a body wears exactly one of them, so the
  /// predicate either of the others carries is one an autonomous body could never satisfy. What
  /// replaces it is the same shape read one seam further —
  /// [`Declared::Mode`](crate::Declared::Mode) states the mode its declaration chose and
  /// [`Runs`](crate::Runs) is the row that mode's face fills.
  ///
  /// One refusal reading two ways, exactly as [`node`](Self::node)'s does: a type that is no node at
  /// all misses [`Declared`] and is told so; one whose body wears the face its word did not choose
  /// satisfies that and misses the [`Runs`](crate::Runs) row.
  #[inline]
  pub fn autonomous<O>(&mut self, name: impl Into<Utf8Bytes>, driver: DriverKind) -> NodeHandle<O>
  where
    O: Declared + crate::Runs<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, false)
  }

  /// Declare an autonomous **source** (dataflow head).
  ///
  /// [`autonomous`](Self::autonomous)'s note on the bound applies here verbatim, and the split is
  /// [`node`](Self::node)/[`source`](Self::source)'s: having no upstream IS what makes a node a
  /// head, so the two doors record the one fact this builder keeps about it.
  #[inline]
  pub fn autonomous_source<O>(
    &mut self,
    name: impl Into<Utf8Bytes>,
    driver: DriverKind,
  ) -> NodeHandle<O>
  where
    O: Declared + crate::Runs<<O as Declared>::Mode>,
  {
    self.declare(name.into(), driver, true)
  }

  /// Declare an **origin** — a [`Source`](crate::Source) or an [`AsyncSource`](crate::AsyncSource),
  /// which is a dataflow head of a different KIND.
  ///
  /// A fourth door rather than a bound relaxed on [`source`](Self::source), because an origin is not
  /// an operator: it has no `accept`, no inbox and no per-item loop, so the bound
  /// [`source`](Self::source) carries is one it could never satisfy. What it has instead is a life,
  /// and the pair below is the origin layer's own version of the same predicate —
  /// [`DeclaredOrigin`](crate::DeclaredOrigin) states the face its declaration chose and
  /// [`Lived`](crate::Lived) is the row that face fills.
  ///
  /// One refusal reading two ways, exactly as [`node`](Self::node)'s does: a type that is no origin
  /// at all misses `DeclaredOrigin` and is told so; one whose body wears the face its word did not
  /// choose satisfies that and misses the `Lived` row.
  #[inline]
  pub fn origin<S>(&mut self, name: impl Into<Utf8Bytes>, driver: DriverKind) -> NodeHandle<S>
  where
    S: crate::DeclaredOrigin + crate::Lived<<S as crate::DeclaredOrigin>::Mode>,
  {
    self.declare(name.into(), driver, true)
  }

  /// The unbound half both doors share. It records a NAME and a driver and nothing else, so the
  /// predicate belongs on the doors rather than here — see [`node`](Self::node).
  fn declare<O>(&mut self, name: Utf8Bytes, driver: DriverKind, is_source: bool) -> NodeHandle<O> {
    let id = NodeId::new(self.nodes.len());
    self.nodes.push(Node {
      name,
      driver,
      is_source,
    });
    NodeHandle::new(id)
  }

  /// Declare an edge `from → to`. The bound `D: Driven<N, In = <U as Driven<M>>::Out>` is the
  /// **compile-time guard** (same as [`subscribe`](crate::subscribe)): the edge is
  /// accepted only when the consumer's input type is exactly the producer's output
  /// type — the one type the two ends have to agree on.
  ///
  /// The two ends' FACES are free and independent, and nothing here relates them: an edge carries a
  /// message, and which of the pair awaits its body says nothing about what it puts on the wire.
  /// Each is inferred from the trait its end implements, so a caller writes neither.
  ///
  /// A mismatched pair is a **compile error**:
  ///
  /// ```compile_fail
  /// use ingraph::{
  ///   Block, Buffered, Declared, Delivery, DriverKind, Effect, Emitter, FanoutKind, GraphBuilder,
  ///   Operator, Unchanneled,
  /// };
  /// struct A; impl Operator for A {
  ///   type In = (); type Out = u8; type Error = core::convert::Infallible;
  ///   fn accept(&mut self, ctx: &Context, _: Delivery<Self::In>, _: &mut Emitter<Self::Out>) -> Result<(), Self::Error> { Ok(()) }
  /// }
  /// impl Declared for A {
  ///   const EFFECT: Effect = Effect::Pure;
  ///   type Channels = Unchanneled; type Mode = Block; type Options = (); type Pair = Buffered;
  ///   type Wires<O> = ingraph::Downstream<O>;
  ///   type Attribution<O> = ();
  /// }
  /// struct B; impl Operator for B {
  ///   type In = u16; type Out = u16; type Error = core::convert::Infallible;
  ///   fn accept(&mut self, ctx: &Context, _: Delivery<Self::In>, _: &mut Emitter<Self::Out>) -> Result<(), Self::Error> { Ok(()) }
  /// }
  /// impl Declared for B {
  ///   const EFFECT: Effect = Effect::Pure;
  ///   type Channels = Unchanneled; type Mode = Block; type Options = (); type Pair = Buffered;
  ///   type Wires<O> = ingraph::Downstream<O>;
  ///   type Attribution<O> = ();
  /// }
  /// let mut g = GraphBuilder::new();
  /// let a = g.source::<A>("a", DriverKind::Async);
  /// let b = g.node::<B>("b", DriverKind::Async);
  /// g.edge(&a, &b, FanoutKind::Direct); // A::Out (u8) != B::In (u16) → rejected
  /// ```
  ///
  /// Both ends state their facts above, so what this example refuses is the MESSAGE mismatch alone:
  /// a node missing them is refused one line earlier, where it is mounted.
  ///
  /// # The producer seat is an OPERATOR's, and an origin has its own door
  ///
  /// `U: Driven<M>` is a node the graph CALLS — one of the two operator faces. An origin implements
  /// neither: what it implements is [`Source`](crate::Source)/[`AsyncSource`](crate::AsyncSource),
  /// reached through [`Lived`](crate::Lived), which is a different row with a different shape of life
  /// behind it. So an origin does not come through here and is not meant to —
  /// [`origin_edge`](Self::origin_edge) is its door, for [`origin`](Self::origin)'s own reason one
  /// step earlier: a fourth door rather than a bound relaxed.
  #[inline]
  pub fn edge<U, D, M, N>(
    &mut self,
    from: &NodeHandle<U>,
    to: &NodeHandle<D>,
    kind: FanoutKind,
  ) -> EdgeId
  where
    U: Driven<M>,
    D: Driven<N, In = <U as Driven<M>>::Out>,
  {
    let id = EdgeId::new(self.edges.len());
    self.edges.push(Edge {
      from: from.id(),
      to: to.id(),
      kind,
    });
    id
  }

  /// Declare an edge from an **ORIGIN** to a consumer of it — [`edge`](Self::edge) with the producer
  /// seat spelled through the origin layer's row instead of the operator's.
  ///
  /// The guard is [`edge`](Self::edge)'s, read one trait over: the edge is accepted only when the
  /// consumer's input is exactly what this origin YIELDS, which is the one type the two ends have to
  /// agree on. Both ends' faces stay free and independent — an awaited origin may feed a blocking
  /// consumer and the reverse — because what crosses an edge is a message and nothing about a body's
  /// face travels with it.
  ///
  /// A SECOND DOOR rather than a bound relaxed on [`edge`](Self::edge), and the reason is
  /// [`origin`](Self::origin)'s verbatim: an origin is not an operator, and the two producer
  /// predicates are two traits no blanket row can join — a type could satisfy either, and stable Rust
  /// cannot be told that no type satisfies both.
  ///
  /// # What the DECLARED road spells instead
  ///
  /// Nothing new. A declaration names its upstream by TYPE —
  /// `subscribe(upstream(node = "crate::Watch"))` — and an origin mounted through
  /// [`Blueprint::origin`](crate::Blueprint::origin) is one of the types that join finds, so the same
  /// word reaches an origin and a node alike. This door exists for the HAND-WRITTEN arrangement,
  /// where there are two typed handles and the compiler can be made to check the pair.
  ///
  /// A mismatched pair is a **compile error**, exactly as it is at [`edge`](Self::edge):
  ///
  /// ```compile_fail
  /// use ingraph::{
  ///   Block, Buffered, Context, Control, Declared, DeclaredOrigin, Delivery, DriverKind, Effect,
  ///   Emitter, FanoutKind, Feed, Fin, GraphBuilder, Operator, Source, Unchanneled,
  /// };
  /// struct Ticking;
  /// impl Source for Ticking {
  ///   type Options = (); type Yield = u8; type Mutation = ();
  ///   type Error = core::convert::Infallible;
  ///   fn build(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> { Ok(Self) }
  ///   fn run(
  ///     self, _ctx: Context, _giving: Feed<u8>, _eating: Control<core::convert::Infallible>,
  ///   ) -> Result<Fin, Self::Error> { Ok(Fin::Spent) }
  /// }
  /// impl DeclaredOrigin for Ticking { type Mode = Block; }
  /// struct Ledger;
  /// impl Operator for Ledger {
  ///   type In = u16; type Out = u16; type Error = core::convert::Infallible;
  ///   fn accept(
  ///     &mut self, _ctx: &Context, _: Delivery<Self::In>, _: &mut Emitter<Self::Out>,
  ///   ) -> Result<(), Self::Error> { Ok(()) }
  /// }
  /// impl Declared for Ledger {
  ///   const EFFECT: Effect = Effect::Pure;
  ///   type Channels = Unchanneled; type Mode = Block; type Options = (); type Pair = Buffered;
  ///   type Wires<O> = ingraph::Downstream<O>;
  ///   type Attribution<O> = ();
  /// }
  /// let mut g = GraphBuilder::new();
  /// let ticking = g.origin::<Ticking>("ticking", DriverKind::Thread);
  /// let ledger = g.node::<Ledger>("ledger", DriverKind::Thread);
  /// // Ticking's Yield (u8) is not Ledger's In (u16) → rejected
  /// g.origin_edge(&ticking, &ledger, FanoutKind::Direct);
  /// ```
  #[inline]
  pub fn origin_edge<S, D, N>(
    &mut self,
    from: &NodeHandle<S>,
    to: &NodeHandle<D>,
    kind: FanoutKind,
  ) -> EdgeId
  where
    S: crate::DeclaredOrigin + crate::Lived<<S as crate::DeclaredOrigin>::Mode>,
    D: Driven<N, In = crate::Produced<S>>,
  {
    let id = EdgeId::new(self.edges.len());
    self.edges.push(Edge {
      from: from.id(),
      to: to.id(),
      kind,
    });
    id
  }

  /// Declare an edge between two nodes named by [`NodeId`], with no type check HERE.
  ///
  /// [`edge`](Self::edge) is the door a hand-written arrangement takes, and its bound is the whole
  /// point of it: two handles are two types, and the compiler makes the pair agree. This door is the
  /// JOIN's — the walk that reads each node's declared upstreams and finds them among the root's
  /// mounted fields by type identity. There are no two handles there to bind: what the join holds is
  /// a `TypeId` and the position it matched at, so the agreement cannot be spelled as a bound at
  /// this call.
  ///
  /// It is not spelled NOWHERE, which is what makes the door defensible. A declaration naming its
  /// upstream states the agreement at its OWN site — the emitted subscription audit resolves the
  /// path there and the compiler checks the pair — and the wiring walk asks again when it opens the
  /// edge, where a mismatch is an [`EdgeTypeError`](crate::EdgeTypeError) naming both types. This
  /// adds a third party to a fact two others already keep; it does not become its only keeper.
  ///
  /// `pub(crate)`, so the join is the only caller: a public untyped edge would be a way of building
  /// the very arrangement [`edge`](Self::edge) exists to refuse.
  #[inline]
  pub(crate) fn join(&mut self, from: NodeId, to: NodeId, kind: FanoutKind) -> EdgeId {
    let id = EdgeId::new(self.edges.len());
    self.edges.push(Edge { from, to, kind });
    id
  }

  /// Consume the builder into its raw node/edge data (the graph module's
  /// `validate` entry point).
  #[inline]
  pub(crate) fn into_parts(self) -> (Vec<Node>, Vec<Edge>) {
    (self.nodes, self.edges)
  }
}

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

#[cfg(test)]
mod tests;