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 `stored` WORD, arriving at tantivy's own flag — and the default that is honestly NOT it.
//!
//! Beside [`tests`](super::tests) rather than inside it, on this repository's own precedent: one
//! file per thing being proved. What the word MEANS in a declaration is `ingraph-derive`'s
//! `index/roads.rs`; what a slot's `const STORED` looks like in an expansion is
//! `ingraph-codegen`'s. Here there is a real index on a real directory, so here is where *the flag
//! is actually set* can be read rather than claimed.
//!
//! # Every assertion is a PAIR, and it has to be
//!
//! A test that only checked *a stored slot keeps its body* would pass for a backend that stored
//! unconditionally — which is exactly what this backend did before the word existed. So each claim
//! below is made against BOTH postures, and the default's half is the one that would have passed
//! silently.

use std::path::Path;

use tantivy::{TantivyDocument, schema::Value as _};

use super::{TantivyDoc, TantivyStore, open_unfanned, upsert_entry};
use crate::{BoxWriter, FulltextRoad, Slot, SlotName};

/// A fresh store under a temporary root. The `TempDir` must OUTLIVE the store — its drop removes
/// the directory the indices are mapped from.
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)
}

/// Whether the `body` field of the index in `dir` carries tantivy's `STORED` flag.
fn body_is_stored(dir: &Path, stored: bool) -> bool {
  let opened = open_unfanned(dir, stored).expect("the slot opens");
  let schema = opened.index.schema();
  schema.get_field_entry(opened.fields.body()).is_stored()
}

/// THE FLAG ITSELF, both ways round. The default is what changed, so the default is the half that
/// matters: this backend wrote `TEXT | STORED` unconditionally before the word existed.
#[test]
fn the_posture_decides_the_flag_on_the_body_field() {
  let dir = tempfile::tempdir().expect("a temporary directory");
  assert!(
    !body_is_stored(&dir.path().join("plain"), false),
    "the default keeps nothing"
  );
  assert!(
    body_is_stored(&dir.path().join("kept"), true),
    "and the word is what asks for it"
  );
}

/// THE INDEXED HALF IS NOT A CHOICE. A full-text slot exists to be searched, so `body` is tokenized
/// in EITHER posture — stated because a schema change that reached the wrong flag would otherwise
/// look identical to this one.
#[test]
fn both_postures_index_the_body() {
  let dir = tempfile::tempdir().expect("a temporary directory");
  for (slot, stored) in [("plain", false), ("kept", true)] {
    let opened = open_unfanned(&dir.path().join(slot), stored).expect("the slot opens");
    let index = opened.index.schema();
    assert!(
      index.get_field_entry(opened.fields.body()).is_indexed(),
      "{slot} indexes its body"
    );
  }
}

/// WHAT THE FLAG BUYS, end to end: the text is retrievable from a hit's stored document under
/// `stored`, and absent under the default. The search itself succeeds in both, which is the point —
/// the default costs a reader nothing it was promised.
#[test]
fn only_a_stored_slot_hands_the_text_back() {
  for (stored, kept) in [(false, false), (true, true)] {
    let (_dir, store) = open_store();
    let mut writer = store
      .writer_with("captions", TantivyStore::MIN_WRITER_HEAP_BYTES, stored)
      .expect("the writer opens");
    let slot = smol_bytes::Utf8Bytes::from_static("captions");
    upsert_entry(
      &slot,
      &mut writer,
      TantivyDoc::new("captions")
        .with_identity(&7_i64)
        .with_address(&7_i64)
        .with_body("a red car"),
    )
    .expect("the entry is queued");
    writer.commit().expect("the batch commits");
    store.reload("captions").expect("the reader reloads");

    let opened = store
      .slot_index("captions", stored)
      .expect("the slot is open");
    let searcher = opened.reader.searcher();
    assert_eq!(searcher.num_docs(), 1, "the entry landed either way");
    // ONE document in ONE segment after a commit, so the only address there is names it — a search
    // would be a second thing to get wrong in a test about what a document HOLDS.
    let document: TantivyDocument = searcher
      .doc(tantivy::DocAddress::new(0, 0))
      .expect("the sole document");
    let body = document
      .get_first(opened.fields.body())
      .and_then(|value| value.as_str().map(str::to_owned));
    assert_eq!(
      body,
      kept.then(|| "a red car".to_owned()),
      "stored = {kept}: the body is handed back only where the declaration asked"
    );
  }
}

/// THE WORD REACHES THE FLAG WITHOUT A HUMAN RETYPING IT. `slot_writer` reads the slot's NAME and
/// its `STORED` answer off the same type, which is the door an emitted declaration opens — and the
/// two markers below differ in exactly the word this round added.
#[test]
fn the_slot_type_carries_its_own_posture_to_the_writer() {
  struct Plain;
  struct Kept;

  impl Slot for Plain {
    type Of = ();

    const SLOT: &'static SlotName = SlotName::new("plain");
    const FIELD: &'static str = "body";
    const ENGINE: &'static str = "tantivy";
  }

  impl FulltextRoad for Plain {
    const STORED: bool = false;

    type Error = core::convert::Infallible;

    fn write(_entry: &Self::Of, _into: &mut BoxWriter) -> Result<(), Self::Error> {
      Ok(())
    }
  }

  impl Slot for Kept {
    type Of = ();

    const SLOT: &'static SlotName = SlotName::new("kept");
    const FIELD: &'static str = "body";
    const ENGINE: &'static str = "tantivy";
  }

  impl FulltextRoad for Kept {
    const STORED: bool = true;

    type Error = core::convert::Infallible;

    fn write(_entry: &Self::Of, _into: &mut BoxWriter) -> Result<(), Self::Error> {
      Ok(())
    }
  }

  let (dir, store) = open_store();
  for (slot, kept) in [("plain", false), ("kept", true)] {
    let writer = if kept {
      store.slot_writer::<Kept>(TantivyStore::MIN_WRITER_HEAP_BYTES)
    } else {
      store.slot_writer::<Plain>(TantivyStore::MIN_WRITER_HEAP_BYTES)
    }
    .expect("the writer opens");
    assert_eq!(writer.slot(), slot, "the door read the slot's own name");
    drop(writer);
    assert_eq!(
      body_is_stored(&dir.path().join(slot), kept),
      kept,
      "and its own posture"
    );
  }
}