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 FEEDER ROW: a default change feed nobody fills, refused with its three roads.
//!
//! A change feed reports what arrived and never who put it there, so *somebody lands into that
//! store* is the one fact the runtime cannot discover. A default `changes(<db>)` claims it about
//! THIS graph; `external` declares the hand is elsewhere and the check stands down.
//!
//! What each test is arranged to catch is a different way of getting the rule wrong: refusing the
//! reindex posture, refusing a declared cross-process feed, refusing a store that IS fed, and
//! letting the sentence rot.
use crate::Context;

use crate::{
  AckMode, ChannelGraph, Delivery, DriverKind, EdgeId, Effect, Emitter, Enablement, FanoutKind,
  Feeder, GraphBuilder, LaunchError, Listen, NodeId, NodeWiring, Operator, Plan, Refusal,
  UpstreamWiring,
};

/// Two nodes with nothing worth reading in them — this file is about the WALK, and a node is a name
/// and an effect to it.
macro_rules! node {
  ($name:ident) => {
    struct $name;

    impl Operator for $name {
      type Error = core::convert::Infallible;
      type In = u8;
      type Out = u8;

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

    /// The facts a hand-wired node states — the mount predicate is
    /// `O: Declared + Driven<O::Mode>`, so a node that is not emitted says what it is too, in the
    /// mode a bare declaration has.
    impl crate::Declared for $name {
      const EFFECT: crate::Effect = crate::Effect::Pure;

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

node!(Scenes);
node!(Captions);

/// `scenes → captions`: the store is `scenes`, and `captions` watches its feed.
fn watching() -> ChannelGraph {
  let mut builder = GraphBuilder::new();
  let scenes = builder.source::<Scenes>("scenes", DriverKind::Thread);
  let captions = builder.node::<Captions>("captions", DriverKind::Async);
  builder.edge(&scenes, &captions, FanoutKind::Broadcast);
  builder.validate().expect("a pair validates")
}

/// The deployment that launches both, with `captions` landing so the leaf rule has nothing to say.
fn plan(graph: ChannelGraph, watched: Effect, feeder: Feeder) -> Plan {
  let enablement = graph
    .nodes()
    .iter()
    .fold(Enablement::new(), |enablement, node| {
      enablement.launching(node.name())
    });
  Plan::new(graph)
    .with_enablement(enablement)
    .wiring(NodeId::new(0), NodeWiring::new(watched))
    .wiring(NodeId::new(1), NodeWiring::default().landing())
    .upstream(
      EdgeId::new(0),
      UpstreamWiring::new(Listen::Changes(feeder), AckMode::Local),
    )
}

/// Every refusal a plan produced, as the report renders them.
fn refusals(plan: Plan) -> Vec<String> {
  match plan.validate() {
    Err(LaunchError::Refused(rows)) => rows.iter().map(ToString::to_string).collect(),
    Err(other) => panic!("the walk refused for another reason: {other}"),
    Ok(_) => Vec::new(),
  }
}

/// THE ROW, and the SENTENCE: a default feed over a store nothing in the graph lands into is refused
/// with all three roads named.
#[test]
fn a_default_feed_with_no_lander_is_refused_with_its_three_roads() {
  let rows = refusals(plan(watching(), Effect::Pure, Feeder::InGraph));
  let row = rows
    .iter()
    .find(|row| row.contains("listens to the changes of"))
    .unwrap_or_else(|| panic!("the feeder row is missing: {rows:?}"));
  assert!(row.contains("`captions`"), "{row}");
  assert!(row.contains("`scenes`"), "{row}");
  // ROAD ONE: the store is filled from another process.
  assert!(row.contains("say `external`"), "{row}");
  // ROAD TWO: the in-graph geometry — subscribe to the node itself.
  assert!(row.contains("subscribe to `scenes` directly"), "{row}");
  // ROAD THREE: the lander is simply missing.
  assert!(row.contains("add the node that lands into it"), "{row}");
}

/// The row is COLLECTED, not thrown — the walk keeps going, so an operator fixes everything in one
/// pass. `scenes` is pure and publishes, so the pure-leaf rule has nothing to say about it and the
/// feeder row is the one that fires.
#[test]
fn the_row_joins_the_collect_list_rather_than_stopping_the_walk() {
  let rows = refusals(plan(watching(), Effect::Pure, Feeder::InGraph));
  assert!(
    matches!(
      plan(watching(), Effect::Pure, Feeder::InGraph).validate(),
      Err(LaunchError::Refused(_))
    ),
    "the walk collects"
  );
  assert_eq!(rows.len(), 1, "{rows:?}");
}

/// `external` DECLARES the cross-process dependence, and the check stands down — which is what makes
/// the two-process shape a first-class citizen rather than an escape.
#[test]
fn an_external_feed_needs_no_lander() {
  assert_eq!(
    refusals(plan(watching(), Effect::Pure, Feeder::External)),
    Vec::<String>::new()
  );
}

/// A store that IS fed passes with no word at all, which is the default's whole point.
#[test]
fn a_watched_store_with_a_lander_passes() {
  assert_eq!(
    refusals(plan(watching(), Effect::Lands, Feeder::InGraph)),
    Vec::<String>::new()
  );
}

/// The row is about the STORE, not about the launch: a changes listener over an UNLAUNCHED lander is
/// the reindex posture and stays legal, the store still holding everything that node wrote.
#[test]
fn an_unlaunched_lander_is_the_reindex_posture_and_not_this_row() {
  let graph = watching();
  let plan = Plan::new(graph)
    .with_enablement(Enablement::new().launching("captions"))
    .wiring(NodeId::new(0), NodeWiring::default().landing())
    .wiring(NodeId::new(1), NodeWiring::default().landing())
    .upstream(
      EdgeId::new(0),
      UpstreamWiring::new(Listen::Changes(Feeder::InGraph), AckMode::Local),
    );
  assert_eq!(refusals(plan), Vec::<String>::new());
}

/// The row names an ARM, so it can be matched on rather than read.
#[test]
fn the_row_is_its_own_variant() {
  let Err(LaunchError::Refused(rows)) = plan(watching(), Effect::Pure, Feeder::InGraph).validate()
  else {
    panic!("the walk refuses");
  };
  let [Refusal::FeederAbsent(absent)] = rows.as_slice() else {
    panic!("one row, and it is the feeder's: {rows:?}");
  };
  assert_eq!(absent.consumer_name(), "captions");
  assert_eq!(absent.watched_name(), "scenes");
  assert_eq!(absent.edge(), EdgeId::new(0));
}