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 SYSTEM OF RECORD both live walks retrieve into: a transcript segment, its stored row, and
//! the filter a client sends against it.
//!
//! Written BY HAND, for the reason `query::sql::find`'s fixture is: `ingraph-codegen` cannot reach
//! this crate, so a test here cannot be an expansion — what it can be is the same thing a third
//! party writes. Everything the retrieve face asks of a declaration is asked of this file too.
//!
//! # The filter is over DURATION, and that is the multilingual ruling showing up in a fixture
//!
//! A canonical filter example must not be `lang = "en"`. Language is not a pipeline semantic
//! anywhere on this path — a German segment containing the English word the query asked for IS a
//! hit — so the filters here are product dimensions: how long the segment runs.

use sqlx::{Connection as _, Sqlite};

use crate::{
  Carrier, ColumnName, ColumnReader, ColumnShape, ColumnWriter, ComplexComparison, Field,
  FieldName, Identifiable, Record, RecordAddress, ScalarFilter, Transformer,
  comparison::{
    At, Backend, Frame, TryFromFilter,
    sql::{SqlKeyIn, SqlLoweringError, SqlScalarComparison},
  },
  query::sql::{CrossingError, SqlQuery},
};

/// One transcript segment of one media — the WHOLE upstream domain entity a tier-B retrieve answers
/// with.
#[derive(Debug, Clone, PartialEq)]
pub(super) struct Segment {
  pub(super) media: String,
  pub(super) id: i64,
  pub(super) transcript: String,
  /// The product dimension a filter is written over — seconds.
  pub(super) duration: i64,
}

/// `lineage ⊕ id`: the media step and the segment's own id. It is what an index answers with, and
/// what the gather crosses back into an address.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub(super) struct SegmentKey {
  pub(super) media: String,
  pub(super) id: i64,
}

/// THE KEY'S ROW, in the column language — engine-blind, so this file's engine and every other one
/// read the key through the same impl. It lives beside the CORPUS rather than beside an engine,
/// which is the merged family's whole shape: one row per TYPE.
impl Field for SegmentKey {
  fn write(&self, w: &mut impl ColumnWriter) {
    self.media.write(w);
    self.id.write(w);
  }

  fn read<R: ColumnReader>(r: &mut R) -> Result<Self, R::Error> {
    Ok(Self {
      media: String::read(r)?,
      id: i64::read(r)?,
    })
  }
}

impl Identifiable for Segment {
  type Id = i64;

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

/// The KEY answers the identity too, which is what lets a retrieved key become an address.
///
/// Every key a node macro emits carries this impl — a derived index's own binding reads its `Id`
/// off the carried key exactly this way — so the bound [`SqlGather`](crate::retrieve::SqlGather)
/// names is one every retrievable key already satisfies.
impl Identifiable for SegmentKey {
  type Id = i64;

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

impl Transformer for Segment {
  type Key = SegmentKey;
  type Lineage = String;
  type Record = Self;
  type Graphql = ();

  fn key(&self) -> SegmentKey {
    SegmentKey {
      media: self.media.clone(),
      id: self.id,
    }
  }
}

/// The stored row.
#[derive(Debug, Clone, PartialEq)]
pub(super) struct SegmentRow {
  media: String,
  id: i64,
  transcript: String,
  duration: i64,
}

impl<'r, R> sqlx::FromRow<'r, R> for SegmentRow
where
  R: sqlx::Row,
  i64: sqlx::Decode<'r, R::Database> + sqlx::Type<R::Database>,
  String: 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 {
      media: row.try_get("media_id")?,
      id: row.try_get("id")?,
      transcript: row.try_get("transcript")?,
      duration: row.try_get("duration")?,
    })
  }
}

/// The record's LOWERED comparison — one predicate over one column, pushing its own frame exactly as
/// an emitted comparison does.
pub(super) struct SegmentFilter<Db> {
  duration: SqlScalarComparison<i64, Db>,
}

impl<Db> ComplexComparison<Db> for SegmentFilter<Db>
where
  Db: Backend<Error = SqlLoweringError>,
  SqlScalarComparison<i64, Db>: ComplexComparison<Db>,
{
  fn conjuncts(&self) -> usize {
    ComplexComparison::<Db>::conjuncts(&self.duration)
  }

  fn apply<'q>(
    &'q self,
    at: At<'_>,
    builder: <Db as Backend>::Builder<'q>,
  ) -> Result<<Db as Backend>::Builder<'q>, <Db as Backend>::Error> {
    let frame = At::frame(at, FieldName::new("duration"));
    ComplexComparison::<Db>::apply(&self.duration, Frame::at(&frame), builder)
  }
}

/// Segments running no longer than `seconds` — the client's filter, crossed into the database's own
/// comparison exactly as a declared conversion crosses one.
pub(super) fn shorter_than(seconds: i64) -> SegmentFilter<Sqlite> {
  SegmentFilter {
    duration: SqlScalarComparison::try_from_filter(ScalarFilter::<i64>::new().with_lte(seconds))
      .expect("an integer bound crosses into SQLite"),
  }
}

impl<Db> Record<Db> for Segment
where
  Db: Backend,
  SegmentFilter<Db>: ComplexComparison<Db>,
{
  type Row = SegmentRow;
  type Comparison = SegmentFilter<Db>;
  type OrderBy = ();
}

impl<Db> SqlQuery<Db> for SegmentRow
where
  Db: Backend + sqlx::Database,
  SegmentFilter<Db>: ComplexComparison<Db>,
  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 = Segment;
  type Address = SqlKeyIn<i64, Db, 1>;

  const ADDRESS: RecordAddress = RecordAddress::new(
    FieldName::new("segment"),
    &[FieldName::new("media_id"), FieldName::new("id")],
  );
  const ALIASES: &'static [&'static str] = &[
    "__ig_segment_0__",
    "__ig_segment_1__",
    "__ig_segment_2__",
    "__ig_segment_3__",
    "__ig_segment_4__",
    "__ig_segment_5__",
    "__ig_segment_6__",
    "__ig_segment_7__",
  ];
  const COLUMNS: &'static [ColumnShape] = &[
    ColumnShape::Plain(ColumnName::new("media_id")),
    ColumnShape::Plain(ColumnName::new("id")),
    ColumnShape::Plain(ColumnName::new("transcript")),
    ColumnShape::Plain(ColumnName::new("duration")),
  ];

  /// The ROW-VALUE membership at width one, which is the whole of the keys half of a composed
  /// gather — and never a per-column `IN`.
  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<Segment, CrossingError> {
    Ok(Segment {
      media: self.media,
      id: self.id,
      transcript: self.transcript,
      duration: self.duration,
    })
  }
}

/// The seeded corpus, in the ONE order everything downstream reads it in.
///
/// Multilingual on purpose: the German and French rows carry the English word `sunset` verbatim,
/// which is what makes them first-class lexical hits with no language gate anywhere.
pub(super) const SEEDED: &[(&str, i64, &str, i64)] = &[
  ("m1", 1, "a long sunset over the harbour", 30),
  ("m1", 2, "Der Sonnenuntergang, ein sunset am Meer", 12),
  ("m2", 3, "le coucher de soleil — a sunset in Nice", 45),
  ("m2", 4, "sunset again, and again, sunset", 8),
  ("m3", 5, "a heron over still water", 20),
  ("m3", 6, "sunset light on the sunset ridge", 60),
];

/// A fresh in-memory store holding [`SEEDED`].
///
/// A bare [`SqliteConnection`](sqlx::sqlite::SqliteConnection) and never a `Pool`: this crate
/// enables no sqlx runtime, and constructing a pool would panic asking for one.
pub(super) async fn store() -> sqlx::sqlite::SqliteConnection {
  let mut db = sqlx::sqlite::SqliteConnection::connect("sqlite::memory:")
    .await
    .expect("an in-memory database");
  sqlx::query(
    r#"CREATE TABLE "segment" ("media_id" TEXT NOT NULL, "id" INTEGER PRIMARY KEY,
       "transcript" TEXT NOT NULL, "duration" INTEGER NOT NULL)"#,
  )
  .execute(&mut db)
  .await
  .expect("the table");
  for (media, id, transcript, duration) in SEEDED {
    sqlx::query(r#"INSERT INTO "segment" VALUES (?, ?, ?, ?)"#)
      .bind(media)
      .bind(id)
      .bind(transcript)
      .bind(duration)
      .execute(&mut db)
      .await
      .expect("a segment");
  }
  db
}

/// Drop the row at `id` from the store, leaving the INDEX still holding its key — the
/// engine-knows-it, store-lost-it case a retrieve must skip rather than refuse.
pub(super) async fn forget(db: &mut sqlx::sqlite::SqliteConnection, id: i64) {
  sqlx::query(r#"DELETE FROM "segment" WHERE "id" = ?"#)
    .bind(id)
    .execute(db)
    .await
    .expect("the row goes");
}