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 batch's two triggers, its one bound, and the punctuation that beats both.
//!
//! 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::*;

/// `max_items`, for the tests that do not care what it is.
fn three() -> NonZeroUsize {
  NonZeroUsize::new(3).expect("three is not zero")
}

fn batcher() -> Batcher<u64> {
  Batcher::new(three(), Duration::from_millis(500))
}

/// The COUNT trigger: the push that reaches `max_items` says so, and the batch it yields is exactly
/// that many, in arrival order.
#[test]
fn a_batch_fills_at_max_items() {
  let now = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, now), Push::Queued);
  assert_eq!(batcher.push(2, now), Push::Queued);
  assert!(
    !batcher.ready(now),
    "two of three is not full, and no time has passed"
  );

  assert_eq!(batcher.push(3, now), Push::Full);
  assert!(batcher.ready(now), "the count alone makes it due");
  assert_eq!(batcher.len(), 3);
  assert_eq!(batcher.drain(), vec![1, 2, 3]);
}

/// **`max_items` is a BOUND and not only a trigger.** A driver that never acts on `Push::Full` still
/// cannot grow the batch past the ceiling — and the item it offered comes back rather than being
/// dropped or appended.
#[test]
fn a_full_batch_refuses_the_next_item_and_hands_it_back() {
  let now = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, now), Push::Queued);
  assert_eq!(batcher.push(2, now), Push::Queued);
  assert_eq!(batcher.push(3, now), Push::Full);

  assert_eq!(batcher.push(4, now), Push::Refused(4));
  assert_eq!(batcher.len(), 3, "the refusal changed nothing");

  // The recovery the refusal exists for: drain, then offer the item again.
  assert_eq!(batcher.drain(), vec![1, 2, 3]);
  assert_eq!(batcher.push(4, now), Push::Queued);
  assert_eq!(batcher.drain(), vec![4]);
}

/// The TIME trigger: a partial batch is due at its opening plus `max_wait`, and not a moment before.
#[test]
fn a_partial_batch_flushes_at_max_wait() {
  let opened = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, opened), Push::Queued);
  assert_eq!(
    batcher.deadline(),
    Some(opened + Duration::from_millis(500))
  );

  assert!(!batcher.ready(opened + Duration::from_millis(499)));
  assert!(batcher.ready(opened + Duration::from_millis(500)));
  assert!(batcher.ready(opened + Duration::from_secs(60)));
  assert_eq!(batcher.drain(), vec![1]);
}

/// **The wait is the BATCH's, not the item's.** A later arrival does not push the deadline out, so a
/// steady trickle lands on a fixed cadence instead of never.
#[test]
fn the_window_opens_at_the_first_item_and_no_later_one_moves_it() {
  let opened = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, opened), Push::Queued);
  assert_eq!(
    batcher.push(2, opened + Duration::from_millis(300)),
    Push::Queued
  );

  assert_eq!(
    batcher.deadline(),
    Some(opened + Duration::from_millis(500)),
    "the second item's arrival is not the batch's opening"
  );
}

/// **Punctuation beats the timer.** An END drains through the unconditional door, which asks nothing
/// about size and nothing about time — a batch neither full nor late comes out whole.
#[test]
fn punctuation_drains_a_partial_batch_regardless() {
  let opened = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, opened), Push::Queued);
  assert_eq!(batcher.push(2, opened), Push::Queued);
  assert!(!batcher.ready(opened), "neither trigger has fired");

  assert_eq!(batcher.drain(), vec![1, 2]);
  assert!(batcher.is_empty());
  assert_eq!(batcher.deadline(), None);
}

/// An empty batcher has nothing waiting to be late: no deadline, never ready, and an END on one
/// costs the driver the same single line it costs on a full one.
#[test]
fn an_empty_batcher_has_no_deadline() {
  let now = Instant::now();
  let mut batcher = batcher();

  assert!(batcher.is_empty());
  assert_eq!(batcher.len(), 0);
  assert_eq!(batcher.deadline(), None);
  assert!(!batcher.ready(now));
  assert!(!batcher.ready(now + Duration::from_secs(3_600)));
  assert_eq!(batcher.drain(), Vec::<u64>::new());
}

/// A drain RESETS the clock as well as the items: the next push opens a new batch whose deadline is
/// measured from itself, not from the batch that has already left.
#[test]
fn a_push_after_a_drain_reopens_the_window() {
  let opened = Instant::now();
  let mut batcher = batcher();

  assert_eq!(batcher.push(1, opened), Push::Queued);
  assert_eq!(batcher.drain(), vec![1]);
  assert_eq!(batcher.deadline(), None);

  let reopened = opened + Duration::from_secs(10);
  assert_eq!(batcher.push(2, reopened), Push::Queued);
  assert_eq!(
    batcher.deadline(),
    Some(reopened + Duration::from_millis(500)),
    "the second batch's clock starts at the second batch"
  );
  assert!(!batcher.ready(reopened));
}

/// The two knobs read back as they were given — what a driver builds its own park arithmetic on.
#[test]
fn the_knobs_read_back() {
  let batcher = batcher();

  assert_eq!(batcher.max_items(), three());
  assert_eq!(batcher.max_wait(), Duration::from_millis(500));
}

/// A ceiling of one is the degenerate batch, and it behaves: every push fills, every batch is one
/// item, and the count trigger fires without the timer being consulted at all.
#[test]
fn a_ceiling_of_one_fills_on_every_push() {
  let now = Instant::now();
  let mut batcher = Batcher::new(
    NonZeroUsize::new(1).expect("one is not zero"),
    Duration::from_millis(500),
  );

  assert_eq!(batcher.push(1, now), Push::Full);
  assert!(batcher.ready(now));
  assert_eq!(batcher.push(2, now), Push::Refused(2));
  assert_eq!(batcher.drain(), vec![1]);
  assert_eq!(batcher.push(2, now), Push::Full);
  assert_eq!(batcher.drain(), vec![2]);
}

/// A wait that cannot be added to an instant reads as the OPENING — the batch flushes at once rather
/// than being stranded behind a timer that can never fire. The documented degradation, pinned.
#[test]
fn an_unrepresentable_deadline_reads_as_due_now() {
  let opened = Instant::now();
  let mut batcher = Batcher::new(three(), Duration::MAX);

  assert_eq!(batcher.push(1, opened), Push::Queued);
  assert_eq!(
    batcher.deadline(),
    Some(opened),
    "no instant is `Duration::MAX` away, so the answer degrades to *now* and not to *never*"
  );
  assert!(batcher.ready(opened));
}