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
//! The quiet window: the reset, the independence between keys, the cancel, and the property that
//! nothing ripens early no matter how the touches interleave.
//!
//! The clock is FAKE and needs no apparatus to be: `now` is an argument, so a base instant and some
//! arithmetic exercise a 500 ms window in microseconds and with no sleeping anywhere.

use super::*;

const QUIET: Duration = Duration::from_millis(500);

fn debounce() -> Debounce<u64> {
  Debounce::new(QUIET)
}

fn ms(millis: u64) -> Duration {
  Duration::from_millis(millis)
}

/// **The reset is the whole point.** `create` + `modify` + `modify` is ONE intake, at the last touch
/// plus the window — not three, and not one at the first touch plus the window.
#[test]
fn a_second_touch_resets_the_window() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(7, start);
  debounce.touch(7, start + ms(10));
  debounce.touch(7, start + ms(20));

  assert_eq!(debounce.len(), 1, "three touches, one pending key");
  assert_eq!(debounce.deadline(), Some(start + ms(520)));

  assert!(
    debounce.ripe(start + ms(500)).is_empty(),
    "the FIRST touch plus the window is not the answer — the window restarted twice"
  );
  assert!(debounce.ripe(start + ms(519)).is_empty());
  assert_eq!(debounce.ripe(start + ms(520)), vec![7]);
  assert!(debounce.is_empty());
  assert_eq!(debounce.deadline(), None);
}

/// A busy key does not hold a quiet one back: each key's window is its own.
#[test]
fn distinct_keys_ripen_independently() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(1, start);
  debounce.touch(2, start + ms(100));
  // Key 2 is re-touched; key 1 is not, and is unaffected.
  debounce.touch(2, start + ms(400));

  assert_eq!(debounce.len(), 2);
  assert_eq!(debounce.deadline(), Some(start + ms(500)));

  assert_eq!(debounce.ripe(start + ms(500)), vec![1]);
  assert_eq!(
    debounce.deadline(),
    Some(start + ms(900)),
    "the head moves on to the key that is still pending"
  );
  assert!(debounce.ripe(start + ms(899)).is_empty());
  assert_eq!(debounce.ripe(start + ms(900)), vec![2]);
}

/// Several keys coming due at once arrive in RIPENING order, and within one instant in touch order —
/// the schedule is ordered by both, so the answer is deterministic rather than a hash walk.
#[test]
fn ripe_keys_come_back_in_ripening_order() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(30, start + ms(30));
  debounce.touch(10, start + ms(10));
  debounce.touch(20, start + ms(20));
  // Two more at one instant: their order between themselves is the order they were touched in.
  debounce.touch(41, start + ms(40));
  debounce.touch(42, start + ms(40));

  assert_eq!(debounce.ripe(start + ms(1_000)), vec![10, 20, 30, 41, 42]);
}

/// A retirement arriving mid-window drops the pending intake, and says whether there was one.
#[test]
fn a_cancel_drops_the_pending_intake() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(1, start);
  debounce.touch(2, start);

  assert!(debounce.cancel(&1), "there was a pending intake for key 1");
  assert!(!debounce.cancel(&1), "and now there is not");
  assert!(
    !debounce.cancel(&99),
    "a key that was never touched cancels to false"
  );

  assert_eq!(debounce.len(), 1);
  assert_eq!(
    debounce.ripe(start + ms(1_000)),
    vec![2],
    "the cancelled key left no entry behind in the schedule"
  );
}

/// A cancelled key is not a poisoned key: touching it again opens an ordinary window.
#[test]
fn a_cancelled_key_can_be_touched_again() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(1, start);
  assert!(debounce.cancel(&1));
  assert_eq!(debounce.deadline(), None);

  debounce.touch(1, start + ms(100));
  assert_eq!(debounce.deadline(), Some(start + ms(600)));
  assert_eq!(debounce.ripe(start + ms(600)), vec![1]);
}

/// Ripening ends the window rather than suspending it: the next touch starts a fresh one.
#[test]
fn a_touch_after_a_ripe_opens_a_fresh_window() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(1, start);
  assert_eq!(debounce.ripe(start + ms(500)), vec![1]);

  debounce.touch(1, start + ms(600));
  assert_eq!(debounce.deadline(), Some(start + ms(1_100)));
  assert_eq!(debounce.ripe(start + ms(1_100)), vec![1]);
}

/// **A thousand touches on one key are one intake, and leave ONE entry behind.**
///
/// The count is the visible half of the law and the schedule size is the load-bearing half: a design
/// that left superseded entries in place would answer the same `vec![7]` here while carrying 999
/// dead rows, and would wake a driving loop once for each of them. The deadline assertion is the
/// same statement from the other side — the head is the LAST touch's, not the first's.
#[test]
fn a_burst_on_one_key_leaves_one_entry_and_ripens_once() {
  let start = Instant::now();
  let mut debounce = debounce();

  for step in 0..1_000 {
    debounce.touch(7, start + ms(step));
  }

  assert_eq!(debounce.len(), 1);
  assert_eq!(
    debounce.due.len(),
    1,
    "the schedule holds no superseded entries"
  );
  assert_eq!(debounce.deadline(), Some(start + ms(999 + 500)));

  assert!(debounce.ripe(start + ms(1_498)).is_empty());
  assert_eq!(debounce.ripe(start + ms(1_499)), vec![7]);
  assert!(debounce.is_empty());
  assert_eq!(debounce.due.len(), 0);
}

/// Two touches at the SAME instant are still one pending key.
///
/// The case the sequence number under the slot exists for: without it the second touch would address
/// the first one's entry, and *remove the old, insert the new* would either leave two entries or
/// delete the one it had just written.
#[test]
fn a_re_touch_at_the_same_instant_leaves_one_entry() {
  let start = Instant::now();
  let mut debounce = debounce();

  debounce.touch(1, start);
  debounce.touch(1, start);

  assert_eq!(debounce.len(), 1);
  assert_eq!(debounce.due.len(), 1);
  assert_eq!(debounce.deadline(), Some(start + QUIET));
  assert_eq!(debounce.ripe(start + QUIET), vec![1]);
  assert!(debounce.is_empty());
  assert_eq!(debounce.due.len(), 0);
}

/// A deterministic pseudo-random source — a burst pattern that does not depend on a dev-dependency
/// and replays byte-for-byte on every machine.
struct Lcg(u64);

impl Lcg {
  const fn new(seed: u64) -> Self {
    Self(seed)
  }

  fn next(&mut self) -> u64 {
    self.0 = self
      .0
      .wrapping_mul(6_364_136_223_846_793_005)
      .wrapping_add(1_442_695_040_888_963_407);
    self.0 >> 33
  }
}

/// **No key EVER comes back before its last touch plus the window**, however the touches interleave.
///
/// The property the whole type exists to hold, run over eight keys and two thousand interleaved
/// steps of touching and harvesting. The bookkeeping is the test's own: the last touch per key, kept
/// beside the machine and compared against every key it hands back.
#[test]
fn no_key_ripens_before_its_last_touch_plus_the_window() {
  let start = Instant::now();
  let mut debounce = Debounce::<u8>::new(QUIET);
  let mut last_touch: HashMap<u8, Instant> = HashMap::new();
  let mut rng = Lcg::new(0x5eed_1234);
  let mut now = start;
  let mut harvested = 0_usize;

  for step in 0..2_000 {
    now += ms(rng.next() % 150);

    // Touches stop well before the run does, so the tail drains everything that is still pending.
    if step < 1_500 && !rng.next().is_multiple_of(3) {
      let key = (rng.next() % 8) as u8;
      debounce.touch(key, now);
      last_touch.insert(key, now);
    }

    for key in debounce.ripe(now) {
      let touched = last_touch
        .remove(&key)
        .expect("a key came back that was never touched");
      assert!(
        now >= touched + QUIET,
        "key {key} ripened at {now:?}, before its last touch {touched:?} plus {QUIET:?}"
      );
      harvested += 1;
    }
  }

  assert!(
    last_touch.is_empty(),
    "every touched key ripened once the touching stopped"
  );
  assert!(
    harvested > 8,
    "the run exercised more than one round of ripening"
  );
  assert!(debounce.is_empty());
}

/// **The deadline alone is enough to drive the machine.** Parking on exactly what it reports — never
/// polling, never guessing — takes every key out, and each report is the true earliest.
#[test]
fn parking_on_the_deadline_alone_takes_every_key_out() {
  let start = Instant::now();
  let mut debounce = debounce();
  let mut rng = Lcg::new(0x0d15_ea5e);

  let mut expected: Vec<(Instant, u64)> = Vec::new();
  for key in 0..32 {
    let touched = start + ms(rng.next() % 1_000);
    debounce.touch(key, touched);
    expected.push((touched + QUIET, key));
  }
  expected.sort_unstable();

  let mut taken: Vec<(Instant, u64)> = Vec::new();
  while let Some(deadline) = debounce.deadline() {
    let before = taken.len();
    for key in debounce.ripe(deadline) {
      taken.push((deadline, key));
    }
    assert!(
      taken.len() > before,
      "a reported deadline that yields nothing at that instant would spin this loop forever"
    );
  }

  assert_eq!(
    taken, expected,
    "every key, at exactly the instant it was due"
  );
}