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::num::NonZeroUsize;

use super::{
  DEFAULT_FEED_DEPTH, FeedContext, FeedPolicy, Fixed, MemoryAware, MemoryProbe, Pressure, Steady,
  Unpressured,
};
use crate::BoxedError;

fn depth(n: usize) -> NonZeroUsize {
  NonZeroUsize::new(n).expect("the test's own depth")
}

fn ctx<'a>(in_flight: usize, probe: &'a dyn MemoryProbe) -> FeedContext<'a> {
  FeedContext::new(in_flight, depth(4), probe)
}

/// A probe that cannot read — the failure arm every deployment eventually meets.
#[derive(Debug, derive_more::Display)]
#[display("this probe is unwell")]
struct Unwell;

impl core::error::Error for Unwell {}

#[derive(Debug)]
struct Blind;

impl MemoryProbe for Blind {
  fn pressure(&self) -> Result<Pressure, BoxedError> {
    Err(Box::new(Unwell))
  }
}

#[test]
fn a_reading_is_clamped_into_its_own_range() {
  assert_eq!(Pressure::of(-3.0), Pressure::NONE);
  assert_eq!(Pressure::of(7.0), Pressure::CRITICAL);
  assert_eq!(Pressure::of(f64::NAN), Pressure::NONE);
  assert!((Pressure::of(0.25).fraction() - 0.25).abs() < f64::EPSILON);
}

#[test]
fn the_shipped_probe_reads_no_pressure_and_cannot_fail() {
  assert_eq!(
    Unpressured
      .pressure()
      .expect("the shipped probe never fails"),
    Pressure::NONE
  );
}

#[test]
fn a_probe_that_cannot_read_widens_rather_than_starves() {
  // The one place a failed reading is turned into a value, and it is the WIDENING one: a pipeline
  // must not be throttled because a probe could not find out whether it should be.
  let blind = Blind;
  assert_eq!(ctx(0, &blind).pressure(), Pressure::NONE);
  let policy = MemoryAware::between(depth(4), depth(64));
  assert_eq!(policy.capacity(&ctx(0, &blind)), depth(64));
}

#[test]
fn the_shipped_policy_answers_the_measured_knee() {
  let probe = Unpressured;
  assert_eq!(
    Fixed::default().capacity(&ctx(0, &probe)),
    DEFAULT_FEED_DEPTH
  );
  assert_eq!(Fixed::default().depth(), DEFAULT_FEED_DEPTH);
  assert_eq!(Fixed::of(depth(7)).capacity(&ctx(3, &probe)), depth(7));
}

#[test]
fn memory_aware_takes_its_ceiling_with_headroom_and_its_floor_under_pressure() {
  let policy = MemoryAware::between(depth(4), depth(64));
  assert_eq!(policy.floor(), depth(4));
  assert_eq!(policy.ceiling(), depth(64));

  let calm = Steady::at(Pressure::NONE);
  assert_eq!(policy.capacity(&ctx(0, &calm)), depth(64));

  let dire = Steady::at(Pressure::CRITICAL);
  assert_eq!(policy.capacity(&ctx(0, &dire)), depth(4));

  // Half way is half the span shed, and never outside the two bounds it was given.
  let half = Steady::at(Pressure::of(0.5));
  let scaled = policy.capacity(&ctx(0, &half));
  assert_eq!(scaled, depth(34));
  assert!(scaled >= policy.floor() && scaled <= policy.ceiling());
}

#[test]
fn a_swapped_pair_degrades_to_the_floor_rather_than_to_a_refusal() {
  let policy = MemoryAware::between(depth(64), depth(4));
  let dire = Steady::at(Pressure::CRITICAL);
  let calm = Steady::at(Pressure::NONE);
  assert_eq!(policy.capacity(&ctx(0, &dire)), depth(64));
  assert_eq!(policy.capacity(&ctx(0, &calm)), depth(64));
}

#[test]
fn the_context_carries_what_the_ruling_says_it_carries() {
  let probe = Steady::at(Pressure::of(0.25));
  let ctx = FeedContext::new(3, depth(8), &probe);
  assert_eq!(ctx.in_flight(), 3);
  assert_eq!(ctx.width(), depth(8));
  assert_eq!(ctx.pressure(), Pressure::of(0.25));
  assert_eq!(
    ctx.probe().pressure().expect("the pinned probe answers"),
    Pressure::of(0.25)
  );
  // The probe is a trait object with no `Debug`, so the rendering prints the READING instead.
  let rendered = format!("{ctx:?}");
  assert!(rendered.contains("in_flight: 3"), "{rendered}");
  assert!(rendered.contains("pressure"), "{rendered}");
}

/// The one real platform reading in this round. It asserts about the SHAPE and never about the
/// number: what the machine running the suite has left is not something a test can pin.
#[cfg(target_os = "macos")]
#[test]
fn the_darwin_probe_reads_one_of_the_three_levels() {
  let reading = super::Darwin
    .pressure()
    .expect("`kern.memorystatus_vm_pressure_level` is present on every supported Darwin");
  assert!(
    reading == Pressure::NONE || reading == Pressure::of(0.5) || reading == Pressure::CRITICAL,
    "the mapping has exactly three landing places, and this read {reading:?}"
  );
}