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 COLUMN SUBSET, ARRIVING AT A REAL SCHEMA — what this backend does with each arm, and the one
//! it is honestly short on.
//!
//! Beside [`tests`](super::tests) rather than inside it, on this module's own precedent: one file
//! per thing being proved. What a subset MEANS is the seam's own doc; what an emission puts in one
//! is `ingraph-codegen`'s. Here there is a real index on a real directory, so here is where *the
//! parser's default fields are the subset's* can be read rather than claimed.
//!
//! # A slot holds ONE searchable box, and every claim below is shaped by that
//!
//! A tantivy slot's schema carries one text field, `body`. So [`All`](FulltextSubset::All) is that
//! field — byte for byte the query this backend has always run — and a `These` naming it is the same
//! query. Every OTHER name is refused, and the refusal is this backend reporting that the per-field
//! DOCUMENT has not landed rather than answering from a box that holds every elected field's text at
//! once.
//!
//! The refusal is worth its own file because the alternative is silent: an implementation that
//! dropped an unheld column from the scope would answer the whole subject to a caller who narrowed
//! it, with nothing anywhere to say so.

use core::{
  future::Future,
  num::NonZeroUsize,
  pin::pin,
  task::{Context, Poll, Waker},
};

use super::{
  AsyncFulltextRead, AsyncFulltextWrite, Connected, FulltextStore, FulltextSubset,
  SEARCHABLE_FIELD, Scored, TantivyDoc, TantivyFulltext, TantivyFulltextError, TantivyStore,
  scoped_fields,
};
use crate::FulltextColumn;

/// The `k` every search below is handed — wider than these fixtures, so what an assertion counts is
/// the SUBSET's doing and never the ceiling's.
const ROOMY: NonZeroUsize = NonZeroUsize::new(10).expect("10 is not zero");

/// The slot every search below runs against — a NAME rather than a declaration, this file having no
/// record to derive one from.
const SLOT: &str = "subset_captions";

const HEAP: usize = TantivyStore::MIN_WRITER_HEAP_BYTES;

/// Drive a future to its value without a runtime — [`tests`](super::tests)' own, and for its reason:
/// every future this backend returns is already ready.
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 fresh store under a temporary root. The `TempDir` must OUTLIVE the store — its drop removes the
/// on-disk indices.
fn open_store() -> (tempfile::TempDir, TantivyStore) {
  let dir = tempfile::tempdir().expect("a temporary directory");
  let store = TantivyStore::open(dir.path()).expect("the store opens");
  (dir, store)
}

/// Index one body under `key`, commit, and reload — the whole batch shape, collapsed.
///
/// The entry is built BY HAND, as the emission builds one: this file is about the read's grain, so
/// nothing here goes through a record's faces.
fn commit(store: &TantivyStore, face: &TantivyFulltext, entries: &[(i64, &str)]) {
  {
    let mut writer = store
      .writer(face.slot(), HEAP)
      .expect("the slot's writer opens");
    for (key, body) in entries {
      let doc = TantivyDoc::new(face.slot())
        .with_identity(key)
        .with_address(key)
        .with_body(*body);
      block_on(face.upsert(Connected::new(store, &mut writer), doc)).expect("the document queues");
    }
    writer.commit().expect("the batch commits");
  }
  store
    .reload(face.slot())
    .expect("the slot's reader reloads");
}

/// THE WHOLE-SUBJECT ARM RESOLVES TO THE BODY FIELD, and to exactly one of it.
///
/// The half that must not move: `All` is the call this backend has always made, so a resolution that
/// widened it — or that answered an empty list, which `QueryParser` reads as *no default field* and
/// silently matches nothing for a bare term — would be a behaviour change wearing a new parameter.
#[test]
fn the_whole_subject_resolves_to_the_one_searchable_field() {
  let (_dir, store) = open_store();
  let opened = store.slot_index(SLOT, false).expect("the slot opens");

  assert_eq!(
    scoped_fields(FulltextSubset::All, &opened.fields).expect("`All` is always held"),
    vec![opened.fields.body()],
    "one field, and it is the body",
  );
}

/// A `These` NAMING THE HELD COLUMN IS THE SAME QUERY — the matrix's identity row.
///
/// Stated against the ANSWER rather than against the resolution, because the claim is about what a
/// caller gets: a subset naming everything this slot holds is the whole subject, spelled the long
/// way.
#[test]
fn a_subset_naming_the_held_column_answers_what_the_whole_subject_answers() {
  let (_dir, store) = open_store();
  let face = store.fulltext(SLOT);
  commit(
    &store,
    &face,
    &[(1, "a heron at dawn"), (2, "a car in the rain")],
  );

  let ask = |subset| {
    block_on(face.search(Connected::new(&store, ()), subset, "heron", ROOMY, None))
      .expect("the search runs")
  };

  let whole = ask(FulltextSubset::All);
  let named = ask(FulltextSubset::These(&[FulltextColumn::new(
    SEARCHABLE_FIELD,
  )]));

  assert_eq!(whole.len(), 1, "the corpus holds one heron");
  assert_eq!(
    whole.iter().map(Scored::score).collect::<Vec<_>>(),
    named.iter().map(Scored::score).collect::<Vec<_>>(),
    "the two spellings of one subject score identically",
  );
}

/// A COLUMN THIS SLOT DOES NOT HOLD IS NAMED, not dropped.
///
/// `title` is the shape a per-field door mints today — the DECLARATION's field name, where this
/// slot's one box is named `body` — so this is the gap reported at the seam that wants it. Dropping
/// the column instead would widen the caller's search in silence, which is the failure the whole
/// grain exists to prevent.
#[test]
fn a_column_this_slot_does_not_hold_is_refused_by_name() {
  let (_dir, store) = open_store();
  let face = store.fulltext(SLOT);

  let refused = block_on(face.search(
    Connected::new(&store, ()),
    FulltextSubset::These(&[FulltextColumn::new("title")]),
    "heron",
    ROOMY,
    None,
  ));

  assert!(
    matches!(
      refused,
      Err(TantivyFulltextError::UnheldColumn { column }) if column.as_str() == "title"
    ),
    "the refusal names the column: {refused:?}",
  );
  assert!(
    refused.unwrap_err().to_string().contains(SEARCHABLE_FIELD),
    "and says which one this slot does hold",
  );
}

/// THE FIRST UNHELD COLUMN IS THE ONE NAMED, in the caller's own order.
///
/// A held column BEFORE the unheld one, so a check that stopped at the first entry — or that
/// collected only what resolved — would pass this by accident.
#[test]
fn a_mixed_subset_names_the_first_column_that_is_not_held() {
  let (_dir, store) = open_store();
  let opened = store.slot_index(SLOT, false).expect("the slot opens");

  let refused = scoped_fields(
    FulltextSubset::These(&[
      FulltextColumn::new(SEARCHABLE_FIELD),
      FulltextColumn::new("standfirst"),
      FulltextColumn::new("byline"),
    ]),
    &opened.fields,
  );

  assert!(
    matches!(
      refused,
      Err(TantivyFulltextError::UnheldColumn { column }) if column.as_str() == "standfirst"
    ),
    "the FIRST unheld column, and a held one before it did not absorb the check: {refused:?}",
  );
}

/// AN EMPTY `These` IS REFUSED, because both other answers are wrong.
///
/// An empty result reads as *nothing matched* where nothing was asked, and falling back to the whole
/// subject answers a question the caller did not ask. The seam leaves this to the engine on purpose,
/// and this is the engine's answer.
#[test]
fn an_empty_subset_is_refused_rather_than_answered() {
  let (_dir, store) = open_store();
  let opened = store.slot_index(SLOT, false).expect("the slot opens");

  let refused = scoped_fields(FulltextSubset::These(&[]), &opened.fields);

  assert!(
    matches!(refused, Err(TantivyFulltextError::EmptySubset)),
    "an empty subset has no answer to give: {refused:?}",
  );
}

/// THE SUBSET IS CHECKED BEFORE THE SEARCHER IS TOUCHED — validate-then-act, over a slot that was
/// never written.
///
/// The ordering is observable exactly here: a never-written slot has an empty index and every query
/// against it answers nothing, so a refusal that arrived AFTER the search would be indistinguishable
/// from a hit-less one — unless the refusal is what comes back, which is what this asserts.
#[test]
fn the_refusal_precedes_the_search() {
  let (_dir, store) = open_store();
  let face = store.fulltext(SLOT);

  let refused = block_on(face.search(
    Connected::new(&store, ()),
    FulltextSubset::These(&[FulltextColumn::new("title")]),
    "heron",
    ROOMY,
    None,
  ));

  assert!(
    refused.is_err(),
    "an empty slot answers the refusal, not an empty hit list",
  );
}