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
//! Arrangement validation errors.

use smol_bytes::Utf8Bytes;

use super::{EdgeId, NodeId};

/// The payload of [`ArrangeError::EdgeEndpointOutOfRange`]: the edge carrying the
/// bad endpoint, that endpoint, and the declared node count.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EdgeEndpointError {
  edge: EdgeId,
  node: NodeId,
  node_count: usize,
}

impl EdgeEndpointError {
  /// Record that `edge`'s `node` endpoint indexes past a graph of `node_count`
  /// nodes.
  #[inline]
  pub(crate) const fn new(edge: EdgeId, node: NodeId, node_count: usize) -> Self {
    Self {
      edge,
      node,
      node_count,
    }
  }

  /// The edge carrying the bad endpoint.
  #[inline]
  pub const fn edge(&self) -> EdgeId {
    self.edge
  }

  /// The endpoint that indexes past the declared node set.
  #[inline]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// How many nodes the builder actually declared.
  #[inline]
  pub const fn node_count(&self) -> usize {
    self.node_count
  }
}

/// The payload of [`ArrangeError::DirectFanout`]: the offending producer, its name,
/// and its out-edge count.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DirectFanoutError {
  node: NodeId,
  name: Utf8Bytes,
  out_count: usize,
}

impl DirectFanoutError {
  /// Record that `node` (`name`) has `out_count` out-edges, one of them a Direct
  /// edge.
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes, out_count: usize) -> Self {
    Self {
      node,
      name,
      out_count,
    }
  }

  /// The offending producer node.
  #[inline]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// That node's declared name.
  #[inline]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }

  /// How many out-edges it has (> 1).
  #[inline]
  pub const fn out_count(&self) -> usize {
    self.out_count
  }
}

/// The payload of [`ArrangeError::Cycle`]: a node on the detected cycle and its
/// name.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct CycleError {
  node: NodeId,
  name: Utf8Bytes,
}

impl CycleError {
  /// Record that `node` (`name`) lies on a detected cycle.
  #[inline]
  pub(crate) const fn new(node: NodeId, name: Utf8Bytes) -> Self {
    Self { node, name }
  }

  /// A node on the detected cycle.
  #[inline]
  pub const fn node(&self) -> NodeId {
    self.node
  }

  /// That node's declared name.
  #[inline]
  pub fn name(&self) -> &str {
    self.name.as_str()
  }
}

/// Why a [`GraphBuilder`](super::GraphBuilder) failed [`validate`](super::GraphBuilder::validate).
/// Variants are declared in `validate`'s check order.
///
/// The rendering is derived per variant rather than written as one `match`, which is what keeps
/// each sentence beside the variant it describes — the payloads are read through their accessors
/// and nothing is computed on the way out. The `Error` impl is written, because a derived
/// `Display` supplies only half of one and neither payload here is a `source`: an endpoint's
/// index, a node's name and an out-edge count are facts about the graph, not errors of their own.
#[derive(
  Debug,
  Clone,
  PartialEq,
  Eq,
  derive_more::Display,
  derive_more::IsVariant,
  derive_more::Unwrap,
  derive_more::TryUnwrap,
)]
#[unwrap(ref, ref_mut)]
#[try_unwrap(ref, ref_mut)]
#[non_exhaustive]
pub enum ArrangeError {
  /// An edge endpoint names a node that does not exist. A
  /// [`NodeHandle`](super::NodeHandle) carries no builder identity, so a handle
  /// minted by a *different* builder can smuggle an out-of-range [`NodeId`] into
  /// [`edge`](super::GraphBuilder::edge); `validate` rejects it rather than panic
  /// on the out-of-bounds index. This variant has no node name — the endpoint is
  /// out of range, so there is no declaration to name.
  #[display(
    "{} endpoint {} is out of range; the graph declares {} node(s)",
    _0.edge(), _0.node(), _0.node_count()
  )]
  EdgeEndpointOutOfRange(EdgeEndpointError),
  /// A node has a `Direct` (exclusive-move) out-edge alongside others. A `Direct`
  /// edge must be a node's *sole* out-edge; use `Broadcast`/`Group` to fan out.
  #[display(
    "{} (`{}`) has {} out-edges including a Direct edge; Direct must be exclusive",
    _0.node(), _0.name(), _0.out_count()
  )]
  DirectFanout(DirectFanoutError),
  /// The declared edges contain a cycle running through this node.
  #[display("graph cycle through {} (`{}`)", _0.node(), _0.name())]
  Cycle(CycleError),
}

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

#[cfg(test)]
mod tests;