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 CONSTRUCTION CONTRACT: what a node's author writes so a launch can build one.
//!
//! A node is a type an application owns, holding whatever that application's compute needs — a
//! decoder's thread budget, a model handle, an open device. The launch has to produce one, and the
//! only party that knows how is the author. So construction is a CAPABILITY the type implements,
//! exactly as [`AsyncResource`](crate::AsyncResource) is for the things several nodes share.
//!
//! # Two doors, one body
//!
//! [`with_options`](AsyncConstructor::with_options) is the source of truth and the only one an author
//! writes. [`new`](AsyncConstructor::new) exists where the options have a [`Default`] and DELEGATES to
//! it — the options pattern's own law, which is what keeps a hand-wired test and a launch walk from
//! taking two different paths into the same type. The walk itself calls `with_options` and nothing
//! else; `new` is the human's door.
//!
//! # ASYNC, and the exclusive-model default is why
//!
//! A node that owns its model loads the weights inside its own construction — that is the whole
//! point of the exclusive default — so building one is I/O and compute and the contract is a future.
//! The same sentence [`AsyncResource::build`](crate::AsyncResource::build) is written for, one tier down.
//!
//! Unlike that one, the future is NOT `Send`. A node's engine follows the node's own mobility: the
//! default engine is a pinned thread, which is safe for every node and is where a `!Send` citizen
//! lives, so a construction that cannot cross threads is a supported shape rather than a refusal.
//! The async engine is the opt-in that asks for `Send`, and it asks at its own wiring.

use core::future::Future;

use super::Resources;

#[cfg(test)]
mod tests;

/// A type a LAUNCH can build — the capability a node's author implements by hand.
///
/// # `type Options` is the AUTHOR's, and a zero-knob node writes `()`
///
/// Bound by nothing here. What options must satisfy is the DEPLOYMENT's question — a node section
/// read out of a file has to deserialize, and that is asked where the sections are declared rather
/// than where one is spent. A node with nothing to configure writes `type Options = ();` and gets
/// [`new`](Self::new) for free.
///
/// # `type Error` is the AUTHOR's too
///
/// Bound-free, per [`Operator::Error`](crate::Operator)'s discipline: a construction refuses in its
/// own currency, and the launch layer is what wraps a typed refusal into a start-up one naming the
/// node.
///
/// # Examples
///
/// ```
/// use ingraph::{AsyncConstructor, Resources};
///
/// /// A node with knobs, and the options that carry them.
/// struct Decode {
///   threads: usize,
/// }
///
/// struct DecodeOptions {
///   threads: usize,
/// }
///
/// impl Default for DecodeOptions {
///   fn default() -> Self {
///     Self { threads: 4 }
///   }
/// }
///
/// impl AsyncConstructor for Decode {
///   type Options = DecodeOptions;
///   type Error = core::convert::Infallible;
///
///   async fn with_options(_ctx: &Resources, options: DecodeOptions) -> Result<Self, Self::Error> {
///     Ok(Self {
///       threads: options.threads,
///     })
///   }
/// }
///
/// # tokio::runtime::Builder::new_current_thread().build().unwrap().block_on(async {
/// let ctx = Resources::new();
///
/// // The launch's door: a present section supplies the options.
/// let tuned = Decode::with_options(&ctx, DecodeOptions { threads: 8 })
///   .await
///   .unwrap();
/// assert_eq!(tuned.threads, 8);
///
/// // The human's door, which exists because the options have a `Default` — and which runs the
/// // very same body.
/// let plain = Decode::new(&ctx).await.unwrap();
/// assert_eq!(plain.threads, 4);
/// # });
/// ```
#[diagnostic::on_unimplemented(
  message = "`{Self}` cannot be built by a launch — a node states HOW it is constructed, and this \
             type states nothing",
  label = "not constructible",
  note = "write `impl AsyncConstructor for {Self}`; a node with nothing to configure takes `type \
          Options = ();` and gets `new` for free"
)]
pub trait AsyncConstructor: Sized {
  /// What building one takes — the author's own type, `()` where there is nothing to configure.
  type Options;

  /// What a refused construction reports.
  type Error;

  /// Build one from `options`, reaching whatever it shares through `ctx`.
  ///
  /// THE one source of truth: [`new`](Self::new) delegates here, and the launch walk calls this and
  /// nothing else.
  ///
  /// # Errors
  ///
  /// Whatever this node's own construction refuses with. The launch wraps it into a start-up
  /// refusal naming the node.
  fn with_options(
    ctx: &Resources,
    options: Self::Options,
  ) -> impl Future<Output = Result<Self, Self::Error>>;

  /// Build one at the options' own defaults — the HUMAN's door, and never a second body.
  ///
  /// It exists only where [`Options`](Self::Options) has a [`Default`], and its whole content is
  /// the delegation: a hand-wired test and a launch walk construct the same type by running the
  /// same code, which is the one-source-of-truth law the options pattern is written around.
  ///
  /// # Errors
  ///
  /// [`with_options`](Self::with_options)'s, unchanged.
  #[inline]
  fn new(ctx: &Resources) -> impl Future<Output = Result<Self, Self::Error>>
  where
    Self::Options: Default,
  {
    Self::with_options(ctx, Self::Options::default())
  }
}