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 CHANNEL WORD: what one data edge is opened as, and the form a deployment writes it in.
//!
//! The vocabulary is CLOSED and framework-owned — an edge is bounded at some depth or it is not
//! bounded at all — so it is an enum rather than a seam. There is no third kind: a spin discipline
//! is a consumer's way of waiting and not a property of the queue, and the word for it was deleted
//! rather than reseated.
//!
//! # The three layers this value can come from
//!
//! An author DECLARES a default (`upstream(node = "…", channel = bounded(512))`), a deployment
//! OVERRIDES it (`[node.channels]`), and the framework SHIPS one under both
//! ([`Wiring::SHIPPED`](crate::Wiring::SHIPPED)). Resolution runs at the launch validate walk and
//! goes config over declared over shipped, uniformly for the KIND as well as the depth — see
//! [`Channels`](crate::Channels), which is where a deployment's half arrives.

/// WHAT an edge is opened as: bounded at a depth, or unbounded.
///
/// # `Bounded` counts DELIVERIES, not items
///
/// A delivery may be a batch, so the memory an edge can hold is `capacity × batch` — the same
/// counting [`channel`](super::channel) has always done. Zero is legal and means a rendezvous: the
/// sender waits until the consumer takes it.
///
/// # `Unbounded` trades backpressure for memory, and says so
///
/// A send never waits, so a producer is never slowed by its consumer — and nothing bounds what the
/// queue holds but the machine. It is a per-upstream opt-in for the two shapes that need it: a burst
/// intake that must not stall its producer, and a feedback edge where waiting could deadlock. Data
/// is never dropped either way; what changes is who pays for a slow consumer.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ChannelOptions {
  /// A queue of at most `capacity` deliveries — a full one is backpressure at the sender.
  Bounded(usize),
  /// A queue nothing bounds — a send never waits, and memory is the only limit.
  Unbounded,
}

impl ChannelOptions {
  /// The depth these options bound an edge at, or `None` where they bound it at nothing.
  #[inline]
  #[must_use]
  pub const fn capacity(&self) -> Option<usize> {
    match self {
      Self::Bounded(capacity) => Some(*capacity),
      Self::Unbounded => None,
    }
  }

  /// Whether an edge opened under these options can ever make a sender wait.
  #[inline]
  #[must_use]
  pub const fn is_bounded(&self) -> bool {
    matches!(self, Self::Bounded(_))
  }

  /// The other half of [`is_bounded`](Self::is_bounded) — the kind the contradiction row reads.
  #[inline]
  #[must_use]
  pub const fn is_unbounded(&self) -> bool {
    matches!(self, Self::Unbounded)
  }
}

impl core::fmt::Display for ChannelOptions {
  /// The word an author WROTE, so a refusal about a resolved edge reads back as the declaration or
  /// the document it came from.
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    match self {
      Self::Bounded(capacity) => write!(f, "bounded({capacity})"),
      Self::Unbounded => f.write_str("unbounded"),
    }
  }
}

/// What a document writes: an INTEGER is a bounded capacity, and the literal string `"unbounded"` is
/// the other kind.
///
/// Two forms rather than a tagged object because the value is one word: `ocr = 512` and `ocr =
/// "unbounded"` are what a reader of a TOML or JSON file expects to be able to write, and a
/// `{ "kind": "bounded", "capacity": 512 }` shape would be ceremony around a scalar. Everything else
/// is refused where the reader is looking at the file, naming both forms.
#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for ChannelOptions {
  fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
  where
    D: serde::Deserializer<'de>,
  {
    deserializer.deserialize_any(SpecVisitor)
  }
}

/// The reader for the two forms — see [`ChannelOptions`]'s `Deserialize`.
#[cfg(feature = "serde")]
struct SpecVisitor;

#[cfg(feature = "serde")]
impl serde::de::Visitor<'_> for SpecVisitor {
  type Value = ChannelOptions;

  fn expecting(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.write_str("a capacity as a non-negative integer, or the string \"unbounded\"")
  }

  fn visit_u64<E>(self, capacity: u64) -> Result<Self::Value, E>
  where
    E: serde::de::Error,
  {
    usize::try_from(capacity)
      .map(ChannelOptions::Bounded)
      .map_err(|_| {
        E::custom(format!(
          "a capacity of {capacity} does not fit this machine"
        ))
      })
  }

  fn visit_i64<E>(self, capacity: i64) -> Result<Self::Value, E>
  where
    E: serde::de::Error,
  {
    // Written rather than left to serde's own signed-to-unsigned path, because the message is the
    // point: a negative depth is a value the grammar has, not a type error, and the reader is
    // looking at the file where the two forms are spellable.
    u64::try_from(capacity).map_or_else(
      |_| {
        Err(E::custom(format!(
          "a channel is `{capacity}` deep in no sense — write a non-negative capacity, or \
           \"unbounded\""
        )))
      },
      |capacity| self.visit_u64(capacity),
    )
  }

  fn visit_str<E>(self, word: &str) -> Result<Self::Value, E>
  where
    E: serde::de::Error,
  {
    if word == "unbounded" {
      return Ok(ChannelOptions::Unbounded);
    }
    Err(E::custom(format!(
      "`{word}` is not a channel — an integer is a bounded capacity and \"unbounded\" is the only \
       word"
    )))
  }
}

#[cfg(test)]
mod tests;