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 super::keyed;
use crate::{
  ColumnError, ColumnReader, ColumnWriter, Field, FulltextEngine, Hits, NoColumns, Scored,
};

/// A stand-in engine whose ADDRESS is a list of words — small enough to state a walk order in and
/// rich enough to leave something behind.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
struct Words(Vec<String>);

impl Words {
  fn of(words: &[&str]) -> Self {
    Self(words.iter().map(|word| (*word).to_owned()).collect())
  }
}

/// THE WRITE PHASE — a word per column, and text is the only kind this toy has a column for.
#[derive(Debug, Default)]
struct Writing(Vec<String>);

impl ColumnWriter for Writing {
  fn i64(&mut self, value: i64) {
    self.0.push(value.to_string());
  }

  fn u64(&mut self, value: u64) {
    self.0.push(value.to_string());
  }

  fn text(&mut self, value: &str) {
    self.0.push(value.to_owned());
  }

  fn bytes(&mut self, value: &[u8]) {
    self.0.push(String::from_utf8_lossy(value).into_owned());
  }

  fn uuid(&mut self, value: uuid::Uuid) {
    self.0.push(value.to_string());
  }
}

/// THE READ PHASE — words taken off the front, never rewound.
#[derive(Debug)]
struct Reading {
  words: Vec<String>,
  at: usize,
}

impl Reading {
  /// The next word, with the position moved past it before the borrow leaves.
  fn take(&mut self) -> Result<&str, Refusal> {
    let at = self.at;
    if at >= self.words.len() {
      return Err(Refusal::Truncated);
    }
    self.at = at + 1;
    Ok(&self.words[at])
  }
}

impl ColumnReader for Reading {
  type Error = Refusal;

  fn i64(&mut self) -> Result<i64, Self::Error> {
    self.take()?.parse().map_err(|_| Refusal::Truncated)
  }

  fn u64(&mut self) -> Result<u64, Self::Error> {
    self.take()?.parse().map_err(|_| Refusal::Truncated)
  }

  fn text(&mut self) -> Result<&str, Self::Error> {
    self.take()
  }

  fn bytes(&mut self) -> Result<&[u8], Self::Error> {
    self.take().map(str::as_bytes)
  }

  fn uuid(&mut self) -> Result<uuid::Uuid, Self::Error> {
    self.take()?.parse().map_err(|_| Refusal::Truncated)
  }

  fn fixed<const N: usize>(&mut self) -> Result<[u8; N], Self::Error> {
    <[u8; N]>::try_from(self.take()?.as_bytes()).map_err(|_| Refusal::Truncated)
  }

  /// The COMPLETENESS CHECK, and this walk's whole subject on the refusal side: what the retired
  /// `exhausted` verb asked, asked of the reader that knows how far it got.
  fn finish(self) -> Result<(), Self::Error> {
    if self.at == self.words.len() {
      Ok(())
    } else {
      Err(Refusal::Trailing)
    }
  }
}

#[derive(Debug, Clone, PartialEq, Eq)]
enum Refusal {
  Truncated,
  Trailing,
  Custom(String),
}

impl ColumnError for Refusal {
  fn custom<T: core::fmt::Display>(msg: T) -> Self {
    Self::Custom(msg.to_string())
  }
}

struct Engine;

impl FulltextEngine for Engine {
  type Options = ();
  type SearchOptions = ();
  type Error = Refusal;
  type Score = f32;
  type Address = Words;
  type Connection = ();
  type WriteBuffer = Writing;
  type ReadBuffer = Reading;

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

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

  fn open(address: Self::Address) -> Self::ReadBuffer {
    Reading {
      words: address.0,
      at: 0,
    }
  }
}

/// A TWO-COLUMN key — the structure half: which columns, in which order.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Pair {
  media: String,
  shot: String,
}

impl Field for Pair {
  fn write(&self, w: &mut impl ColumnWriter) {
    w.text(&self.media);
    w.text(&self.shot);
  }

  fn read<R: ColumnReader>(r: &mut R) -> Result<Self, R::Error> {
    Ok(Self {
      media: r.text()?.to_owned(),
      shot: r.text()?.to_owned(),
    })
  }
}

/// A ONE-COLUMN key over the same engine — what a key that reads FEWER columns than the address
/// holds looks like.
#[derive(Debug, Clone, PartialEq, Eq)]
struct Single(String);

impl Field for Single {
  fn write(&self, w: &mut impl ColumnWriter) {
    w.text(&self.0);
  }

  fn read<R: ColumnReader>(r: &mut R) -> Result<Self, R::Error> {
    Ok(Self(r.text()?.to_owned()))
  }
}

fn hits(addresses: &[&[&str]]) -> Hits<Words, f32> {
  addresses
    .iter()
    .enumerate()
    .map(|(at, words)| Scored::new(Words::of(words), 1.0 - at as f32 / 10.0))
    .collect()
}

/// The whole walk: every address reads into the key, in order, keeping its own score.
#[test]
fn every_address_reads_into_its_key() {
  let read = keyed::<Engine, Pair>(hits(&[&["m1", "a"], &["m2", "b"]])).expect("both read back");

  assert_eq!(
    read
      .iter()
      .map(Scored::data_ref)
      .cloned()
      .collect::<Vec<_>>(),
    vec![
      Pair {
        media: "m1".to_owned(),
        shot: "a".to_owned()
      },
      Pair {
        media: "m2".to_owned(),
        shot: "b".to_owned()
      },
    ]
  );
  // The SCORE is the engine's own and is carried across untouched — the read is about the address
  // half and touches nothing else.
  assert_eq!(
    read.iter().map(Scored::score).collect::<Vec<_>>(),
    vec![1.0, 0.9]
  );
}

/// An address holding MORE columns than the key reads is [`ColumnReader::finish`]'s refusal, not a
/// silently half-read address — which is the check that moved out of the engine when the seam shed
/// the record, and then onto the read phase when the column language landed.
#[test]
fn an_address_the_key_does_not_finish_is_refused() {
  assert_eq!(
    keyed::<Engine, Single>(hits(&[&["m1", "a"]])),
    Err(Refusal::Trailing)
  );
  // The same addresses, read by the key whose column count matches, are fine — so the refusal is
  // about the PAIRING and not about the addresses.
  assert!(keyed::<Engine, Pair>(hits(&[&["m1", "a"]])).is_ok());
}

/// An address that runs out mid-key is the row's own refusal, raised where the column was read.
#[test]
fn an_address_that_runs_out_is_the_row_s_refusal() {
  assert_eq!(
    keyed::<Engine, Pair>(hits(&[&["m1"]])),
    Err(Refusal::Truncated)
  );
}

/// FAIL-FAST: one unreadable address fails the whole answer rather than shortening it.
///
/// The good hit is FIRST, so a walk that dropped bad addresses instead of refusing would answer with
/// it and be one short — which is exactly the shape that hides a corrupt index.
#[test]
fn one_unreadable_address_fails_the_whole_answer() {
  assert_eq!(
    keyed::<Engine, Pair>(hits(&[&["m1", "a"], &["m2"]])),
    Err(Refusal::Truncated)
  );
}

/// An empty answer is an empty answer — no engine call and no address to read.
#[test]
fn nothing_read_is_nothing_refused() {
  assert_eq!(keyed::<Engine, Pair>(Vec::new()), Ok(Vec::new()));
}

/// The unused face turns the walk too, which is what makes the seam's own shape provable at the
/// poorest engine there is.
#[test]
fn the_unused_face_reads_its_own_empty_address() {
  struct Nothing;

  impl Field for Nothing {
    fn write(&self, _w: &mut impl ColumnWriter) {}

    fn read<R: ColumnReader>(_r: &mut R) -> Result<Self, R::Error> {
      Ok(Self)
    }
  }

  assert_eq!(
    keyed::<(), Nothing>(vec![Scored::new((), ())]).map(|hits| hits.len()),
    Ok(1)
  );
  // And the poorest engine's own refusal is the one the walk hands back.
  let _: Result<Hits<Nothing, ()>, NoColumns> = keyed::<(), Nothing>(Vec::new());
}