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::{thread, time::Instant};

use super::{
  super::{Cadence, ItemId, Policies, Rings, Sweeper, Taps, Ticks, Wake, channel},
  Clock, PollUpstream, Recurrence, Schedule, Seats, Swept, Unpolled,
};

/// The SHIPPED tick gate — what a deployment that said nothing about its clock runs under.
fn shipped() -> Ticks {
  Policies::new().ticks("clock", Taps::new())
}

/// Every upstream that came due at `at`, as a clock over `schedule` started at `start` reports it.
fn due(schedule: &Schedule, start: Instant, at: Instant) -> Vec<PollUpstream> {
  let mut clock = Clock::start(schedule, start);
  let mut ticked = Vec::new();
  clock.take_due(at, &mut ticked, &shipped());
  ticked
}

/// The ticks queued on `inbox`, in arrival order, with everything else named.
fn ticks<K, T>(inbox: &super::super::Inbox<K, T>) -> Vec<Option<PollUpstream>> {
  inbox
    .drain()
    .map(|wake| match wake {
      Wake::Tick(tick) => Some(tick.upstream()),
      Wake::Sweep | Wake::Delivered(_) => None,
    })
    .collect()
}

#[test]
fn a_poll_source_is_its_index_and_orders_by_it() {
  assert_eq!(PollUpstream::new(2).index(), 2);
  assert_eq!(PollUpstream::new(2).to_string(), "poll#2");
  assert!(PollUpstream::new(0) < PollUpstream::new(1));
}

#[test]
fn a_schedule_is_its_sources_in_declaration_order() {
  let schedule = Schedule::new()
    .every(Duration::from_secs(600))
    .every(Duration::from_secs(3_600));
  assert_eq!(schedule.len(), 2);
  assert!(!schedule.is_empty());
  assert_eq!(
    schedule.interval(PollUpstream::new(0)),
    Some(Duration::from_secs(600))
  );
  assert_eq!(
    schedule.interval(PollUpstream::new(1)),
    Some(Duration::from_secs(3_600))
  );
  assert_eq!(schedule.interval(PollUpstream::new(2)), None);
  assert!(Schedule::new().is_empty());
}

#[test]
fn a_clock_parks_until_the_nearest_source_or_the_sweep_whichever_is_sooner() {
  let start = Instant::now();
  let schedule = Schedule::new()
    .every(Duration::from_millis(10))
    .every(Duration::from_millis(100));
  let clock = Clock::start(&schedule, start);
  assert_eq!(
    clock.park_for(Duration::from_secs(1), start),
    Duration::from_millis(10),
    "the nearest upstream is sooner than the sweep"
  );
  assert_eq!(
    clock.park_for(Duration::from_millis(5), start),
    Duration::from_millis(5),
    "the sweep is sooner than any upstream"
  );
  // A node with no poll upstream gets its sweep back untouched, which is what makes the poll arm cost
  // an ordinary resident nothing at all.
  assert_eq!(
    Clock::start(&Schedule::new(), start).park_for(Duration::from_secs(1), start),
    Duration::from_secs(1)
  );
}

#[test]
fn each_source_comes_due_on_its_own_interval_and_never_on_anothers() {
  // THE MUTATION: one deadline shared by every upstream. Then the fast upstream's first tick would
  // reschedule the slow one too, and `[poll#0]` below would be `[poll#0, poll#1]` — a compactor
  // dragged along at a reaper's cadence.
  let start = Instant::now();
  let schedule = Schedule::new()
    .every(Duration::from_millis(10))
    .every(Duration::from_millis(100));

  assert_eq!(
    due(&schedule, start, start + Duration::from_millis(15)),
    [PollUpstream::new(0)],
    "only the fast upstream is due"
  );
  assert_eq!(
    due(&schedule, start, start + Duration::from_millis(105)),
    [PollUpstream::new(0), PollUpstream::new(1)],
    "both are due once the slow one's interval has passed"
  );
  assert!(
    due(&schedule, start, start + Duration::from_millis(5)).is_empty(),
    "the first tick falls one interval after launch, as a sweeper's does"
  );
}

#[test]
fn a_source_that_was_looked_at_late_is_one_look_and_not_a_burst_of_catch_up_ticks() {
  let start = Instant::now();
  let schedule = Schedule::new().every(Duration::from_millis(10));
  let mut clock = Clock::start(&schedule, start);

  // Three intervals late, and still ONE look: a tick says "look at this store again", and saying it
  // four times over is four walks of a store that only changed once.
  let mut ticked = Vec::new();
  clock.take_due(start + Duration::from_millis(35), &mut ticked, &shipped());
  assert_eq!(ticked, [PollUpstream::new(0)]);

  // Rescheduled from NOW rather than from the deadline it missed: nothing is due five milliseconds
  // later, where a `due += every` clock would still be paying off its debt.
  ticked.clear();
  clock.take_due(start + Duration::from_millis(40), &mut ticked, &shipped());
  assert!(ticked.is_empty());
  clock.take_due(start + Duration::from_millis(46), &mut ticked, &shipped());
  assert_eq!(ticked, [PollUpstream::new(0)]);
}

#[test]
fn a_bursting_source_is_one_tick_and_never_swallows_another_sources() {
  // THE MUTATION: ONE coalescing cell shared by every ticker. Then the reaper's first ring claims
  // it, its next thousand coalesce — which is right — and the compactor's ring coalesces into the
  // reaper's, which is starvation: the inbox would hold `[Some(poll#0)]` and the slow upstream would
  // never be looked at at all.
  let (out, inbox) = channel::<ItemId, u64>(8);
  let fast = out.ticker(PollUpstream::new(0));
  let slow = out.ticker(PollUpstream::new(1));

  for _ in 0..1_000 {
    assert!(fast.ring());
  }
  assert!(slow.ring());

  assert_eq!(
    ticks(&inbox),
    [Some(PollUpstream::new(0)), Some(PollUpstream::new(1))],
    "one look per upstream, and the slow upstream's is still there"
  );
}

#[test]
fn taking_a_tick_frees_its_source_to_ring_again() {
  // The cell travels with the tick, so consuming one is what opens the window. Without that, a
  // upstream ticks exactly once in the process's life.
  let (out, inbox) = channel::<ItemId, u64>(8);
  let ticker = out.ticker(PollUpstream::new(0));
  assert!(ticker.ring());
  assert!(ticker.ring(), "coalesced into the one already queued");
  assert_eq!(inbox.len(), 1);

  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(0))]);
  assert!(ticker.ring());
  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(0))], "and again");
}

#[test]
fn a_tick_with_nowhere_to_go_leaves_its_cell_as_it_found_it() {
  // A full inbox is an inbox with work in it, so the consumer is about to look anyway and this tick
  // has lost nothing. What it must NOT do is leave the cell claimed: nobody will ever consume the
  // tick that was never queued, so the upstream would go silent for good.
  let (out, inbox) = channel::<ItemId, u64>(1);
  let ticker = out.ticker(PollUpstream::new(0));
  assert!(out.nudge().ring(), "the one slot is taken by a sweep");
  assert!(ticker.ring(), "no room, and the ringer is not blocked");
  assert_eq!(inbox.len(), 1);

  assert_eq!(ticks(&inbox), [None], "the sweep, and no tick");
  assert!(ticker.ring());
  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(0))]);
}

#[test]
fn a_ticker_clone_is_the_same_source_sharing_the_same_cell() {
  // Two handles to one upstream are one upstream: a clone that minted a cell of its own would double
  // the looks a burst becomes.
  let (out, inbox) = channel::<ItemId, u64>(8);
  let ticker = out.ticker(PollUpstream::new(3));
  let twin = ticker.clone();
  assert_eq!(twin.upstream(), PollUpstream::new(3));
  assert!(ticker.ring());
  assert!(twin.ring());
  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(3))]);
}

#[test]
fn a_ticker_at_a_gone_consumer_reports_that_it_is_gone() {
  let (out, inbox) = channel::<ItemId, u64>(8);
  let ticker = out.ticker(PollUpstream::new(0));
  drop(inbox);
  assert!(!ticker.ring());
  // Still gone with its cell claimed, which is what a sweeper asks about on the round after the one
  // that filled it.
  assert!(!ticker.ring());
}

#[test]
fn a_schedules_cadences_pair_each_source_with_its_own_interval() {
  let (out, inbox) = channel::<ItemId, u64>(8);
  let schedule = Schedule::new()
    .every(Duration::from_millis(10))
    .every(Duration::from_millis(100));
  let cadences = schedule.cadences(&out);
  assert_eq!(cadences.len(), 2);
  assert_eq!(cadences[0].until_next(), Some(Duration::from_millis(10)));
  assert_eq!(cadences[1].until_next(), Some(Duration::from_millis(100)));

  // And each rings under the position it was minted for — the pairing is the whole reason this is
  // one call rather than two the caller has to keep in step.
  assert!(cadences[1].ring());
  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(1))]);
}

#[test]
fn a_sweeper_rings_each_cadence_at_its_own_rate_from_one_thread() {
  // Nudges rather than tickers, because what is under test is the CLOCK: a nudge has no cell, so
  // every ring the sweeper makes is visible without a consumer draining between them.
  let (fast_out, fast_in) = channel::<ItemId, u64>(256);
  let (slow_out, slow_in) = channel::<ItemId, u64>(256);
  let sweeper = Sweeper::ticking(vec![
    Cadence::new(Duration::from_millis(5), Box::new(fast_out.nudge())),
    Cadence::new(Duration::from_millis(80), Box::new(slow_out.nudge())),
  ]);
  thread::sleep(Duration::from_millis(250));
  // Dropping JOINS the clock thread, so neither count can move after this line.
  drop(sweeper);

  let fast = fast_in.len();
  let slow = slow_in.len();
  assert!(fast >= 5, "the fast cadence rang {fast} times");
  assert!(slow >= 1, "the slow cadence rang at all: {slow}");
  assert!(
    fast > slow,
    "each cadence keeps its own rate: fast {fast}, slow {slow}"
  );
  drop((fast_out, slow_out));
}

#[test]
fn a_sweeper_with_no_cadence_stops_rather_than_waiting_for_one() {
  // Nothing to assert but termination: dropping the handle joins, so a clock that parked on an
  // empty table would hang here rather than fail.
  drop(Sweeper::ticking(Vec::new()));
}

#[tokio::test]
async fn a_unit_that_declared_no_poll_source_sweeps_nothing() {
  // No `impl Seats` is written for this type anywhere. The absent lending is what makes the
  // resident's loop compile for a node that has no sweep entry to call.
  struct Titling;

  let mut node = Titling;
  let mut absent = Unpolled;
  assert_eq!(
    absent.seat(&mut node, PollUpstream::new(0)).await,
    Ok(Swept::Ran(()))
  );
}

/// A schedule mixes the two cadences freely, and each entry keeps its own — which is the whole of
/// what "dual-cadence" means at this layer.
#[test]
fn a_schedule_mixes_intervals_and_calendars() {
  let schedule = Schedule::new()
    .every(Duration::from_secs(600))
    .cron("0 3 * * *")
    .expect("a nightly expression")
    .cron_in("*/15 * * * *", "Etc/UTC")
    .expect("a quarter-hourly expression in a named zone");
  assert_eq!(schedule.len(), 3);

  // `interval` NARROWS: it answers for the entry that has one and says nothing for the two that
  // keep a calendar, which is what `recurrence` is for.
  assert_eq!(
    schedule.interval(PollUpstream::new(0)),
    Some(Duration::from_secs(600))
  );
  assert_eq!(schedule.interval(PollUpstream::new(1)), None);
  assert!(matches!(
    schedule.recurrence(PollUpstream::new(1)),
    Some(Recurrence::Calendar(_))
  ));
  let Some(Recurrence::Calendar(calendar)) = schedule.recurrence(PollUpstream::new(2)) else {
    panic!("the third entry keeps a calendar");
  };
  assert_eq!(calendar.expression(), "*/15 * * * *");
  assert!(schedule.recurrence(PollUpstream::new(3)).is_none());
}

/// A garbage expression is refused at the door rather than becoming an entry that never fires.
#[test]
fn a_schedule_refuses_an_expression_that_is_not_one() {
  assert!(Schedule::new().cron("99 3 * * *").is_err());
  assert!(Schedule::new().cron_in("0 3 * * *", "Not/AZone").is_err());
}

/// The ONE next-due core answers for both arms, and a clock reads it the same way either way.
#[test]
fn one_next_due_core_answers_for_both_arms() {
  assert_eq!(
    Recurrence::Every(Duration::from_secs(600)).until_next(),
    Some(Duration::from_secs(600))
  );
  let quarterly = Recurrence::Calendar(
    super::Calendar::parse_in("*/15 * * * *", "Etc/UTC").expect("a quarter-hourly expression"),
  );
  let wait = quarterly.until_next().expect("always due again");
  assert!(wait <= Duration::from_secs(15 * 60), "{wait:?}");
}

/// The thread engine's clock schedules a calendar entry by exactly the line it schedules an
/// interval one by, so a mixed node parks on whichever comes first.
#[test]
fn a_clock_parks_on_whichever_cadence_is_nearest_across_both_arms() {
  let start = Instant::now();
  let schedule = Schedule::new()
    .cron_in("*/15 * * * *", "Etc/UTC")
    .expect("a quarter-hourly expression")
    .every(Duration::from_millis(10));
  let clock = Clock::start(&schedule, start);
  // The interval entry is ten milliseconds away and the calendar one is at most a quarter of an
  // hour, so the interval is what the park is cut to.
  assert_eq!(
    clock.park_for(Duration::from_secs(60), start),
    Duration::from_millis(10)
  );

  // And the calendar entry is not due at once, which is what a clock that read it as an interval of
  // zero would report.
  assert_eq!(
    due(&schedule, start, start + Duration::from_millis(20)),
    [PollUpstream::new(1)]
  );
}

/// A schedule's cadences carry both arms, in declaration order, each ringing its own position.
#[test]
fn a_schedules_cadences_carry_both_arms() {
  let (out, inbox) = channel::<ItemId, u64>(8);
  let schedule = Schedule::new()
    .every(Duration::from_millis(10))
    .cron_in("0 3 * * *", "Etc/UTC")
    .expect("a nightly expression");
  let cadences = schedule.cadences(&out);
  assert_eq!(cadences.len(), 2);
  assert!(matches!(cadences[0].recurrence(), Recurrence::Every(_)));
  assert!(matches!(cadences[1].recurrence(), Recurrence::Calendar(_)));
  assert!(cadences[1].ring());
  assert_eq!(ticks(&inbox), [Some(PollUpstream::new(1))]);
}