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
//! WHICH NODES A DEPLOYMENT LAUNCHES — and why an absence is the whole of an answer.
//!
//! # Presence is enablement
//!
//! An application DECLARES a catalog and a deployment LAUNCHES a subset of it. So the statement a
//! deployment makes is what it NAMES, and a node it does not name is a node that never starts: the
//! sleeping catalog costs no boilerplate, and a node added in code runs nowhere until somebody says
//! it should. That is the design and not a hazard — a catalog of thirty nodes is a menu, and a
//! deployment orders from it.
//!
//! The carrier of the naming is a SECTION — [`NodeSection`], one per node, held `Option`ally by the
//! emitted `<Root>Options` spine — and this type is what that spine's own `enablement()` folds
//! into: one [`mounted`](Enablement::mounted) call per declared mount, carrying whatever the
//! document had there, which for most of a catalog is nothing.
//!
//! # ONE shape of "not launched", because there is one axis
//!
//! There is a single darkness — nothing named it — and a single fix: write the node a section. The
//! soft switch that once made a second one is gone, configuration files being immutable artifacts
//! that a deployment swaps rather than toggles, so a refusal about a dark upstream has one sentence
//! to say and says it.

use std::collections::HashSet;

use smol_bytes::Utf8Bytes;

use super::NodeSection;

#[cfg(test)]
mod tests;

/// Which nodes a deployment launches, as its options named them.
///
/// The names in it are the arrangement's own node names, which are the MOUNT names the declaration
/// wrote — one word for both, so a section's key and a node's name cannot drift apart. A name
/// naming nothing is a START-UP refusal rather than a silent no-op: options that misspell a node
/// have said something false about the deployment, and finding that out at start-up is the whole
/// value of checking it.
///
/// The typed spine cannot produce that misspelling — its keys are FIELDS, and `deny_unknown_fields`
/// refuses an unknown one at deserialization, where the reader is looking at the document. What can
/// is the door beside it: a deployment assembled in code, which names its nodes with strings
/// because nothing else can carry a name a program computes.
///
/// # Examples
///
/// ```
/// use ingraph::Enablement;
///
/// // A deployment of a three-node catalog that runs one of them.
/// let enablement = Enablement::new().launching("decode");
///
/// assert!(enablement.is_enabled("decode"));
/// // Never named at all, and therefore never launched.
/// assert!(!enablement.is_enabled("captions"));
/// assert!(!enablement.is_enabled("scenes"));
/// ```
#[derive(Debug, Clone, Default)]
pub struct Enablement {
  sections: HashSet<Utf8Bytes>,
}

impl Enablement {
  /// The SLEEPING CATALOG: nothing named, and therefore nothing launched.
  #[inline]
  #[must_use]
  pub fn new() -> Self {
    Self {
      sections: HashSet::new(),
    }
  }

  /// WHAT THE SPINE HOLDS at the mount `node`: `Some` being a section this deployment wrote, `None`
  /// being a node it did not name.
  ///
  /// The BRIDGE from the emitted `<Root>Options` — whose every field is exactly this `Option` — and
  /// the reason it takes the option rather than its contents is that absence is the WHOLE answer:
  /// spelling the bridge as this one call per mount leaves nowhere for a `None` to be read as
  /// anything but a node that does not launch.
  #[inline]
  #[must_use]
  pub fn mounted<O, C, P>(
    self,
    node: impl Into<Utf8Bytes>,
    section: Option<&NodeSection<O, C, P>>,
  ) -> Self {
    match section {
      Some(_) => self.launching(node),
      None => self,
    }
  }

  /// `node` has a section, and therefore runs.
  ///
  /// The general door as well as the readable one: a section carries no fact outside its options
  /// beyond being there, so naming a node is the whole of what a deployment assembled in code — or
  /// merged from a source this crate never sees — has to say.
  #[inline]
  #[must_use]
  pub fn launching(mut self, node: impl Into<Utf8Bytes>) -> Self {
    self.sections.insert(node.into());
    self
  }

  /// Whether `node` runs. A node nothing named does not.
  #[inline]
  #[must_use]
  pub fn is_enabled(&self, node: &str) -> bool {
    self.sections.contains(node)
  }

  /// Every name these options mention — what the unknown-name check reads.
  #[inline]
  pub fn names(&self) -> impl Iterator<Item = &str> {
    self.sections.iter().map(Utf8Bytes::as_str)
  }
}