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 SQL family's two [`AsyncGather`]s — one statement each, and the surface they run it on is the
//! whole difference.
//!
//! [`SqlGather`] borrows a CONNECTION the caller already opened and answers the upstream's RECORDS.
//! [`SqlPooledGather`] takes a POOL and answers the ROWS. Neither is a preference: each of the two
//! differences is forced by a measurement, and both are written on the type that carries them.

use core::marker::PhantomData;

use super::AsyncGather;
use crate::{
  Identifiable, Record,
  query::sql::{SqlDialect, SqlQuery, SqlQueryError, gathered},
};

/// The system of record, as a retrieve reaches it: one connection, one row type, one dialect.
///
/// # What it composes, and why none of it is new
///
/// One call is one statement — `WHERE ("id") IN ((?), …) AND <the client's filter>` — assembled by
/// [`gathered`](crate::query::sql::gathered) out of two pieces the SQL family already had. The keys
/// half is [`SqlQuery::addresses`], the ROW-VALUE membership that
/// [`SqlKeyIn`](crate::comparison::sql::SqlKeyIn) exists to keep away from the per-column `IN`
/// spelling and its cartesian product. The filter half is the record's own comparison, lowered
/// exactly as the list lane lowers it. The rows cross back into records through the declared
/// conversions, which is the same read leg every other query uses.
///
/// So the only thing this type adds is the CORRELATION, and it adds it because a membership names a
/// set: the plan answers in whatever sequence it chose, and the retrieve's order is the engine's.
///
/// # A CONNECTION rather than a pool, and the fill loop is why
///
/// A page may take several batches, and they belong in one read — a pool handing each batch its own
/// connection would let a page span two states of the database. The caller opens whatever bracket
/// the page wants (`BEGIN`, a snapshot, nothing) and lends the connection for the whole loop.
///
/// # `PhantomData<fn() -> (Row, Db)>`
///
/// This crate's convention for every marker parameter: the function pointer contributes no
/// auto-trait obligation and no variance, so the type is `Send`/`Sync` on the borrow alone.
pub struct SqlGather<'a, Row, Db>
where
  Db: sqlx::Database,
{
  connection: &'a mut Db::Connection,
  row: PhantomData<fn() -> (Row, Db)>,
}

impl<'a, Row, Db> SqlGather<'a, Row, Db>
where
  Db: sqlx::Database,
{
  /// Gather through `connection`, reading `Row`'s columns.
  ///
  /// The row type is what picks the table, the columns and the address predicate — the same key
  /// [`SqlQuery`] is implemented on — and a caller naming a record stored in two databases names
  /// which one here.
  #[inline]
  pub const fn new(connection: &'a mut Db::Connection) -> Self {
    Self {
      connection,
      row: PhantomData,
    }
  }
}

/// # The key becomes an ID through [`Identifiable`], which every emitted key answers
///
/// A retrieve deduped at the KEY grain, and a row is addressed by its ID — one column, `UNIQUE` by
/// the schema's own law. `K: Identifiable` is what crosses between them, and it is not a bound
/// invented here: a derived index's binding already reads its id off the carried key exactly this
/// way, so every key that can be retrieved can be addressed.
///
/// # What this impl asks of the ID, and why each is its own
///
/// `Clone` builds the batch's id list; `PartialEq` lines the answered rows back up against it.
/// Neither is [`Identifiable::Id`]'s business — the member is unbounded there on purpose — so both
/// are named HERE, at the backend that spends them, which is the same discipline every other
/// engine-side impl in this crate follows.
impl<Row, Db, K> AsyncGather<K, Row::Record> for SqlGather<'_, Row, Db>
where
  Row: SqlQuery<Db> + for<'r> sqlx::FromRow<'r, Db::Row>,
  Db: SqlDialect,
  for<'e> &'e mut Db::Connection: sqlx::Executor<'e, Database = Db>,
  Db::Arguments: sqlx::IntoArguments<Db>,
  K: Identifiable<Id = <Row::Record as Identifiable>::Id>,
  <Row::Record as Identifiable>::Id: Clone + PartialEq,
{
  type Filter = <Row::Record as Record<Db>>::Comparison;
  type Error = SqlQueryError;

  async fn gather(
    &mut self,
    keys: &[K],
    filter: Option<&Self::Filter>,
  ) -> Result<Vec<Option<Row::Record>>, SqlQueryError> {
    let ids: Vec<<Row::Record as Identifiable>::Id> =
      keys.iter().map(|key| key.id_ref().clone()).collect();
    let rows = gathered::<Row, Db>(self.connection, &ids, filter).await?;

    // Each row read back to the id it IS, once — the dual of `addresses`, through the same declared
    // conversion. Done before the walk so a crossing refusal is reported rather than being spent
    // once per position it is compared at.
    let mut answered: Vec<Option<(<Row::Record as Identifiable>::Id, Row)>> =
      Vec::with_capacity(rows.len());
    for row in rows {
      let id = row.id()?;
      answered.push(Some((id, row)));
    }

    // POSITIONAL: one slot per key, in the key list's order. A key with no row — pruned by the
    // filter, or lost by the store — is `None`, which the fill loop reads as *keep filling*.
    //
    // `Option::take` is what makes a duplicate id impossible to hand out twice; the schema's
    // `UNIQUE` says there can be at most one, and this says so a second time without trusting it.
    let mut found = Vec::with_capacity(ids.len());
    for id in &ids {
      let row = answered
        .iter_mut()
        .find(|slot| slot.as_ref().is_some_and(|(answered, _)| answered == id))
        .and_then(Option::take);
      found.push(match row {
        Some((_, row)) => Some(row.record()?),
        None => None,
      });
    }
    Ok(found)
  }
}

/// The system of record as a RESOLVER reaches it: one pool, one row type, one dialect — and the
/// ROWS themselves, which is the one thing a wire face can cross.
///
/// # `&Pool` rather than a borrowed connection, and `Send` is what decides it
///
/// `ingraph/tests/wire_trio.rs` put five shapes to the compiler, and every one that reached a
/// borrowed `Db::Connection` inside a resolver failed identically — *implementation of
/// `sqlx::Acquire` is not general enough* — while the same call awaited from an ordinary test
/// compiled and ran. So [`SqlGather`] is not mountable on a wire face at all, whatever its body
/// does: async-graphql bounds every resolver future `Send`, and sqlx's
/// `Acquire<'c> for &'c mut Connection` is then asked for at two independent lifetimes, which no
/// impl answers. `&Pool<Db>` is `Acquire` and is `Send` by construction, the pool being `Sync` and
/// shared rather than uniquely borrowed — the same measurement [`SqlDoor`](crate::SqlDoor) is built
/// around, spent one layer down.
///
/// # The connection is ACQUIRED ONCE AND HELD, which is what keeps the sibling's invariant
///
/// A page may take several batches, and a pool handing each of them its own connection would let one
/// page span two states of the database — [`SqlGather`]'s own reason for taking a connection, and it
/// does not stop being true because the construction surface moved. So the pool is what a caller
/// hands over and the connection is still ONE per gather value: the first
/// [`gather`](AsyncGather::gather) acquires, every batch after it spends the same one, and the fill loop
/// runs inside a single read.
///
/// LAZILY, and that is the departure from acquiring in [`new`](Self::new): a page can end without
/// asking anything — `first: 0`, an engine that answered nothing, a floor that cut the stream to
/// empty — and a connection taken for one of those is a connection held out of the pool for a
/// question nobody asked. Constructing therefore costs nothing and the first batch pays.
///
/// # It answers ROWS where [`SqlGather`] answers RECORDS, and the WIRE forces it
///
/// There is no `Record → Output` crossing anywhere in the tree, and that is a measurement rather
/// than an omission: `emit::graphql`'s `row_crossings` writes the wire object's ONLY constructor as
/// `TryFrom<<Record as Record<Db>>::Row>`, off the stored row, and the record resolver's own
/// `wire_crossing` spends exactly that one. A gather answering RECORDS therefore hands a wire face a
/// value it cannot render. The ROW is the fork point both crossings hang off — [`SqlQuery::record`]
/// for the domain entity, `TryFrom<Row>` for the wire object — so answering it is what keeps ONE
/// gather serving both, and the caller spends whichever crossing its own answer needs.
///
/// The two impls cannot be one type: `Row` and `<Row as SqlQuery<Db>>::Record` are not provably
/// distinct, so `AsyncGather<K, Row>` and `AsyncGather<K, Row::Record>` on one type is `E0119`.
///
/// # R2's SWEEP TOUCHES TWO LINES OF WHAT MOUNTS THIS
///
/// The resource re-axis re-keys the resolver's `ctx.data::<SqlDoor<Db>>()` line and the citizen
/// registration that installed it. Nothing in this type moves: it takes a `&Pool<Db>` from whoever
/// holds one, and which citizen that is is the caller's fact.
///
/// # `PhantomData<fn() -> (Row, Db)>`
///
/// This crate's convention for every marker parameter: the function pointer contributes no
/// auto-trait obligation and no variance, so the type's `Send`/`Sync` rest on the pool borrow and
/// the held connection alone — which is the whole point of it.
pub struct SqlPooledGather<'a, Row, Db>
where
  Db: sqlx::Database,
{
  pool: &'a sqlx::Pool<Db>,
  held: Option<sqlx::pool::PoolConnection<Db>>,
  row: PhantomData<fn() -> (Row, Db)>,
}

impl<'a, Row, Db> SqlPooledGather<'a, Row, Db>
where
  Db: sqlx::Database,
{
  /// Gather through `pool`, reading `Row`'s columns.
  ///
  /// `const` and connectionless: see the type's note for why the acquire waits for the first batch.
  /// The row type is what picks the table, the columns and the address predicate — the same key
  /// [`SqlQuery`] is implemented on — and a caller naming a record stored in two databases names
  /// which one here.
  #[inline]
  pub const fn new(pool: &'a sqlx::Pool<Db>) -> Self {
    Self {
      pool,
      held: None,
      row: PhantomData,
    }
  }
}

/// The bounds are [`SqlGather`]'s, unchanged, and its own note carries what each one is for: `K`
/// crosses to an address through [`Identifiable`], and the id's `Clone` and `PartialEq` are named
/// here because they are this backend's to spend rather than [`Identifiable::Id`]'s to promise.
///
/// One `Id` VALUE and not one id COLUMN: a compound address rides
/// [`SqlQuery::addresses`] into the row-value membership, which is the spelling
/// [`SqlKeyIn`](crate::comparison::sql::SqlKeyIn) exists to keep the per-column `IN` — and its
/// cartesian product — away from.
impl<Row, Db, K> AsyncGather<K, Row> for SqlPooledGather<'_, Row, Db>
where
  Row: SqlQuery<Db> + for<'r> sqlx::FromRow<'r, Db::Row>,
  Db: SqlDialect,
  for<'e> &'e mut Db::Connection: sqlx::Executor<'e, Database = Db>,
  Db::Arguments: sqlx::IntoArguments<Db>,
  K: Identifiable<Id = <Row::Record as Identifiable>::Id>,
  <Row::Record as Identifiable>::Id: Clone + PartialEq,
{
  type Filter = <Row::Record as Record<Db>>::Comparison;
  type Error = SqlQueryError;

  async fn gather(
    &mut self,
    keys: &[K],
    filter: Option<&Self::Filter>,
  ) -> Result<Vec<Option<Row>>, SqlQueryError> {
    let ids: Vec<<Row::Record as Identifiable>::Id> =
      keys.iter().map(|key| key.id_ref().clone()).collect();

    // TAKEN AND PUT BACK rather than borrowed where it sits: `Option::insert` in one match arm and
    // `Option::as_mut` in the other is the conditional reborrow the current checker refuses, and an
    // `expect` after an `is_none` test would be an invariant restated in a string where the move
    // holds it outright.
    let mut held = match self.held.take() {
      Some(held) => held,
      None => self.pool.acquire().await?,
    };
    let rows = gathered::<Row, Db>(&mut held, &ids, filter).await;
    // The connection goes back to the field BEFORE the refusal is raised. A batch that would not
    // lower — a bind ceiling, an id that will not cross — says nothing about the connection, and
    // the caller that retries with a shorter batch belongs in the read it already opened.
    self.held = Some(held);
    let rows = rows?;

    // Each row read back to the id it IS, once — the dual of `addresses`, through the same declared
    // conversion. Done before the walk so a crossing refusal is reported rather than being spent
    // once per position it is compared at.
    let mut answered: Vec<Option<(<Row::Record as Identifiable>::Id, Row)>> =
      Vec::with_capacity(rows.len());
    for row in rows {
      let id = row.id()?;
      answered.push(Some((id, row)));
    }

    // POSITIONAL: one slot per key, in the key list's order. A key with no row — pruned by the
    // filter, or lost by the store — is `None`, which the fill loop reads as *keep filling*.
    //
    // `Option::take` is what makes a duplicate id impossible to hand out twice; the schema's
    // `UNIQUE` says there can be at most one, and this says so a second time without trusting it.
    let mut found = Vec::with_capacity(ids.len());
    for id in &ids {
      found.push(
        answered
          .iter_mut()
          .find(|slot| slot.as_ref().is_some_and(|(answered, _)| answered == id))
          .and_then(Option::take)
          .map(|(_, row)| row),
      );
    }
    Ok(found)
  }
}

#[cfg(test)]
mod tests;