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
//! What a caller may say about how a package is RUN: [`MongoOptions`].
//!
//! # One type, and it holds one thing
//!
//! The lane's only policy is the READ CONCERN, and the policy is derived rather than configured —
//! see [`MongoOptions::concern`]. So this type exists to OVERRIDE a derivation, which is why its
//! single slot is an [`Option`] and why its default holds nothing: a caller who says nothing gets
//! the policy, and a caller who says something gets exactly that, on every call the value is passed
//! to.
//!
//! It is a type rather than a parameter because the derivation will grow — a `$lookup`'s ceiling, a
//! batch size, a comment for the profiler are all fields the lane will want — and a signature that
//! took each of them as an argument would break at every one. The house options shape is what makes
//! adding a field additive.

use mongodb::options::{ReadConcern, ReadConcernLevel};

/// The read concern a pipeline spanning MORE THAN ONE collection runs under, unless a caller says
/// otherwise.
///
/// **`snapshot`**, and the reason is what a multi-collection pipeline IS: a `$lookup` reads the
/// looked-into collection at a point the server chooses, so without a snapshot the parent documents
/// and the joined ones can come from two different states of the database — a child that was
/// deleted after its parent was read, a parent whose join returns a row it no longer points at.
/// Neither is an error; both are an answer no consistent database ever held.
///
/// A LEVEL rather than a whole [`ReadConcern`], because the level is the part that is a constant:
/// `ReadConcern` is `#[non_exhaustive]` and its constructors are not `const`, so a `const` of the
/// level is as much of this decision as the type system will hold — and it is the whole decision.
///
/// # It needs MongoDB 5.0, which is this lane's floor
///
/// `snapshot` outside a transaction is a 5.0 feature. Below that the server refuses the command
/// rather than answering inconsistently, which is the failure mode to prefer — but it IS a refusal,
/// so the floor is documented here and in [`lane`](super::lane) rather than discovered by a
/// deployment.
pub const DEFAULT_SPANNING_CONCERN: ReadConcernLevel = ReadConcernLevel::Snapshot;

/// How a package is run: what a caller wants said about the read, and nothing about what to read.
///
/// # The empty value is the ordinary one
///
/// [`new`](Self::new) holds no override, so the lane derives the concern from the package — which
/// is the zero-glue path. Everything here is for the call that has a reason to differ.
#[derive(Debug, Clone, Default, PartialEq)]
#[must_use]
pub struct MongoOptions {
  /// The concern to run under WHATEVER the package reads, or [`None`] for the derived policy.
  read_concern: Option<ReadConcern>,
}

impl MongoOptions {
  /// The derived policy and nothing else — what a caller with no reason to differ passes.
  ///
  /// `const`, so a call site that always runs the same way can state these once as an item rather
  /// than building one per query.
  #[inline]
  pub const fn new() -> Self {
    Self { read_concern: None }
  }

  /// The concern every call under these options runs at, or [`None`] where the lane derives one.
  #[inline]
  #[must_use]
  pub const fn read_concern(&self) -> Option<&ReadConcern> {
    self.read_concern.as_ref()
  }

  /// Run at `concern`, whatever the package reads.
  ///
  /// It OVERRIDES the derivation rather than adjusting it: a caller who names a concern has a
  /// reason the package cannot see — a secondary read, a `linearizable` requirement, a deployment
  /// below this lane's server floor — and a policy that then widened it would be answering a
  /// different question.
  #[inline]
  pub fn with_read_concern(mut self, concern: impl Into<Option<ReadConcern>>) -> Self {
    self.set_read_concern(concern);
    self
  }

  /// [`with_read_concern`](Self::with_read_concern), in place.
  #[inline]
  pub fn set_read_concern(&mut self, concern: impl Into<Option<ReadConcern>>) -> &mut Self {
    self.read_concern = concern.into();
    self
  }

  /// The concern a package reading `spans` collections actually runs at.
  ///
  /// The override where there is one; otherwise the derivation, which is the whole policy in one
  /// line: a pipeline touching more than one collection wants one state of the database, and one
  /// touching a single collection has nothing to be inconsistent WITH.
  ///
  /// [`None`] is not *no concern* — it is *say nothing*, which lets the concern the caller
  /// configured on their own `Database` or `Client` handle stand. A lane that wrote `local` there
  /// would silently override a deployment's own `majority` default, which is the sort of decision a
  /// library must not make on a caller's behalf.
  pub(super) fn concern(&self, spans: bool) -> Option<ReadConcern> {
    if let Some(concern) = &self.read_concern {
      return Some(concern.clone());
    }
    spans.then(|| ReadConcern::from(DEFAULT_SPANNING_CONCERN))
  }
}

#[cfg(test)]
mod tests;