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 ORDINAL IS A SORT KEY AND NOT AN ASSERTION INDEX** — a sequence with a hole, read back.
//!
//! A suite of its own beside [`super::tests`], for the reason the schema lane's shadow suite gives:
//! what is asserted here is ONE property of the gather, and holding it apart from the module's own
//! corpus keeps a change to either visible.
//!
//! # Why this is pinned when the hole cannot happen today
//!
//! Nothing in the shipped write path leaves one. A collection is written by KEYED REPLACE — the
//! edge rows for a parent are deleted and rewritten whole — so its ordinals are always `0..n` with
//! nothing missing, and a suite that only ever read what this framework wrote could never tell a
//! sort key from an index.
//!
//! What makes the distinction worth money is the WRITE GRANT: a maintenance node reaching into
//! another node's store on its own clock does partial, in-place deletion — that is what a reaper IS
//! — and the first such sweeper to delete one element of a sequence produces exactly the shape below.
//! The claim this test makes is that the READ PATH NEEDS NO MIGRATION when it does: every dialect's
//! gather is an ORDERED READ over whatever rows are there, never a positional one.
//!
//! | dialect | how the elements come back ordered |
//! |---|---|
//! | PostgreSQL | `array_agg(<value> ORDER BY <ordinal>)` |
//! | MySQL | `ORDER BY <keys…>, "__ordinal"` |
//! | SQLite | the same term, over the edge table's own primary-key index `(key…, ordinal)` |
//!
//! All three are stated in [`super`]'s own module note. None of them counts, indexes or checks for
//! contiguity, and a gap in the ordinals therefore closes up in the answer instead of shifting,
//! erroring, or leaving a hole.
//!
//! # The DELETE is out of band, and it has to be
//!
//! The hole is made with bare SQL against the edge table, going around the framework's write path on
//! purpose: that path cannot make one, so a fixture that used it would be asserting nothing. What
//! the bare statement stands in for is the future sweeper — the row is gone the way a reaper's own
//! `DELETE` would leave it gone.

#![cfg(feature = "sqlite")]

use sqlx::QueryBuilder;

use crate::{
  Carrier, ColumnName, ColumnShape, ComplexComparison, FieldName, Identifiable, Record,
  RecordAddress, Transformer,
  comparison::{Backend, sql::SqlKeyIn},
  query::sql::{
    CrossingError, ELEMENT, EdgeCollection, EdgeShape, EdgeWrite, SqlQuery, SqlWrite, distribute,
  },
};

/// A take, whose frames are a SEQUENCE: the elements live in `take_frames`, ordered by the ordinal
/// column beside them.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Take {
  id: i64,
  frames: Vec<String>,
}

impl Identifiable for Take {
  type Id = i64;

  fn id_ref(&self) -> &i64 {
    &self.id
  }
}

impl Transformer for Take {
  type Graphql = ();
  type Key = i64;
  type Lineage = i64;
  type Record = Self;

  fn key(&self) -> i64 {
    self.id
  }
}

impl<Db: Backend> Record<Db> for Take {
  type Row = TakeRow;
  type Comparison = SqlKeyIn<i64, Db, 1>;
  // This fixture is never ordered, so the empty product is the honest binding.
  type OrderBy = ();
}

/// The stored row. The collection is a FIELD and no column: it is gathered, not selected.
#[derive(Debug, Clone, PartialEq, Eq)]
struct TakeRow {
  id: i64,
  frames: Vec<String>,
}

/// The page decode leaves the collection EMPTY — materialization only appends, so a parent whose
/// gather returned nothing ends holding exactly what this wrote.
impl<'r, R> sqlx::FromRow<'r, R> for TakeRow
where
  R: sqlx::Row,
  i64: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
  for<'a> &'a str: sqlx::ColumnIndex<R>,
{
  fn from_row(row: &'r R) -> Result<Self, sqlx::Error> {
    Ok(Self {
      id: row.try_get("id")?,
      frames: Vec::new(),
    })
  }
}

/// Bind this row's one key column — the plan's half of the gather's membership.
fn take_key<Db>(row: &TakeRow, _index: usize, qb: &mut QueryBuilder<Db>)
where
  Db: sqlx::Database,
  i64: Carrier<Db>,
{
  row.id.push_bind(qb);
}

/// Give every page row the frames gathered for it — a name for the four types, [`distribute`]
/// owning the grouping and the collapse.
fn take_frames<Db>(page: &mut [TakeRow], gathered: &[Db::Row]) -> Result<(), sqlx::Error>
where
  Db: sqlx::Database,
  for<'r> i64: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'r> String: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'a> &'a str: sqlx::ColumnIndex<Db::Row>,
{
  use sqlx::Row as _;
  let element: &str = ELEMENT;
  distribute(
    page,
    gathered,
    |row| row.id,
    |row| row.try_get("id"),
    |row| row.try_get::<String, _>(element),
    |row| &mut row.frames,
  )
}

const TAKE: RecordAddress = RecordAddress::new(FieldName::new("take"), &[FieldName::new("id")]);

impl<Db> SqlQuery<Db> for TakeRow
where
  Db: Backend + sqlx::Database,
  SqlKeyIn<i64, Db, 1>: ComplexComparison<Db>,
  i64: Carrier<Db>,
  for<'r> i64: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'r> String: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'a> &'a str: sqlx::ColumnIndex<Db::Row>,
{
  type Record = Take;
  type Address = SqlKeyIn<i64, Db, 1>;

  const ADDRESS: RecordAddress = TAKE;
  const ALIASES: &'static [&'static str] = &["__ig_take_0__", "__ig_take_1__"];
  const COLLECTIONS: &'static [EdgeCollection<Self, Db>] = &[EdgeCollection::gather(
    &[FieldName::new("frames")],
    EdgeShape::Sequence,
    take_key::<Db>,
    take_frames::<Db>,
  )];
  /// The collection column is ABSENT, which is the plan's contract: `frames` names no column of
  /// `take`.
  const COLUMNS: &'static [ColumnShape] = &[ColumnShape::Plain(ColumnName::new("id"))];

  fn addresses(ids: &[i64]) -> Result<Self::Address, CrossingError> {
    Ok(SqlKeyIn::new(
      ["id"],
      ids.iter().map(|id| [*id]).collect::<Vec<_>>(),
    ))
  }

  fn id(&self) -> Result<i64, CrossingError> {
    Ok(self.id)
  }

  fn record(self) -> Result<Take, CrossingError> {
    Ok(Take {
      id: self.id,
      frames: self.frames,
    })
  }
}

/// How many frames this row holds.
fn frames_len(row: &TakeRow) -> usize {
  row.frames.len()
}

/// The `at`th frame, bound — the write half's element, whose POSITION becomes the ordinal.
fn frames_element<Db>(row: &TakeRow, at: usize, qb: &mut QueryBuilder<Db>)
where
  Db: sqlx::Database,
  String: Carrier<Db>,
{
  row.frames[at].push_bind(qb);
}

impl<Db> SqlWrite<Db> for TakeRow
where
  Db: Backend + sqlx::Database,
  SqlKeyIn<i64, Db, 1>: ComplexComparison<Db>,
  i64: Carrier<Db>,
  String: Carrier<Db>,
  for<'r> i64: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'r> String: sqlx::Decode<'r, Db> + sqlx::Type<Db>,
  for<'a> &'a str: sqlx::ColumnIndex<Db::Row>,
{
  const EDGES: &'static [EdgeWrite<Self, Db>] = &[EdgeWrite::new(
    &[FieldName::new("frames")],
    EdgeShape::Sequence,
    frames_len,
    frames_element::<Db>,
  )];

  fn row(record: Take) -> Result<Self, CrossingError> {
    Ok(Self {
      id: record.id,
      frames: record.frames,
    })
  }

  fn bind(&self, at: usize, qb: &mut QueryBuilder<Db>) {
    debug_assert_eq!(at, 0, "this row has one column");
    self.id.push_bind(qb);
  }

  fn bind_address(&self, _at: usize, qb: &mut QueryBuilder<Db>) {
    self.id.push_bind(qb);
  }
}

/// The half no rendered statement can show: a stored sequence missing a middle ordinal.
mod live {
  use sqlx::{Connection as _, Executor as _, sqlite::SqliteConnection};

  use super::{Take, TakeRow};
  use crate::query::sql::{get, insert};

  /// The two tables this row needs, created by hand — the schema lane's own suite is where the DDL
  /// is the subject, and here it is a fixture. The edge table's primary key is `(id, ordinal)`,
  /// which is the layout the framework emits and the index SQLite's ordered read rides.
  async fn empty() -> SqliteConnection {
    let mut db = SqliteConnection::connect("sqlite::memory:")
      .await
      .expect("an in-memory database");
    for ddl in [
      r#"CREATE TABLE "take" ("id" INTEGER PRIMARY KEY)"#,
      r#"CREATE TABLE "take_frames" ("id" INTEGER, "frames_ordinal" INTEGER, "frames" TEXT,
         PRIMARY KEY ("id", "frames_ordinal"))"#,
    ] {
      db.execute(ddl).await.expect("a table");
    }
    db
  }

  /// The ordinals actually stored for `id`, read out of band — what the hole looks like on disk.
  async fn ordinals(db: &mut SqliteConnection, id: i64) -> Vec<i64> {
    sqlx::query_scalar(
      r#"SELECT "frames_ordinal" FROM "take_frames" WHERE "id" = ? ORDER BY "frames_ordinal""#,
    )
    .bind(id)
    .fetch_all(db)
    .await
    .expect("the engine answers")
  }

  /// A take of three frames, written through the framework's own write path.
  async fn written(db: &mut SqliteConnection) -> Take {
    let take = Take {
      id: 1,
      frames: ["a", "b", "c"].map(ToOwned::to_owned).to_vec(),
    };
    insert::<TakeRow, sqlx::Sqlite, _>(db, take.clone())
      .await
      .expect("the take is written");
    take
  }

  /// The premise: the write path lays the sequence down at `0, 1, 2`, so the ordinal really is the
  /// position at the moment of writing — which is what makes the hole below a DEPARTURE from it
  /// rather than a shape that was never contiguous.
  #[tokio::test]
  async fn the_write_lays_the_sequence_down_contiguously() {
    let mut db = empty().await;
    let take = written(&mut db).await;

    assert_eq!(ordinals(&mut db, 1).await, [0, 1, 2]);
    assert_eq!(
      get::<TakeRow, sqlx::Sqlite, _>(&mut db, &1, false)
        .await
        .expect("the take is there"),
      Some(take),
    );
  }

  /// **THE PIN.** One element deleted in place, out of band, and the gather answers `[a, c]`: in
  /// order, complete, and with no error.
  ///
  /// The mutations this catches are the three a positional reading would make — an answer of
  /// `[a, b]` (the ordinal read as an index into the returned rows), an answer carrying a hole or a
  /// default in the middle, and a refusal about a missing ordinal. None of them happens, because
  /// every dialect's gather orders BY the ordinal rather than counting on it.
  #[tokio::test]
  async fn a_deleted_middle_ordinal_closes_up_in_the_answer() {
    let mut db = empty().await;
    written(&mut db).await;

    // OUT OF BAND, on purpose: the framework's own write path replaces a collection whole and can
    // never leave this shape. What this stands in for is a future write-grant sweeper's own
    // in-place `DELETE`.
    sqlx::query(r#"DELETE FROM "take_frames" WHERE "id" = ? AND "frames_ordinal" = ?"#)
      .bind(1i64)
      .bind(1i64)
      .execute(&mut db)
      .await
      .expect("the middle edge row is deleted");
    assert_eq!(
      ordinals(&mut db, 1).await,
      [0, 2],
      "the stored ordinals are no longer contiguous"
    );

    let got = get::<TakeRow, sqlx::Sqlite, _>(&mut db, &1, false)
      .await
      .expect("a hole is not an error");
    assert_eq!(
      got,
      Some(Take {
        id: 1,
        frames: ["a", "c"].map(ToOwned::to_owned).to_vec(),
      }),
      "the surviving elements come back in ordinal order, and the gap closes up"
    );
  }

  /// The same reading from the other end: deleting the FIRST ordinal leaves an answer that starts at
  /// `1`, so nothing anywhere assumes a sequence begins at zero either.
  #[tokio::test]
  async fn a_sequence_that_no_longer_starts_at_zero_still_reads_in_order() {
    let mut db = empty().await;
    written(&mut db).await;

    sqlx::query(r#"DELETE FROM "take_frames" WHERE "id" = ? AND "frames_ordinal" = ?"#)
      .bind(1i64)
      .bind(0i64)
      .execute(&mut db)
      .await
      .expect("the first edge row is deleted");

    assert_eq!(
      get::<TakeRow, sqlx::Sqlite, _>(&mut db, &1, false)
        .await
        .expect("a missing zeroth ordinal is not an error"),
      Some(Take {
        id: 1,
        frames: ["b", "c"].map(ToOwned::to_owned).to_vec(),
      }),
    );
  }

  /// And an emptied sequence is the EMPTY collection rather than an absent row or a refusal — the
  /// end state a sweeper that deleted every element leaves behind.
  #[tokio::test]
  async fn a_sequence_swept_empty_is_the_empty_collection() {
    let mut db = empty().await;
    written(&mut db).await;

    sqlx::query(r#"DELETE FROM "take_frames" WHERE "id" = ?"#)
      .bind(1i64)
      .execute(&mut db)
      .await
      .expect("every edge row is deleted");

    assert_eq!(
      get::<TakeRow, sqlx::Sqlite, _>(&mut db, &1, false)
        .await
        .expect("an emptied collection is not an error"),
      Some(Take {
        id: 1,
        frames: Vec::new(),
      }),
    );
  }
}