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
use core::time::Duration;

use std::{
  sync::{
    Arc,
    atomic::{AtomicUsize, Ordering},
  },
  thread,
};

use super::super::{
  Delivery, Item, ItemId, Payload, PollUpstream, Rings, Sweeper, Wake, ack_channel, channel,
};

fn delivery(seq: u64) -> (Delivery<u64>, super::super::AckReceiver<ItemId>) {
  let (ack, answers) = ack_channel();
  (
    Delivery::new(Payload::One(Item::new(ItemId::new(seq), seq)), ack),
    answers,
  )
}

#[test]
fn a_delivery_arrives_as_the_data_variant_and_a_ring_as_the_sweep_one() {
  let (out, inbox) = channel::<ItemId, u64>(4);
  let (message, _answers) = delivery(1);
  out.deliver(message).expect("the inbox is open");
  assert!(out.nudge().ring());

  let mut kinds = Vec::new();
  for wake in inbox.drain() {
    kinds.push(match wake {
      Wake::Delivered(_) => "data",
      Wake::Sweep => "sweep",
      Wake::Tick(_) => "tick",
    });
  }
  assert_eq!(kinds, ["data", "sweep"]);
}

#[test]
fn a_tick_arrives_as_the_third_variant_and_names_its_source() {
  let (out, inbox) = channel::<ItemId, u64>(4);
  assert!(out.ticker(PollUpstream::new(1)).ring());
  let taken: Vec<Option<PollUpstream>> = inbox
    .drain()
    .map(|wake| match wake {
      Wake::Tick(tick) => Some(tick.upstream()),
      Wake::Delivered(_) | Wake::Sweep => None,
    })
    .collect();
  assert_eq!(taken, [Some(PollUpstream::new(1))]);
}

#[test]
fn a_full_edge_blocks_the_sender_and_never_drops_data() {
  // Capacity ONE, so the second delivery cannot be taken until the consumer takes the first. The
  // sender waiting — rather than dropping, or growing — is the whole backpressure posture.
  let (out, inbox) = channel::<ItemId, u64>(1);
  let (first, _a) = delivery(1);
  out.deliver(first).expect("room for one");
  assert_eq!(inbox.len(), 1, "the one slot is occupied");

  let sent = Arc::new(AtomicUsize::new(0));
  let writer = {
    let out = out.clone();
    let sent = sent.clone();
    thread::spawn(move || {
      for seq in 2..=4 {
        let (message, answers) = delivery(seq);
        out.deliver(message).expect("the inbox is open");
        drop(answers);
        sent.fetch_add(1, Ordering::SeqCst);
      }
    })
  };

  // Nothing gets through while the one slot is occupied.
  thread::sleep(Duration::from_millis(50));
  assert_eq!(sent.load(Ordering::SeqCst), 0);

  let mut taken = 0usize;
  while taken < 4 {
    match inbox.park(Duration::from_secs(2)) {
      Some(Wake::Delivered(_)) => taken += 1,
      Some(Wake::Sweep | Wake::Tick(_)) => {}
      None => panic!("the sender is still alive"),
    }
  }
  writer.join().expect("the writer thread");
  assert_eq!(sent.load(Ordering::SeqCst), 3);
  assert_eq!(taken, 4, "every delivery arrived; none was dropped");
}

#[test]
fn a_ring_coalesces_on_a_full_edge_instead_of_blocking_the_ringer() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  let nudge = out.nudge();
  // Fill the one slot with a ring, then ring a thousand times more: each finds it full, drops, and
  // returns at once. A wake carries no information, so a coalesced ring has lost nothing.
  assert!(nudge.ring());
  for _ in 0..1_000 {
    assert!(nudge.ring());
  }
  assert_eq!(inbox.len(), 1);
}

#[test]
fn a_ring_at_a_gone_consumer_reports_that_it_is_gone() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  let nudge = out.nudge();
  drop(inbox);
  assert!(!nudge.ring());
}

#[test]
fn delivering_to_a_gone_consumer_hands_the_delivery_back() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  drop(inbox);
  assert!(out.is_disconnected());
  let (message, _answers) = delivery(1);
  let returned = out.deliver(message).expect_err("the consumer is gone");
  assert_eq!(returned.payload().len(), 1);
}

#[test]
fn a_park_that_times_out_is_a_sweep_and_a_park_with_no_senders_is_shutdown() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  let woken = inbox.park(Duration::from_millis(20));
  assert!(matches!(woken, Some(Wake::Sweep)), "a timeout is a sweep");
  drop(out);
  assert!(
    inbox.park(Duration::from_millis(20)).is_none(),
    "every sender gone is shutdown"
  );
  assert!(inbox.is_disconnected());
}

#[test]
fn shutdown_waits_for_the_queue_to_empty_first() {
  // Disconnection is reported only once there is nothing left, which is what makes shutdown-by-drop
  // a DRAIN rather than a discard.
  let (out, inbox) = channel::<ItemId, u64>(4);
  for seq in 1..=3 {
    let (message, answers) = delivery(seq);
    out.deliver(message).expect("room");
    drop(answers);
  }
  drop(out);
  let mut taken = 0usize;
  while let Some(wake) = inbox.park(Duration::from_millis(50)) {
    if matches!(wake, Wake::Delivered(_)) {
      taken += 1;
    }
  }
  assert_eq!(taken, 3);
}

#[tokio::test]
async fn the_async_park_takes_data_and_the_ring_that_stands_in_for_its_timeout() {
  let (out, inbox) = channel::<ItemId, u64>(2);
  let (message, _answers) = delivery(1);
  out.deliver_async(message).await.expect("room");
  assert!(matches!(inbox.park_async().await, Some(Wake::Delivered(_))));

  // The async engine has no deadline receive, so its sweep is a ring on the same inbox.
  assert!(out.nudge().ring());
  assert!(matches!(inbox.park_async().await, Some(Wake::Sweep)));

  drop(out);
  assert!(inbox.park_async().await.is_none());
}

#[tokio::test]
async fn the_async_send_awaits_room_rather_than_dropping() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  let (first, _a) = delivery(1);
  out.deliver_async(first).await.expect("room for one");

  let writer = {
    let out = out.clone();
    tokio::spawn(async move {
      let (message, answers) = delivery(2);
      out.deliver_async(message).await.expect("eventually room");
      drop(answers);
    })
  };
  // The task cannot finish until a slot frees, and taking one is what frees it.
  assert!(matches!(inbox.park_async().await, Some(Wake::Delivered(_))));
  writer.await.expect("the writer task");
  assert!(matches!(inbox.park_async().await, Some(Wake::Delivered(_))));
}

#[test]
fn the_sweeper_rings_on_its_interval_and_stops_when_it_is_dropped() {
  let (out, inbox) = channel::<ItemId, u64>(8);
  let sweeper = Sweeper::spawn(Duration::from_millis(10), vec![Box::new(out.nudge())]);
  thread::sleep(Duration::from_millis(120));
  let rung = inbox.len();
  assert!(rung >= 2, "the clock ticked at least twice, saw {rung}");

  // Dropping JOINS the thread, so the count after it cannot move again.
  drop(sweeper);
  let settled = inbox.len();
  thread::sleep(Duration::from_millis(60));
  assert_eq!(inbox.len(), settled, "a dropped sweeper has stopped");
  drop(out);
}

#[test]
fn the_sweeper_rings_every_ringer_rather_than_stopping_at_the_first_live_one() {
  // The mutation this pins: `any(|r| r.ring())` short-circuits, so a graph's second node would
  // never be swept at all.
  let (first_out, first_in) = channel::<ItemId, u64>(8);
  let (second_out, second_in) = channel::<ItemId, u64>(8);
  let sweeper = Sweeper::spawn(
    Duration::from_millis(10),
    vec![Box::new(first_out.nudge()), Box::new(second_out.nudge())],
  );
  thread::sleep(Duration::from_millis(120));
  drop(sweeper);
  assert!(first_in.len() >= 2);
  assert!(second_in.len() >= 2, "the second ringer was rung too");
  drop((first_out, second_out));
}

#[test]
fn the_sweeper_ends_once_every_ringer_is_gone() {
  let (out, inbox) = channel::<ItemId, u64>(1);
  let sweeper = Sweeper::spawn(Duration::from_millis(5), vec![Box::new(out.nudge())]);
  drop(inbox);
  drop(out);
  // Nothing to assert but termination: dropping the handle joins, so a sweeper that had not noticed
  // its ringers were dead would hang here rather than fail.
  thread::sleep(Duration::from_millis(40));
  drop(sweeper);
}