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
use core::{
  num::NonZeroUsize,
  pin::pin,
  task::{Context, Poll, Waker},
};
use std::sync::Mutex;

use smol_bytes::Utf8Bytes;

use super::{AsyncFulltextStore, FulltextEngine, FulltextSubset};
use crate::{
  AsyncFulltextRead, AsyncFulltextWrite, ColumnReader, ColumnWriter, Connected, Field,
  FulltextRecord, FulltextTable, Hits, Identifiable, Scored, SlotName, Transformer,
  store::column::testkit::{Col, Fallback, FallbackRead, Refusal},
};

/// The `k` every search below hands the verb — the universal fact the seam now takes positionally,
/// spelled once so a test reads as a question rather than as a number.
const K: NonZeroUsize = NonZeroUsize::new(10).expect("10 is not zero");

/// Drive a `ready` future to its value without a runtime.
///
/// Hand-rolled rather than taken from an executor crate: every future here is already-ready, so what
/// this needs is one poll and a `Waker` that is never woken — and adding an async runtime as a
/// dev-dependency to spin a `Ready` would be a dependency the tests do not spend.
fn block_on<F: Future>(future: F) -> F::Output {
  let mut future = pin!(future);
  let mut cx = Context::from_waker(Waker::noop());
  loop {
    if let Poll::Ready(value) = future.as_mut().poll(&mut cx) {
      return value;
    }
  }
}

// A keyed document: the compound lineage key `(media, frame)`, and the text as a FIELD. The shape
// every full-text declaration has.
struct Caption {
  media: u64,
  frame: u32,
  text: String,
}

#[derive(Debug, Clone, PartialEq)]
struct CaptionKey {
  media: u64,
  frame: u32,
}

// The ancestor half of that key: the `media` step, with the frame left off.
#[derive(Debug, PartialEq)]
struct CaptionLineage {
  media: u64,
}

impl Identifiable for Caption {
  type Id = u32;

  fn id_ref(&self) -> &u32 {
    &self.frame
  }
}

impl Transformer for Caption {
  type Key = CaptionKey;
  type Lineage = CaptionLineage;
  type Record = Self;
  type Graphql = ();

  fn key(&self) -> CaptionKey {
    CaptionKey {
      media: self.media,
      frame: self.frame,
    }
  }
}

impl FulltextRecord for Caption {
  type Document = String;

  fn document(&self) -> &String {
    &self.text
  }
}

impl FulltextTable for Caption {
  const SLOT: &'static SlotName = SlotName::new("captions");
}

fn caption(media: u64, frame: u32, text: &str) -> Caption {
  Caption {
    media,
    frame,
    text: text.to_owned(),
  }
}

// A document that is not text at all — a structured multi-field shape, standing in for what the
// designed `DocSink` form will carry.
//
// It is the DOCUMENT SETTLEMENT stated as a type. `FulltextRecord::Document` is bound by nothing, so
// what an engine can TOKENIZE stays that engine's question, asked at its own impl. Any bound added
// to that member turns this fixture red, which is the pin the settlement gets instead of the
// mutation a bound-carrying member would have had.
struct Fields(Vec<(&'static str, String)>);

struct Structured(Fields);

impl FulltextRecord for Structured {
  type Document = Fields;

  fn document(&self) -> &Fields {
    &self.0
  }
}

/// The record face: the document by reference, at the shape the record declared.
#[test]
fn a_fulltext_record_states_its_document() {
  let caption = caption(7, 12, "a red car");

  assert_eq!(caption.document(), "a red car");

  fn document_of<T: FulltextRecord>(record: &T) -> &T::Document {
    record.document()
  }
  assert_eq!(document_of(&caption), "a red car");
}

/// The two capabilities are independent: a bound naming [`FulltextRecord`] alone reaches the
/// document, and a record with no [`Transformer`] address still has one.
///
/// `Structured` is that record, and its document is a shape no `AsRef<str>` reaches — so this also
/// asserts what the document member does NOT require.
#[test]
fn the_document_face_carries_no_identity() {
  fn width_of<T: FulltextRecord<Document = Fields>>(record: &T) -> usize {
    record.document().0.len()
  }

  let structured = Structured(Fields(vec![
    ("title", "a red car".to_owned()),
    ("caption", "parked".to_owned()),
  ]));

  assert_eq!(width_of(&structured), 2);
  assert_eq!(structured.document().0[1].1, "parked");
}

/// The unused face is a live implementation of the seam, which is what makes the seam's shape
/// provable: every associated type resolves, the write face takes the engine's own entry, the read
/// face hands back the engine's own addresses, and the BASE turns its whole address lifecycle.
#[test]
fn the_unused_face_answers_the_whole_seam() {
  assert_eq!(
    block_on(AsyncFulltextWrite::upsert(&(), Connected::new(&(), ()), ())),
    Ok(())
  );
  assert_eq!(
    block_on(AsyncFulltextRead::search(
      &(),
      Connected::new(&(), ()),
      FulltextSubset::All,
      "car",
      K,
      None
    )),
    Ok(Vec::new())
  );
  // The lifecycle, all three phases: a buffer that takes nothing, an address that IS the unit, and a
  // read phase that is whole because it holds nothing.
  //
  // Spelled through a function generic in the BASE rather than as three calls on `()`, which is the
  // same idiom `neither_verb_projects_a_record` uses below and buys the same thing twice over: the
  // composition `open ∘ finalize ∘ buffer` type-checks for EVERY engine, and the unit is only where
  // it is instantiated. Written as calls it would read as three unit values handed to each other —
  // true, and the shape of the claim lost.
  fn whole_lifecycle<E: FulltextEngine>() -> Result<(), E::Error> {
    E::open(E::finalize(E::buffer())).finish()
  }

  assert_eq!(whole_lifecycle::<()>(), Ok(()));
}

/// NEITHER verb projects anything off a record, which is A′ as an assertion.
///
/// Written as two generic functions rather than as calls, because an ABSENCE of bounds is what is
/// being asserted: both are generic over the ENGINE alone, name no record type at all, and carry no
/// `where` beyond the seam itself.
///
/// MUTATION-CHECKED: putting the record parameter back on the trait (`trait FulltextEngine<R>`) is
/// `E0107` at both signatures below — *trait takes 1 generic argument but 0 generic arguments were
/// supplied* — and takes `retrieve::keyed` and the Tantivy face's own impl with it. That is the pin
/// the de-generic gets, and it is a compile fence rather than an assertion because a re-generic is a
/// change to a SIGNATURE.
#[test]
fn neither_verb_projects_a_record() {
  fn index_anything<D>(db: &D, doc: D::Doc) -> impl Future<Output = Result<(), D::Error>>
  where
    D: AsyncFulltextWrite<Connection = (), WriteContext<'static> = ()>,
  {
    db.upsert(Connected::new(&(), ()), doc)
  }

  fn search<D>(
    db: &D,
    query: &str,
  ) -> impl Future<Output = Result<Hits<D::Address, D::Score>, D::Error>>
  where
    // `SearchOptions: 'static` is the price of naming NO knobs from a helper whose returned
    // future has no input lifetime to hang the borrow on: a `None` still has to pick a lifetime,
    // and the only one in scope here is `'static` — the posture `ReadContext<'static>` already
    // takes. A caller with knobs to pass borrows them for the call and needs neither bound.
    D: AsyncFulltextRead<Connection = (), ReadContext<'static> = ()>,
    D::SearchOptions: 'static,
  {
    db.search(Connected::new(&(), ()), FulltextSubset::All, query, K, None)
  }

  assert_eq!(block_on(index_anything::<()>(&(), ())), Ok(()));
  assert_eq!(block_on(search::<()>(&(), "car")), Ok(Vec::new()));
}

// A toy index over one slot: it records the LENGTH of every entry written to it and answers every
// search with the single hit it was seeded with. Not a backend — what it proves is that the seam
// TURNS with a body in it.
//
// Its carriers are its OWN: the entry is the text the emission flattened out of the record, and the
// address is the key that emission read off it. Neither is anything this crate names.
struct MemoryIndex {
  lengths: Mutex<Vec<usize>>,
  hit: Vec<Col>,
}

impl FulltextEngine for MemoryIndex {
  type Options = ();
  type SearchOptions = ();
  type Error = Refusal;
  type Score = f32;
  type Address = Vec<Col>;
  type Connection = ();
  type WriteBuffer = Fallback;
  type ReadBuffer = FallbackRead;

  fn buffer() -> Self::WriteBuffer {
    Fallback::default()
  }

  fn finalize(buf: Self::WriteBuffer) -> Self::Address {
    buf.0
  }

  fn open(address: Self::Address) -> Self::ReadBuffer {
    Fallback(address).read()
  }
}

impl AsyncFulltextWrite for MemoryIndex {
  type Doc = String;
  type WriteContext<'a> = ();

  fn upsert(
    &self,
    _ctx: Connected<'_, Self::Connection, Self::WriteContext<'_>>,
    doc: Self::Doc,
  ) -> impl Future<Output = Result<(), Self::Error>> + Send {
    self
      .lengths
      .lock()
      .expect("the toy index is not poisoned")
      .push(doc.len());
    core::future::ready(Ok(()))
  }
}

impl AsyncFulltextRead for MemoryIndex {
  type ReadContext<'a> = ();

  fn search(
    &self,
    _ctx: Connected<'_, Self::Connection, Self::ReadContext<'_>>,
    _subset: FulltextSubset<'_>,
    query: &str,
    _k: NonZeroUsize,
    _options: ::core::option::Option<&Self::SearchOptions>,
  ) -> impl Future<Output = Result<Hits<Self::Address, Self::Score>, Self::Error>> + Send {
    // The score carries the query's length, so a caller can tell the query actually arrived — a real
    // face would answer a relevance here, in whichever direction its engine runs.
    core::future::ready(Ok(vec![Scored::new(self.hit.clone(), query.len() as f32)]))
  }
}

// The KEY's own ROW: the STRUCTURE half — which columns cross, in which order.
//
// It names NO ENGINE, which is what the column language bought: this one impl is what crosses into
// the toy above, into the shipped tantivy index and into an engine written in a crate that has never
// heard of this one. It is what an emission writes, and the engine decides what a column IS.
impl Field for CaptionKey {
  fn write(&self, w: &mut impl ColumnWriter) {
    self.media.write(w);
    self.frame.write(w);
  }

  fn read<R: ColumnReader>(r: &mut R) -> Result<Self, R::Error> {
    Ok(Self {
      media: u64::read(r)?,
      frame: u32::read(r)?,
    })
  }
}

/// `key`, sealed into the toy index's address.
fn addressed(key: &CaptionKey) -> Vec<Col> {
  let mut buf = MemoryIndex::buffer();
  key.write(&mut buf);
  MemoryIndex::finalize(buf)
}

/// A face with a BODY: the write takes the entry the EMISSION built out of the record, and the
/// search hands back the engine's own addresses — read into the key by the framework's shared walk.
///
/// The emission is the two expressions at the call — `caption.document().clone()` and
/// `caption.key()` — and that is exactly where A′ moved them to. Nothing is qualified: the seam
/// names no record, so there is no record for inference to be ambiguous about, where the
/// record-generic form needed `FulltextDb::<Caption>::search(…)` to escape `E0284`.
#[test]
fn a_written_face_takes_the_entry_and_answers_with_addresses() {
  let caption = caption(7, 12, "a red car");
  let index = MemoryIndex {
    lengths: Mutex::new(Vec::new()),
    hit: addressed(&caption.key()),
  };

  assert_eq!(
    block_on(index.upsert(Connected::new(&(), ()), caption.document().clone())),
    Ok(())
  );
  assert_eq!(
    *index.lengths.lock().expect("the toy index is not poisoned"),
    vec!["a red car".len()]
  );

  let hits = block_on(index.search(Connected::new(&(), ()), FulltextSubset::All, "car", K, None))
    .expect("the toy index cannot fail");
  let keyed: Hits<CaptionKey, f32> =
    crate::retrieve::keyed::<MemoryIndex, CaptionKey>(hits).expect("the address reads back");
  assert_eq!(keyed.len(), 1);
  assert_eq!(keyed[0].data_ref(), &caption.key());
  assert_eq!(keyed[0].score(), 3.0);
  assert_eq!(keyed[0].clone().into_data(), caption.key());
}

// A store standing in for a real backend's two layers: the manager is opened once, and it records
// what each per-slot handle was minted for.
struct RecordingStore {
  minted: Mutex<Vec<Utf8Bytes>>,
}

impl AsyncFulltextStore for RecordingStore {
  type Options = ();
  type Error = core::convert::Infallible;
  type Handle = ();

  async fn open(_options: Self::Options) -> Result<Self, Self::Error> {
    Ok(Self {
      minted: Mutex::new(Vec::new()),
    })
  }

  fn fulltext(&self, slot: impl Into<Utf8Bytes>) -> Self::Handle {
    self
      .minted
      .lock()
      .expect("the recording store is not poisoned")
      .push(slot.into());
  }
}

/// The construction layer: open once, mint per slot. `fulltext` is sync and infallible, so a caller
/// mints a handle wherever it needs one without threading a `Result` or an await.
///
/// And the slot is the factory's ONLY parameter — a second one added here to match the vector
/// store's `dim` is `E0061` at both calls, which is the pin the missing width gets.
#[test]
fn a_declared_slot_reaches_the_store_through_the_factory() {
  let store = block_on(RecordingStore::open(())).expect("the recording store opens");

  // The slot a DECLARATION names comes off the record's own const, which is the one home that fact
  // has; the second call is the caller that door stays open for — a slot nothing declared.
  store.fulltext(Caption::SLOT.as_ref());
  store.fulltext(String::from("transcripts"));

  let minted = store
    .minted
    .lock()
    .expect("the recording store is not poisoned");
  let minted: Vec<&str> = minted.iter().map(|slot| &**slot).collect();

  assert_eq!(minted, vec!["captions", "transcripts"]);
}