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
//! THE BRIDGE RUNNING: an origin whose feed IS a graph edge, driven end to end.
//!
//! The suite beside this one asserts what a deployment is allowed to be; this one asserts what
//! happens when one runs. Four claims, and each is about a seam the bridge could have got wrong:
//!
//! | claim | what would be wrong without it |
//! |---|---|
//! | items arrive as DELIVERIES under minted ids | a feed's bare `Y` is not what an edge carries |
//! | a stalled consumer stalls the ORIGIN | a pump between them would absorb the stall into a second queue |
//! | a stop mid-stream loses nothing already given | an ending that raced the last give would drop it |
//! | the edge closes with the origin's life, and only then | an invented `End`, or a stream that never ends |
//!
//! The consumer here is the TEST — it takes the inbox the wiring opened and reads it directly —
//! which is what makes these sans-I/O: nothing schedules a second body, so what is asserted is the
//! edge itself rather than some node's behaviour over it.
use crate::Context;

use core::{convert::Infallible, time::Duration};
use std::sync::{Arc, Mutex};

use crate::{
  Block, Buffered, ChannelOptions, Control, Declared, DeclaredOrigin, Delivery, Effect, Emitter,
  Enablement, Feed, Fin, Inbox, ItemId, MutationNode, Operator, Resources, Source, Stopper,
  Unchanneled, Upstream, Wake,
};

/// How long a POSITIVE wait may take before the test calls it a hang. Generous: a slow machine is
/// not a failure, and every wait here is one a correct run satisfies immediately.
const PATIENCE: Duration = Duration::from_secs(10);

/// How long a NEGATIVE wait is given to be wrong — the window in which a give that should be
/// BLOCKED gets its chance to come through anyway. Short, because what it is measuring is the
/// absence of an event that a broken bridge would produce at once.
const STILLNESS: Duration = Duration::from_millis(200);

/// An origin that hands out `1..=count` and says so each time a give RETURNS.
///
/// The report is the whole instrument: a give that has not answered is an origin BLOCKED on the
/// edge, which is the only way a test can see backpressure from the outside.
struct Counting {
  count: u64,
  gave: flume::Sender<u64>,
  /// Every value a give answered `Ok` for, in order — what the downstream's tail is compared with.
  delivered: Arc<Mutex<Vec<u64>>>,
  /// Where this life's own ending is left, for a test that asserts which one it was.
  ended: Arc<Mutex<Option<Fin>>>,
}

impl Source for Counting {
  type Options = ();
  type Yield = u64;
  type Mutation = ();
  type Error = Infallible;

  fn build(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> {
    unreachable!("this suite hands the mount a built origin, as the create walk would")
  }

  fn run(
    self,
    ctx: Context,
    giving: Feed<u64>,
    _eating: Control<Infallible>,
  ) -> Result<Fin, Self::Error> {
    let mut fin = Fin::Spent;
    for value in 1..=self.count {
      // The stop is read BEFORE the give, which is the origin face's own shape: a body inside `run`
      // hears the wind-down on its shutdown line and nowhere else.
      if ctx.shutdown().is_shutdown() {
        fin = Fin::Stopped;
        break;
      }
      if giving.give(value).is_err() {
        fin = Fin::Stopped;
        break;
      }
      self
        .delivered
        .lock()
        .expect("no test panics while holding this")
        .push(value);
      let _ = self.gave.send(value);
    }
    *self
      .ended
      .lock()
      .expect("no test panics while holding this") = Some(fin);
    Ok(fin)
  }
}

impl DeclaredOrigin for Counting {
  type Mode = Block;
}

/// The consumer whose inbox the test reads. Its body never runs — what this declaration is for is
/// the EDGE it puts in the plan and the input type that edge carries.
struct Ledger;

impl Operator for Ledger {
  type Error = Infallible;
  type In = u64;
  type Out = u64;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<u64>,
    _emitter: &mut Emitter<u64>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Ledger {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  // TWO DEEP, and the number is this suite's instrument: the backpressure test needs a bound it can
  // fill by hand, and every other test here is indifferent to it.
  const UPSTREAMS: &'static [Upstream] =
    &[Upstream::of::<Counting>("crate::Counting").channelled(ChannelOptions::Bounded(2))];
  type Channels = Unchanneled;
  type Mode = Block;
  type Options = ();
  type Pair = Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// One bridged deployment, wired and ignited: the origin on its engine, the consumer's inbox in the
/// test's hand.
struct Running {
  app: Option<crate::App<()>>,
  inbox: Inbox<ItemId, u64>,
  stopper: Stopper,
  gave: flume::Receiver<u64>,
  delivered: Arc<Mutex<Vec<u64>>>,
  ended: Arc<Mutex<Option<Fin>>>,
}

impl Running {
  /// Wire an origin that will hand out `count` values, and start it.
  fn start(count: u64) -> Self {
    let mut blueprint = crate::Blueprint::new();
    let _ = blueprint.origin::<Counting>("counting");
    let ledger = blueprint.node::<Ledger>("ledger");
    let wired = blueprint
      .into_plan()
      .expect("the edge joins on the origin's own identity")
      .with_enablement(Enablement::new().launching("counting").launching("ledger"))
      .validate()
      .expect("the bridge opens that edge");

    let mut wiring = wired.create().wire();
    // THE TEST TAKES THE CONSUMER'S SIDE and the MOUNT takes the producer's, which is the whole of
    // the bridge's shape: one edge, opened once by the wiring walk, with its two halves going to the
    // two parties that have something to do with it.
    let inbox = wiring
      .inbox::<u64>(ledger)
      .expect("the consumer's input is what its declaration says")
      .expect("this deployment launches the consumer");
    let outbox = wiring
      .outbox::<u64>(ledger)
      .expect("the same edge, asked for under the same type")
      .expect("this deployment launches the consumer");
    let enrolled = wiring.enrol("counting");
    let mut ignition = wiring.into_assembly().ignite();

    let (gave, heard) = flume::unbounded();
    let delivered = Arc::new(Mutex::new(Vec::new()));
    let ended = Arc::new(Mutex::new(None));
    let mounted: crate::Bridged<<() as MutationNode>::Command> = ignition
      .origin_bridged::<Counting>(
        "counting",
        Counting {
          count,
          gave,
          delivered: Arc::clone(&delivered),
          ended: Arc::clone(&ended),
        },
        outbox,
        4,
        enrolled,
      )
      .expect("its engine");
    // TWO SEATS and not three — the handle a bridged mount answers with has no yield line in it,
    // because the far end of this origin's feed is the inbox above.
    let (_commands, stopper) = mounted.into_parts();

    Self {
      app: Some(ignition.into_app::<()>()),
      inbox,
      stopper,
      gave: heard,
      delivered,
      ended,
    }
  }

  /// Everything queued on the edge right now, as the values a consumer's body would have seen.
  ///
  /// It also proves the SHAPE of what crossed: every message is a `Delivered` carrying a
  /// `Payload::One`, so a bridge that had invented a punctuation of its own — or batched — would
  /// fail here rather than in a prose review.
  ///
  /// # It PARKS rather than draining, and the difference is load-bearing
  ///
  /// A resident's own loop parks, so a test whose subject is BACKPRESSURE has to park too — and on
  /// this transport the two doors are not interchangeable when the edge is FULL. `flume`'s `drain`
  /// pulls pending senders into the queue BEFORE it takes the queue, so on an edge already at its
  /// bound it promotes nobody (the queue is not under capacity yet), takes everything, and leaves a
  /// blocked producer blocked until some LATER receive wakes it. Nothing in the framework's own loop
  /// is affected — a resident parks on the next pass and the sender is pulled then — but a test that
  /// drained would be measuring `drain`'s shape instead of the bridge's.
  fn taken(&self) -> Vec<(ItemId, u64)> {
    let mut taken = Vec::new();
    while let Some(wake) = self.inbox.park(Duration::ZERO) {
      match wake {
        Wake::Delivered(delivery) => {
          let mut items = delivery.into_items();
          let item = items.next().expect("a give is one item");
          assert!(items.next().is_none(), "a give is ONE item, not a batch");
          taken.push(item.into_parts());
        }
        // The park's own timeout: nothing is queued, which is where this walk stops.
        Wake::Sweep => break,
        Wake::Tick(_) => panic!("nothing rings a clock on this edge"),
      }
    }
    taken
  }

  /// Wait for the next give to ANSWER, or `None` where the origin is still blocked on the edge.
  fn next_give(&self, patience: Duration) -> Option<u64> {
    self.gave.recv_timeout(patience).ok()
  }

  /// Everything a give answered `Ok` for.
  fn delivered(&self) -> Vec<u64> {
    self
      .delivered
      .lock()
      .expect("no test panics while holding this")
      .clone()
  }

  /// The ending this origin's life reached, once it has reached one.
  fn ended(&self) -> Option<Fin> {
    *self
      .ended
      .lock()
      .expect("no test panics while holding this")
  }

  /// Park until the origin's life is over — the drain-first door, so a finite origin reaches its own
  /// last item rather than its earliest honest ending.
  fn until_stopped(&self) {
    self
      .app
      .as_ref()
      .expect("the app is still held")
      .until_stopped();
  }

  /// Wind the world down and assert it was clean.
  fn shutdown(&mut self) {
    let app = self.app.take().expect("shut down once");
    let stopped = app.shutdown(None);
    assert!(stopped.is_clean(), "{stopped:?}");
  }
}

/// **ITEMS CROSS AS DELIVERIES, UNDER IDS THIS LINE MINTED** — the conversion a feed's bare `Y`
/// needed and the edge already demanded.
///
/// The ids are the claim that goes beyond the values: they are minted here rather than carried, and
/// what an [`ItemId`] promises is that they are monotone within one sender. A bridge that reused one
/// would let a late ack settle the wrong input, which is the fault `drive::window`'s own suite is
/// built around.
#[test]
fn a_bridged_origins_items_reach_the_consumers_inbox_as_deliveries() {
  let mut running = Running::start(2);
  running.until_stopped();
  assert_eq!(running.ended(), Some(Fin::Spent));

  let taken = running.taken();
  assert_eq!(
    taken.iter().map(|(_, value)| *value).collect::<Vec<_>>(),
    vec![1, 2]
  );
  assert_eq!(
    taken.iter().map(|(id, _)| *id).collect::<Vec<_>>(),
    vec![ItemId::new(0), ItemId::new(1)],
    "the ids are minted by this line, from zero, one per give"
  );

  running.shutdown();
}

/// **A STALLED CONSUMER STALLS THE ORIGIN**, through the edge's own bound and not through a second
/// one.
///
/// The edge is two deep, so a consumer that reads nothing lets exactly two gives answer and leaves
/// the third waiting. That number is the whole point: it is the DECLARATION's `channel = bounded(2)`
/// and there is no other queue anywhere for the difference to hide in — a pump between the origin
/// and the edge would have absorbed this stall and answered the third give too.
#[test]
fn a_consumer_that_does_not_read_stalls_the_origin_on_the_edges_own_bound() {
  let mut running = Running::start(5);

  assert_eq!(running.next_give(PATIENCE), Some(1));
  assert_eq!(running.next_give(PATIENCE), Some(2));
  // THE NEGATIVE, and it is the assertion this test exists for: the edge holds two, both are
  // unread, and the third give is waiting for room rather than for a reader.
  assert_eq!(
    running.next_give(STILLNESS),
    None,
    "the third give must be waiting on a full edge"
  );

  // AND THE BOUND IS THE DECLARED ONE, read off the edge itself: two queued, and a third give
  // holding its item in a parked sender. There is nowhere else for anything to be.
  assert_eq!(
    running.inbox.len(),
    2,
    "the edge holds exactly what its declaration said it would"
  );
  assert_eq!(
    running.delivered(),
    vec![1, 2],
    "and nothing beyond the bound was ever handed over"
  );

  // READING IS WHAT RELEASES IT. Once this deployment starts taking items the origin runs to its
  // own end — which is what says the stall was this bound and not some other cause that would have
  // kept it stalled however much was read.
  let mut taken: Vec<u64> = Vec::new();
  while taken.len() < 5 {
    taken.extend(running.taken().into_iter().map(|(_, value)| value));
  }
  assert_eq!(taken, vec![1, 2, 3, 4, 5]);

  running.until_stopped();
  assert_eq!(running.ended(), Some(Fin::Spent));
  running.shutdown();
}

/// **A STOP MID-STREAM LOSES NOTHING ALREADY GIVEN**: what the consumer holds is exactly what the
/// origin's gives answered for.
///
/// The two lists are read from the two ends of the same edge, and the claim is that they are the
/// same list. A stop that raced the last give — an ending that dropped the sending half while an
/// item was in flight — would show up here as a delivered value the inbox never saw.
///
/// It also shows the wind-down's one honest edge: a give already BLOCKED cannot hear the stop, so
/// this deployment has to keep reading to let the origin out of it. That is the origin face's own
/// shape rather than the bridge's — `Feed::give` waits on a transport and nothing else — and it is
/// exactly why the framework being the reader is an improvement on a deployment that might not be.
#[test]
fn a_stop_mid_stream_leaves_the_consumer_exactly_what_was_delivered() {
  let mut running = Running::start(1_000);

  // Let a couple through so the stop lands mid-stream rather than before anything moved.
  assert_eq!(running.next_give(PATIENCE), Some(1));
  assert_eq!(running.next_give(PATIENCE), Some(2));

  running.stopper.announce();

  let mut seen: Vec<u64> = Vec::new();
  while running.ended().is_none() {
    seen.extend(running.taken().into_iter().map(|(_, value)| value));
    let _ = running.next_give(STILLNESS);
  }
  running.until_stopped();
  seen.extend(running.taken().into_iter().map(|(_, value)| value));

  assert_eq!(running.ended(), Some(Fin::Stopped), "it heard the stop");
  assert!(
    !seen.is_empty(),
    "the stop landed mid-stream, not before it"
  );
  assert_eq!(
    seen,
    running.delivered(),
    "the consumer's tail is exactly what the origin's gives answered for"
  );

  running.shutdown();
}

/// **THE EDGE CLOSES WITH THE ORIGIN'S LIFE — AND NOT BEFORE THE LAUNCH LETS GO.**
///
/// Both halves are the claim, and they are the two facts the layer already ran on rather than
/// anything the bridge added. The launch holds a sending half of every edge whose receiver was
/// taken, so nothing stops before it starts: a Spent origin's consumer is still open here. The
/// wind-down releases those halves, and from that moment the origin's own feed — already dropped
/// with its life — was the last one, so the stream ends.
///
/// No `End` crosses either way. `taken` is what says so: every message on this edge is a delivery.
#[test]
fn the_consumers_stream_ends_when_the_wind_down_releases_the_launchs_own_half() {
  let mut running = Running::start(2);
  running.until_stopped();
  assert_eq!(running.ended(), Some(Fin::Spent));
  assert_eq!(
    running.taken().len(),
    2,
    "both items crossed before the life ended"
  );

  // THE ORIGIN IS GONE and the stream is NOT over: the half the launch keeps is what holds it open,
  // and that is the posture that keeps a node from stopping before it has started.
  assert!(
    !running.inbox.is_disconnected(),
    "the launch still holds its own half of this edge"
  );

  running.shutdown();

  // AND NOW IT IS OVER, because the origin's feed was the only other one.
  assert!(
    running.inbox.is_disconnected(),
    "the wind-down released the last half but this origin's, and this origin's is long gone"
  );
  assert!(
    !running.stopper.announce(),
    "and the origin's life was over before the word was said"
  );
}