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 crate::{Context, Resources};
use core::{convert::Infallible, time::Duration};

use crate::{
  Delivery, Effect, Emitter, Listen, Operator,
  drive::{AckMode, ChannelOptions},
};

use super::{Blueprint, Declared, Upstream};

/// A head: nothing inside the graph feeds it.
struct Head;

impl Operator for Head {
  type Error = Infallible;
  type In = String;
  type Out = String;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<Self::In>,
    _emitter: &mut Emitter<Self::Out>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Head {
  const EFFECT: Effect = Effect::Pure;

  type Channels = crate::Unchanneled;
  type Options = ();
  type Mode = crate::Block;
  type Pair = crate::Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// A leaf drawing from the head, at the depth its author shipped.
struct Leaf;

impl Operator for Leaf {
  type Error = Infallible;
  type In = String;
  type Out = String;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<Self::In>,
    _emitter: &mut Emitter<Self::Out>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Leaf {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  const UPSTREAMS: &'static [Upstream] =
    &[Upstream::of::<Head>("Head").channelled(ChannelOptions::Bounded(4))];

  type Channels = crate::Unchanneled;
  type Options = ();
  type Mode = crate::Block;
  type Pair = crate::Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// A leaf whose declaration names an upstream nobody mounts.
struct Stray;

impl Operator for Stray {
  type Error = Infallible;
  type In = String;
  type Out = String;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<Self::In>,
    _emitter: &mut Emitter<Self::Out>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Stray {
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;
  const UPSTREAMS: &'static [Upstream] = &[Upstream::of::<u32>("other::Missing")];

  type Channels = crate::Unchanneled;
  type Options = ();
  type Mode = crate::Block;
  type Pair = crate::Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// **THE JOIN.** Two declarations, no hand-written edge: the leaf names its upstream by TYPE and the
/// registry finds the mount that holds it. What comes out is the arrangement nobody wrote.
#[test]
fn the_registry_joins_an_edge_nobody_wired() {
  let mut blueprint = Blueprint::new();
  let head = blueprint.node::<Head>("head");
  let leaf = blueprint.node::<Leaf>("leaf");
  let plan = blueprint.into_plan().expect("two declarations, one edge");
  let wired = plan
    .with_enablement(crate::Enablement::new().launching("head").launching("leaf"))
    .validate()
    .expect("the arrangement the declarations make");

  let edges = wired.graph().edges();
  assert_eq!(edges.len(), 1, "one declared upstream is one edge");
  assert_eq!(edges[0].from(), head);
  assert_eq!(edges[0].to(), leaf);
  assert_eq!(
    wired.node(leaf).map(|node| node.effect()),
    Some(Effect::Lands),
    "the leaf's own EFFECT reached the floor"
  );
  assert!(
    wired.node(leaf).is_some_and(|node| node.holds_lane()),
    "and so did the lane it holds"
  );
}

/// **THE AUTHOR'S CHANNEL REACHES THE FLOOR THROUGH THE JOIN** — S3b's F6, closed. The declared
/// depth used to be carried to `UpstreamWiring::with_channel` by a hand; the facts trait states it and
/// the join spends it.
#[test]
fn a_declared_channel_reaches_the_floor_without_a_hand() {
  let mut blueprint = Blueprint::new();
  blueprint.node::<Head>("head");
  let leaf = blueprint.node::<Leaf>("leaf");
  let wired = blueprint
    .into_plan()
    .expect("two declarations")
    .with_enablement(crate::Enablement::new().launching("head").launching("leaf"))
    .validate()
    .expect("the arrangement");

  assert_eq!(
    wired.channel(leaf, 0),
    ChannelOptions::Bounded(4),
    "the author's `channel = bounded(4)` is what the edge opens at"
  );
}

/// **AN UPSTREAM THE ROOT DOES NOT MOUNT IS REFUSED BY NAME**, and the sentence reads back the path
/// the declaration wrote.
#[test]
fn a_source_naming_no_mounted_node_is_refused() {
  let mut blueprint = Blueprint::new();
  blueprint.node::<Stray>("stray");
  let refusal = blueprint
    .into_plan()
    .expect_err("a subscription to nothing is not an arrangement");
  let sentence = refusal.to_string();
  assert!(sentence.contains("stray"), "{sentence}");
  assert!(sentence.contains("other::Missing"), "{sentence}");
}

/// The per-upstream words survive the trip: what a `Upstream` is built with is what its row states.
#[test]
fn a_sources_words_are_what_it_was_built_with() {
  const CHANGES: Upstream = Upstream::of::<Head>("Head")
    .listening(Listen::Changes(crate::Feeder::External))
    .acking(AckMode::Chained);

  assert_eq!(CHANGES.named(), "Head");
  assert_eq!(CHANGES.listen(), Listen::Changes(crate::Feeder::External));
  assert_eq!(CHANGES.ack(), AckMode::Chained);
  assert_eq!(CHANGES.channel(), None);
  assert_eq!(CHANGES.upstream(), core::any::TypeId::of::<Head>());

  const POLLED: Upstream =
    Upstream::of::<Head>("Head").listening(Listen::Poll(Duration::from_secs(60)));
  assert_eq!(POLLED.listen(), Listen::Poll(Duration::from_secs(60)));
}

/// A resource nobody in this module builds — its only job is to be demanded and mounted.
struct Model;

impl crate::AsyncResource for Model {
  type Error = core::convert::Infallible;
  type Options = ();

  async fn build(_ctx: &Resources, (): ()) -> Result<Self, Self::Error> {
    Ok(Self)
  }
}

impl crate::DeclaredResource for Model {}

/// A node whose construction reaches for it.
struct Reaching;

impl Operator for Reaching {
  type Error = Infallible;
  type In = String;
  type Out = String;

  fn accept(
    &mut self,
    _ctx: &Context,
    _delivery: Delivery<Self::In>,
    _emitter: &mut Emitter<Self::Out>,
  ) -> Result<(), Self::Error> {
    Ok(())
  }
}

impl Declared for Reaching {
  const DEMANDS: &'static [fn() -> crate::ResourceDemand] = &[crate::ResourceDemand::of::<Model>];
  const EFFECT: Effect = Effect::Lands;
  const HOLDS_LANE: bool = true;

  type Channels = crate::Unchanneled;
  type Options = ();
  type Mode = crate::Block;
  type Pair = crate::Buffered;
  type Wires<O> = crate::Downstream<O>;
  type Attribution<O> = ();
}

/// **THE TYPE→MOUNT JOIN** — S5a's L-7, closed.
///
/// A demand is minted inside a MEMBER's own declaration, which cannot see the root's field list, so
/// the demand side has always been keyed by the compiler's path for the type while the declaration
/// side has a mount. Both keys meet on a plan carrying the root's catalog, and this is the reading
/// that spends the meeting.
#[test]
fn a_demand_minted_by_type_is_read_back_under_the_roots_mount() {
  let mut blueprint = Blueprint::new();
  blueprint.node::<Reaching>("reaching");
  let wired = blueprint
    .into_plan()
    .expect("one declaration")
    .with_enablement(crate::Enablement::new().launching("reaching"))
    .with_resources(
      crate::ResourceCatalog::new().with::<Model>("model", crate::ResourceSource::Section),
    )
    .validate()
    .expect("the arrangement");

  let joined: Vec<(&str, &str)> = wired
    .demanded_at()
    .map(|(mount, resource)| (mount, resource.as_str()))
    .collect();
  assert_eq!(joined.len(), 1);
  assert_eq!(
    joined[0].0, "model",
    "the demand reaches the mount the ROOT wrote it under"
  );
  assert!(
    joined[0].1.ends_with("Model"),
    "and the type's own path stays for diagnostics: {}",
    joined[0].1
  );
}

/// A demand for a resource the catalog does not carry falls back to the type's own name, which is
/// the only name it has — and that is the case the undeclared-resource refusal is about.
#[test]
fn a_demand_nothing_declared_keeps_the_types_own_name() {
  let mut blueprint = Blueprint::new();
  blueprint.node::<Reaching>("reaching");
  let plan = blueprint
    .into_plan()
    .expect("one declaration")
    .with_enablement(crate::Enablement::new().launching("reaching"));
  let refusal = plan
    .validate()
    .expect_err("a demand nothing declared is refused by name");
  let sentence = refusal.to_string();
  assert!(sentence.contains("Model"), "{sentence}");
}