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
//! What the registry seat says, on its own — the round trip through a document lives in
//! `ingraph`'s `tests/registry_options.rs`, which is where a real `#[ingraph::graph]` expansion and
//! a real document meet, exactly as `graph_options.rs` covers [`crate::NodeSection`]'s own rack.
//! What is here is the type on its own terms: the shipped defaults, the merge `for_family` does, and
//! — where `serde` is on — the document shape this crate's own `#[derive(Deserialize)]` reads.

use core::{num::NonZeroUsize, time::Duration};

use super::{
  DEFAULT_BATCH_MAX_ITEMS, DEFAULT_BATCH_MAX_WAIT, DEFAULT_DEBOUNCE, DEFAULT_RETIRE_DRAIN,
  DEFAULT_SETTLE, RegistryOptions, RegistryOverride,
};

/// [`RegistryOptions::new`] states the shipped defaults verbatim, with no family override.
#[test]
fn new_holds_the_shipped_defaults() {
  let options = RegistryOptions::new();
  assert_eq!(options.debounce(), DEFAULT_DEBOUNCE);
  assert_eq!(options.batch_max_items(), DEFAULT_BATCH_MAX_ITEMS);
  assert_eq!(options.batch_max_wait(), DEFAULT_BATCH_MAX_WAIT);
  assert_eq!(options.retire_drain(), DEFAULT_RETIRE_DRAIN);
  assert_eq!(options.settle(), DEFAULT_SETTLE);
  assert_eq!(options.families().count(), 0);
}

/// One source of truth: `Default` states nothing `new` did not.
#[test]
fn default_delegates_to_new() {
  assert_eq!(RegistryOptions::default(), RegistryOptions::new());
}

/// The builder family round-trips, and `set_*` can narrow a value back to whatever `with_*` had
/// already stated — the same law [`RegistryOverride`]'s own `set_*` carries.
#[test]
fn the_builders_round_trip() {
  let five_seconds = Duration::from_secs(5);
  let stated = RegistryOptions::new().with_debounce(five_seconds);
  assert_eq!(stated.debounce(), five_seconds);

  let mut mutated = RegistryOptions::new();
  mutated.set_batch_max_items(NonZeroUsize::new(64).expect("64 is not zero"));
  assert_eq!(
    mutated.batch_max_items(),
    NonZeroUsize::new(64).expect("64 is not zero")
  );
}

/// A family nobody wrote an override for reads the defaults whole — absence is not enablement here,
/// every family runs, and the registry needs SOME tuning for the ones a deployment never named.
#[test]
fn for_family_with_no_override_reads_the_defaults_whole() {
  let options = RegistryOptions::new().with_debounce(Duration::from_secs(9));
  let resolved = options.for_family("nobody-wrote-this-one");
  assert_eq!(resolved, options.for_family("nobody-wrote-this-one"));
  assert_eq!(resolved.debounce(), Duration::from_secs(9));
  assert_eq!(resolved.batch_max_items(), DEFAULT_BATCH_MAX_ITEMS);
}

/// `[registry.media]` naming only `debounce` leaves every other knob reading the `[registry]`
/// table's OWN values — never the hardcoded shipped defaults if the deployment already moved those.
#[test]
fn for_family_folds_only_the_knobs_it_named_over_the_deployments_own_defaults() {
  let options = RegistryOptions::new()
    .with_batch_max_items(NonZeroUsize::new(20).expect("20 is not zero"))
    .with_family(
      "media",
      RegistryOverride::new().with_debounce(Duration::from_secs(1)),
    );

  let media = options.for_family("media");
  assert_eq!(media.debounce(), Duration::from_secs(1), "media's own word");
  assert_eq!(
    media.batch_max_items(),
    NonZeroUsize::new(20).expect("20 is not zero"),
    "media named nothing here, so the DEPLOYMENT's own default stands — not the shipped 10"
  );
  assert_eq!(media.batch_max_wait(), DEFAULT_BATCH_MAX_WAIT);
}

/// A resolved value has nothing left to resolve: `for_family`'s own output carries no family table
/// of its own to recurse into.
#[test]
fn a_resolved_value_carries_no_further_overrides() {
  let options = RegistryOptions::new().with_family("media", RegistryOverride::new());
  assert_eq!(options.for_family("media").families().count(), 0);
}

/// One call per family, replacing rather than accumulating — [`crate::Channels::tuned`]'s own rule.
#[test]
fn with_family_replaces_rather_than_accumulates() {
  let options = RegistryOptions::new()
    .with_family(
      "media",
      RegistryOverride::new().with_debounce(Duration::from_secs(1)),
    )
    .with_family(
      "media",
      RegistryOverride::new().with_debounce(Duration::from_secs(2)),
    );
  assert_eq!(options.families().count(), 1);
  assert_eq!(
    options.for_family("media").debounce(),
    Duration::from_secs(2)
  );
}

/// [`RegistryOptions::families`] is what an unknown-family cross-check would read, once something
/// exists to check against — see the module note on why that check is not this seat's to make.
#[test]
fn families_lists_every_override_written() {
  let options = RegistryOptions::new()
    .with_family("media", RegistryOverride::new())
    .with_family("video", RegistryOverride::new());
  let mut names: Vec<&str> = options.families().collect();
  names.sort_unstable();
  assert_eq!(names, ["media", "video"]);
}

/// [`RegistryOverride::set_debounce`] can narrow a value back to [`None`] — the same "back to
/// nothing" law [`crate::MongoOptions::set_read_concern`] carries.
#[test]
fn a_family_overrides_own_set_can_clear_back_to_none() {
  let mut over = RegistryOverride::new().with_debounce(Duration::from_secs(1));
  assert_eq!(over.debounce(), Some(Duration::from_secs(1)));
  over.set_debounce(None);
  assert_eq!(over.debounce(), None);
}

#[cfg(feature = "serde")]
mod document {
  use core::time::Duration;

  use super::{
    DEFAULT_BATCH_MAX_ITEMS, DEFAULT_DEBOUNCE, DEFAULT_RETIRE_DRAIN, RegistryOptions,
    RegistryOverride,
  };

  /// One deployment's whole `[registry]` document, read exactly as `graph_options.rs` reads a
  /// deployment's whole `AppOptions` document — `serde_json` rather than `toml`, so this suite needs
  /// no dev-dependency the crate does not already carry, and the words a document writes do not
  /// depend on which self-describing format holds them.
  fn parse(document: &str) -> Result<RegistryOptions, serde_json::Error> {
    serde_json::from_str(document)
  }

  /// `{}` IS the shipped defaults — every field is `#[serde(default = …)]`, so a document naming
  /// nothing parses rather than refusing a missing required key.
  #[test]
  fn an_empty_document_is_the_shipped_defaults() {
    assert_eq!(
      parse("{}").expect("an empty document parses"),
      RegistryOptions::new()
    );
  }

  /// The ruling's own worked example, verbatim: five defaults and one family's one override.
  #[test]
  fn the_rulings_worked_example_round_trips() {
    let parsed = parse(
      r#"{
        "debounce": "300ms",
        "batch_max_items": 10,
        "batch_max_wait": "500ms",
        "retire_drain": "30s",
        "settle": "0ms",
        "media": { "debounce": "1s" }
      }"#,
    )
    .expect("the ruling's own document parses");
    assert_eq!(
      parsed,
      RegistryOptions::new().with_family(
        "media",
        RegistryOverride::new().with_debounce(Duration::from_secs(1))
      )
    );
    assert_eq!(
      parsed.for_family("media").debounce(),
      Duration::from_secs(1)
    );
  }

  /// A document naming only ONE family touches only that family's ONE knob — every other family,
  /// and every other knob of the one it does name, keeps reading the defaults.
  #[test]
  fn a_partial_document_overrides_one_knob_of_one_family_only() {
    let parsed = parse(r#"{ "media": { "debounce": "1s" } }"#).expect("a partial document parses");
    assert_eq!(
      parsed,
      RegistryOptions::new().with_family(
        "media",
        RegistryOverride::new().with_debounce(Duration::from_secs(1)),
      )
    );
    assert_eq!(
      parsed.for_family("media").debounce(),
      Duration::from_secs(1)
    );
    assert_eq!(
      parsed.for_family("media").batch_max_items(),
      DEFAULT_BATCH_MAX_ITEMS
    );
    assert_eq!(
      parsed.for_family("video").debounce(),
      DEFAULT_DEBOUNCE,
      "a family this document never named reads the defaults whole"
    );
  }

  /// `humantime`'s familiar spellings — the grammar `ingraph::batch`'s own module note names for
  /// this exact seat, never jiff's (that is the request tier's, and it is a different knife).
  #[test]
  fn humantime_parses_the_familiar_spellings() {
    let parsed = parse(
      r#"{ "debounce": "1s", "batch_max_wait": "2m", "retire_drain": "30s", "settle": "0ms" }"#,
    )
    .expect("humantime's own spellings parse");
    assert_eq!(parsed.debounce(), Duration::from_secs(1));
    assert_eq!(parsed.batch_max_wait(), Duration::from_secs(120));
    assert_eq!(parsed.retire_drain(), DEFAULT_RETIRE_DRAIN);
    assert_eq!(parsed.settle(), Duration::ZERO);
  }

  /// A BARE NUMBER is refused rather than read as seconds, milliseconds or anything else a reader
  /// would have to guess — `humantime_serde` wants the text form, and only the text form.
  #[test]
  fn a_bare_number_is_refused_rather_than_guessed() {
    let refusal = parse(r#"{ "debounce": 300 }"#).expect_err("a bare number is not humantime");
    let sentence = refusal.to_string();
    assert!(sentence.contains("duration"), "{sentence}");
  }

  /// `NonZeroUsize` is what refuses a zero ceiling — no hand-written check, the type IS the check.
  #[test]
  fn a_zero_batch_ceiling_is_refused() {
    let refusal = parse(r#"{ "batch_max_items": 0 }"#).expect_err("zero is not a nonzero usize");
    let sentence = refusal.to_string();
    assert!(
      sentence.contains("nonzero") || sentence.contains("0"),
      "{sentence}"
    );
  }

  /// A family override naming a knob this shape does not have is refused BY NAME — the protection
  /// `deny_unknown_fields` buys everywhere else in this crate, moved one level down from the
  /// container (see the module note for why the container itself cannot carry the word).
  #[test]
  fn a_family_override_naming_an_unknown_knob_is_refused() {
    let refusal = parse(r#"{ "media": { "totally_unknown_knob": 5 } }"#)
      .expect_err("`totally_unknown_knob` is not one of the five");
    let sentence = refusal.to_string();
    assert!(sentence.contains("totally_unknown_knob"), "{sentence}");
    assert!(sentence.contains("unknown field"), "{sentence}");
  }

  /// A family NAMED after one of the five reserved knob words collides with that scalar field —
  /// `{"debounce": {...}}` reads as the `debounce` FIELD taking a map where a duration string
  /// belongs, and is refused as that type mismatch rather than silently becoming a family called
  /// `debounce`.
  #[test]
  fn a_family_named_after_a_reserved_knob_is_refused() {
    parse(r#"{ "debounce": { "batch_max_items": 1 } }"#)
      .expect_err("`debounce` is a reserved knob word, not an open family name");
  }

  /// A family whose table is written EMPTY is legal — it exists and overrides nothing, which is the
  /// same statement `[registry.media]` alone (no knob under it) makes in the ruling's own grammar.
  #[test]
  fn a_family_with_an_empty_table_overrides_nothing() {
    let parsed = parse(r#"{ "media": {} }"#).expect("an empty family table parses");
    assert_eq!(parsed.families().collect::<Vec<_>>(), ["media"]);
    assert_eq!(
      parsed.for_family("media"),
      RegistryOptions::new().for_family("anything-else")
    );
  }
}