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 WIRE-ERASED DOOR onto one family's table — [`DynRegistry`], and the blanket impl that makes
//! every [`Registry<Root>`](super::Registry) answer through it once `Root` can name itself on the
//! wire.
//!
//! # Why this exists BESIDE the typed door, rather than instead of it
//!
//! [`Registries::open`](super::Registries::open) and
//! [`Registries::counting`](super::Registries::counting) ask [`RootKey`](super::RootKey) alone —
//! [`Clone`], [`Eq`], [`Hash`], [`Send`], [`Sync`], `'static` — which is
//! [`Drives`](crate::Drives)'s own bound and is paid on the hot counting path by every emitted
//! projection. A GraphQL `family: String` argument needs two things that bound does not promise: a
//! `key: ID!` a client sent has to PARSE into `Root`, and a key this table holds has to RENDER back
//! out as text. Asking every family in every deployment for [`Display`] and [`FromStr`] to serve the
//! rare caller that reaches in by name would tax the common one that never does — so the wider bound
//! is asked HERE, where it is spent, and nowhere upstream of it.
//!
//! # Total on parsing, WHERE the read side is total on the key
//!
//! [`Registry::state`](super::Registry::state) answers [`Idle`](super::RootState::Idle) for a key it
//! has never heard of, and a string that does not even parse as `Root` is, by construction, a key
//! nothing can be true of — so [`state`](DynRegistry::state) answers `Idle` for it too rather than
//! refusing. The command doors — [`retire`](DynRegistry::retire),
//! [`restore`](DynRegistry::restore), [`reanalyze`](DynRegistry::reanalyze) — take the other reading,
//! on purpose: a person asking to retire a key that cannot exist is a mistake worth surfacing, not a
//! no-op worth hiding, so they answer [`KeyDoesNotParse`] instead.

use core::{fmt::Display, str::FromStr};

use smol_bytes::Utf8Bytes;

use super::{
  Registry, RegistryCounts, RegistryOptions, RegistryOverride, RootKey, RootState,
  state::{RetireOrigin, Stamp},
};

/// A `key` offered to a wire door that does not parse as this family's own root type — the honest
/// refusal [`DynRegistry`]'s command doors give a caller instead of silently doing nothing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct KeyDoesNotParse;

/// THE OBJECT-SAFE FACE one family's table answers through when the caller has a NAME rather than a
/// TYPE — see the module note for why it is a second door rather than a widened first one.
///
/// Every method here is the typed door's own, crossed through a string: `key: &str` in place of
/// `key: &Root`, and a rendered `Utf8Bytes` in place of a returned `Root`. Nothing here adds a new
/// FACT about a family — it only asks the same questions [`Registry`] already answers, in the one
/// form a `TypeId`-free caller can supply.
pub(crate) trait DynRegistry: Send + Sync {
  /// [`Registry::state`], total on `key` failing to parse exactly as it is total on a key never
  /// heard of — see the module note.
  fn state(&self, key: &str) -> RootState;

  /// [`Registry::counts`].
  fn counts(&self) -> RegistryCounts;

  /// [`Registry::options`] — this family's own resolved knobs, as of this read.
  fn options(&self) -> RegistryOptions;

  /// [`Registry::apply_knobs`] — turn this family's live dial.
  fn apply_knobs(&self, over: &RegistryOverride);

  /// [`Registry::snapshot`], with each key rendered to text.
  fn recent(&self, limit: usize) -> Vec<(Utf8Bytes, RootState)>;

  /// [`Registry::retire`], answering the state `key` landed in — or [`KeyDoesNotParse`] where `key`
  /// is not this family's own root type in any spelling.
  fn retire(&self, key: &str, origin: RetireOrigin) -> Result<RootState, KeyDoesNotParse>;

  /// [`Registry::restore`], answering the state `key` landed in.
  fn restore(&self, key: &str) -> Result<RootState, KeyDoesNotParse>;

  /// A PERSON'S OWN INTAKE: [`Registry::intake`] under a name an operator reads rather than a debounce
  /// driver's own. See [`crate::graphql`]'s own note on the mutation this answers for the mapping.
  fn reanalyze(&self, key: &str) -> Result<RootState, KeyDoesNotParse>;
}

impl<Root> DynRegistry for Registry<Root>
where
  Root: RootKey + Display + FromStr,
{
  fn state(&self, key: &str) -> RootState {
    key
      .parse::<Root>()
      .map_or(RootState::Idle, |root| Registry::state(self, &root))
  }

  fn counts(&self) -> RegistryCounts {
    Registry::counts(self)
  }

  fn options(&self) -> RegistryOptions {
    Registry::options(self)
  }

  fn apply_knobs(&self, over: &RegistryOverride) {
    Registry::apply_knobs(self, over);
  }

  fn recent(&self, limit: usize) -> Vec<(Utf8Bytes, RootState)> {
    Registry::snapshot(self, limit)
      .into_iter()
      .map(|(root, state)| (Utf8Bytes::from(root.to_string()), state))
      .collect()
  }

  fn retire(&self, key: &str, origin: RetireOrigin) -> Result<RootState, KeyDoesNotParse> {
    let root = key.parse::<Root>().map_err(|_| KeyDoesNotParse)?;
    let _advance = Registry::retire(self, &root, origin, Stamp::now());
    Ok(Registry::state(self, &root))
  }

  fn restore(&self, key: &str) -> Result<RootState, KeyDoesNotParse> {
    let root = key.parse::<Root>().map_err(|_| KeyDoesNotParse)?;
    let _advance = Registry::restore(self, &root, Stamp::now());
    Ok(Registry::state(self, &root))
  }

  fn reanalyze(&self, key: &str) -> Result<RootState, KeyDoesNotParse> {
    let root = key.parse::<Root>().map_err(|_| KeyDoesNotParse)?;
    let _advance = Registry::intake(self, &root, Stamp::now());
    Ok(Registry::state(self, &root))
  }
}

#[cfg(test)]
mod tests;