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
//! ONE NODE'S SHELF in a deployment's options — the carrier the emitted spine's every field holds.
//!
//! # PRESENCE IS ENABLEMENT, and it is the ONLY enablement axis
//!
//! An application DECLARES a catalog; a deployment LAUNCHES a subset. So the absence of a node's
//! section is the statement that the node is not started — which is why the emitted spine holds
//! `Option<NodeSection<…>>` per node and not a bare section, and why a node added in code runs
//! nowhere until a deployment names it. The sleeping catalog costs no boilerplate.
//!
//! There is NO soft switch beside that hard one, and the doctrine is why: a configuration file is an
//! IMMUTABLE ARTIFACT. Behaviour changes by pointing at a different file — both of them under
//! version control, the file name carrying the intent — never by toggling a live one. Everything a
//! `enabled = false` bought is bought more cleanly per deployment: git keeps the tuning, the
//! enabling variant validates when it is used, and no reader has to ask which of two axes turned a
//! node off. A stray `enabled` key in a document is now an ordinary unknown field, refused by name
//! where the reader is looking at the file.
//!
//! # A SHELF, so what stands beside `options` can grow
//!
//! `options` is one entry of a rack rather than the whole of it. The framework's own per-node
//! blocks — `channels` today, an explicit policy selection later — mount BESIDE it under their own
//! names, each typed and each refusing its own unknown keys. That is what keeps a deployment's file
//! one schema: nothing is stringly keyed, and nothing needs a second document to say what a node's
//! edges do.
//!
//! Each block is ONE TYPE PARAMETER, defaulted — `NodeSection<O, C = Unchanneled, P = Unpoliced>`,
//! which is the rack with both of its framework rows on it. That is what makes it general rather
//! than a place a second block had to be retrofitted into: the policy row was added by adding a
//! defaulted parameter and changing no site that names one spelling, which is exactly what the
//! channels round claimed it would cost.
//!
//! # `stream` is the one row that is a VALUE and not a parameter, and the reason is the emission
//!
//! [`StreamOptions`] holds two framework-open trait objects, so it can be neither deserialized nor
//! projected off a declaration — and the row that would have carried it as a fourth parameter has
//! nowhere to read its TYPE from. A declaration states [`Declared::Pair`](super::Declared::Pair) and
//! the graph root's emission cannot see it, so the spine's field type is written once for every
//! mount; a parameter whose value differed per node would have to be projected through
//! [`Mount`](super::Mount), and a root's OPTIONS type would then refuse to exist for a node whose
//! body was not written yet — the obligation the launch discharges at its own call site, moved back
//! onto the declaration.
//!
//! So the seats ride as a concrete `Option<StreamOptions>`, `serde(skip)`ped because a trait object
//! has no document form, and a deployment states them in CODE. What that costs is the value-like
//! derives: a rack holding a trait object is no more `Copy`, `Eq` or `Hash` than
//! [`Policies`](super::Policies) is, for exactly that type's reason.

use crate::drive::StreamOptions;

#[cfg(test)]
mod tests;

/// A node's own section of a deployment's options: writing one is what launches the node, and what
/// is under it is what the node is built with.
///
/// # `options` is OPTIONAL inside a present section
///
/// A section with no `options` key is the node at whatever its own options say by default —
/// `[decode]` alone, the common case, and the only shape a zero-knob node (`type Options = ()`) can
/// be written in at all. What fills a `None` is the CONSTRUCTION's own door: it is
/// [`AsyncConstructor::new`](super::AsyncConstructor::new)'s condition — the options' [`Default`] — restated
/// as data, so the two agree by construction rather than by convention.
///
/// # `channels` and `policies` are the FRAMEWORK's blocks, and they are optional the same way
///
/// A section with no `channels` key is a node whose every edge stands at whatever its declaration
/// and the framework say — which is nearly every node. What a written one holds is the emitted
/// per-node shelf, one field per declared source, and the parameter's default
/// ([`Unchanneled`](super::Unchanneled)) is the shelf of a node that declared none.
///
/// `policies` is the second row of the same rack and reads the same way — see
/// [`PolicyShelf`](super::PolicyShelf) for what it can hold today, which is nothing, and why that
/// is the honest content rather than an unfinished one.
///
/// # Examples
///
/// ```
/// use ingraph::NodeSection;
///
/// /// A node's own options, as its author writes them.
/// #[derive(Debug, PartialEq)]
/// struct DecodeOptions {
///   threads: usize,
/// }
///
/// // A section states what it is tuned to, and its presence is what runs the node.
/// let tuned = NodeSection::new(DecodeOptions { threads: 8 });
/// assert_eq!(tuned.options(), Some(&DecodeOptions { threads: 8 }));
///
/// // A section with no options at all — the node at its own defaults.
/// let plain = NodeSection::<DecodeOptions>::default();
/// assert_eq!(plain.options(), None);
/// assert_eq!(plain.channels(), None);
/// assert_eq!(plain.policies(), None);
/// assert!(plain.stream().is_none());
/// ```
///
/// # `stream` is the rack's third framework row, and it is stated in CODE
///
/// A section with no `stream` seats is a streaming node's lane at [`StreamOptions::new`]'s three
/// shipped answers, and a buffered node reads the row not at all — see the module note for why this
/// one is a value where the other two are parameters.
#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
// The bound is WRITTEN rather than inferred, and that is the whole of what keeps a mandatory knob
// mandatory. serde reads `#[serde(default)]` on a field mentioning `O` as `O: Default`, which would
// make a section deserializable only for options that can be built out of nothing — so an options
// type with a required field would have no section at all rather than one that refuses by name. The
// default the attribute actually spends is `Option::<O>::default()`, which every `O` already has —
// and the same sentence is why the shelf is held optionally rather than defaulted into existence.
#[cfg_attr(
  feature = "serde",
  serde(bound(
    deserialize = "O: serde::Deserialize<'de>, C: serde::Deserialize<'de>, P: \
                   serde::Deserialize<'de>"
  ))
)]
pub struct NodeSection<O, C = super::Unchanneled, P = super::Unpoliced> {
  #[cfg_attr(feature = "serde", serde(default))]
  options: Option<O>,
  #[cfg_attr(feature = "serde", serde(default))]
  channels: Option<C>,
  #[cfg_attr(feature = "serde", serde(default))]
  policies: Option<P>,
  /// The seats a STREAMING node's lane runs under — `None` being [`StreamOptions::new`]'s own.
  ///
  /// `serde(skip)` rather than `serde(default)`: what is under it is a width beside two trait
  /// objects, and a document that could name a [`FeedPolicy`](crate::FeedPolicy) would be a document
  /// naming a Rust type. `deny_unknown_fields` is what turns a `stream` key written anyway into a
  /// refusal at deserialization rather than a knob that is silently dropped.
  #[cfg_attr(feature = "serde", serde(skip))]
  stream: Option<StreamOptions>,
}

impl<O> NodeSection<O, super::Unchanneled, super::Unpoliced> {
  /// A section that runs `options`.
  ///
  /// It mints the DEFAULT shelf, which is what keeps `NodeSection::new(options)` a complete
  /// spelling: a bare call has no place to say which framework blocks ride along, and nearly every
  /// section carries none. A section that does have one is this one plus
  /// [`with_channels`](Self::with_channels), which brings the shelf's type with it.
  #[inline]
  #[must_use]
  pub const fn new(options: O) -> Self {
    Self {
      options: Some(options),
      channels: None,
      policies: None,
      stream: None,
    }
  }
}

impl<O, C, P> NodeSection<O, C, P> {
  /// Run it with `channels` — the framework block, stated in code rather than in a document.
  ///
  /// The shelf's TYPE comes with the value, so the section a deployment assembles in code is typed
  /// by the block it wrote, exactly as one parsed from a document is by the block that was there.
  #[inline]
  #[must_use]
  pub fn with_channels<D>(self, channels: D) -> NodeSection<O, D, P> {
    NodeSection {
      options: self.options,
      channels: Some(channels),
      policies: self.policies,
      stream: self.stream,
    }
  }

  /// Run it with `policies` — the rack's second framework block, stated the same way.
  ///
  /// The bound is where [`PolicyShelf`](super::PolicyShelf) BITES. A channels block is checked when
  /// it is read, at [`Channels::mounted`](super::Channels::mounted); a policies block has nothing
  /// reading it yet, so the one place the framework can hold a type to being a policy block is the
  /// door it comes through in code.
  #[inline]
  #[must_use]
  pub fn with_policies<S>(self, policies: S) -> NodeSection<O, C, S>
  where
    S: super::PolicyShelf,
  {
    NodeSection {
      options: self.options,
      channels: self.channels,
      policies: Some(policies),
      stream: self.stream,
    }
  }

  /// Run its LANE under `stream` — the rack's third framework block, and the one a document cannot
  /// carry.
  ///
  /// It takes a value rather than a parameter, so writing it changes nothing about the section's
  /// type: a spine's field is one spelling for every mount, and a streaming node's seats had to fit
  /// inside it. A node whose declaration wrote no `stream` word holds a lane nowhere and reads this
  /// not at all.
  #[inline]
  #[must_use]
  pub fn with_stream(mut self, stream: StreamOptions) -> Self {
    self.stream = Some(stream);
    self
  }

  /// What it is built with, where the section said — `None` being the node at its own defaults.
  #[inline]
  #[must_use]
  pub const fn options(&self) -> Option<&O> {
    self.options.as_ref()
  }

  /// What it tunes its edges to, where the section wrote a block — `None` being every edge at
  /// whatever the declaration and the framework say.
  #[inline]
  #[must_use]
  pub const fn channels(&self) -> Option<&C> {
    self.channels.as_ref()
  }

  /// Which policies it selects, where the section wrote a block — `None` being every concern at
  /// whatever the deployment's own [`Policies`](crate::Policies) say.
  #[inline]
  #[must_use]
  pub const fn policies(&self) -> Option<&P> {
    self.policies.as_ref()
  }

  /// What its LANE runs under, where the section wrote seats — `None` being
  /// [`StreamOptions::new`]'s three shipped answers, and `None` for every buffered node, which has
  /// no lane to seat.
  #[inline]
  #[must_use]
  pub const fn stream(&self) -> Option<&StreamOptions> {
    self.stream.as_ref()
  }

  /// [`options`](Self::options), moved out — what a construction is handed.
  #[inline]
  #[must_use]
  pub fn into_options(self) -> Option<O> {
    self.options
  }

  /// The same section with its framework blocks DROPPED — what is left after they have been spent.
  ///
  /// The blocks and the options travel to different places: a `channels` block is read into the
  /// deployment's own [`Channels`](super::Channels) table at the top of the launch, and the options
  /// go into the node's construction one step later. Once the first has happened the shelf's TYPE is
  /// carrying nothing, and every walk downstream of it would have to be generic over a parameter
  /// with no reader.
  ///
  /// So the entry hands the create walk a section that has already given up its shelf, and
  /// [`Creation::node`](super::Creation::node) stays the one-parameter door every hand-written
  /// arrangement already calls.
  #[inline]
  #[must_use]
  pub fn unshelved(self) -> NodeSection<O, super::Unchanneled, super::Unpoliced> {
    NodeSection {
      options: self.options,
      channels: None,
      policies: None,
      stream: None,
    }
  }
}

impl<O, C, P> Default for NodeSection<O, C, P> {
  /// The node runs, at its own defaults — `[decode]` with nothing under it.
  ///
  /// Hand-written so neither `O` nor `C` need be [`Default`]: a section with no options states an
  /// ABSENCE, and what fills it is the construction's door rather than a value this carrier had to
  /// be able to build.
  #[inline]
  fn default() -> Self {
    Self {
      options: None,
      channels: None,
      policies: None,
      stream: None,
    }
  }
}