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
//! [`Refused`] — WHICH LEG of a `fanout` write refused, when one of them did.

use core::fmt;

/// Which leg of a two-legged fan refused, carrying that leg's own error.
///
/// # Why a fan needs this at all
///
/// A `fanout` field's engines are DIFFERENT ENGINES, so they are different Rust types with different
/// `Error` associated types — and neither is convertible into the other, because
/// [`FulltextEngine::Error`](super::FulltextEngine::Error) and
/// [`VectorEngine::Error`](super::VectorEngine::Error) carry no bound at all. That is deliberate and
/// this crate will not narrow it: *each is an associated type with no bound, and each has a second
/// implementation already in view that would break under the obvious narrowing.* A fan therefore
/// cannot flatten its legs' errors into one type, and must not erase them into a box — boxing is
/// what a bound would have bought, and the bound is the thing being refused.
///
/// So the fan's error is the SUM, and the caller matches on it. Nothing is lost: each leg's error
/// arrives as itself, at its own type, and the variant says which engine produced it.
///
/// # N legs, spelled by nesting
///
/// Two variants serve any arity, right-nested: a three-engine fan reports
/// `Refused<A, Refused<B, C>>`, and the emission writes exactly that. A wider enum per arity would
/// be a family of types that must agree and are free to stop agreeing, which is this crate's reason
/// for every other collapse.
///
/// # The fan is SEQUENTIAL and stops at the first refusal
///
/// A leg that already committed is not rolled back, and there is nothing here that could: the
/// engines are independent stores with no shared transaction, and inventing one would be this crate
/// deciding a durability question that belongs to the deployment. What the caller is owed is
/// knowing WHICH leg refused — so the legs before it committed and the legs after it were not
/// attempted — and that is exactly what this type says.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Refused<A, B> {
  /// The FIRST leg refused — the engine the field declared first.
  First(A),
  /// A LATER leg refused. For a two-engine fan that is the second engine; for a wider one it is
  /// another [`Refused`], naming which.
  Second(B),
}

impl<A, B> Refused<A, B> {
  /// The leg's error, where both legs report the same type.
  ///
  /// The convenience a fan over ONE engine type wants — two slots of one engine is a legal and
  /// ordinary shape, since a field may name an engine word the deployment binds twice — and it
  /// exists only for that case, which is why it is spelled `A == B` rather than through a
  /// conversion.
  #[must_use]
  pub fn into_inner(self) -> A
  where
    B: Into<A>,
  {
    match self {
      Self::First(error) => error,
      Self::Second(error) => error.into(),
    }
  }
}

impl<A: fmt::Display, B: fmt::Display> fmt::Display for Refused<A, B> {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    match self {
      Self::First(error) => write!(f, "the fan's first engine refused: {error}"),
      Self::Second(error) => write!(f, "{error}"),
    }
  }
}

/// CONDITIONAL, so the sum is an error exactly where its legs are — and the seam stays unbounded.
impl<A, B> core::error::Error for Refused<A, B>
where
  A: core::error::Error + 'static,
  B: core::error::Error + 'static,
{
  fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
    match self {
      Self::First(error) => Some(error),
      Self::Second(error) => Some(error),
    }
  }
}

#[cfg(test)]
mod tests;