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 ROAD's own claims: the citizen is the RESOURCE, the mint carries the ELECTION's corpus name,
//! the manager comes back beside the handle, and an uninstalled resource refuses with a sentence a
//! deployment can act on.
//!
//! Beside the module rather than inside it, on this crate's directory-module precedent. What is
//! proved here is the road alone — no declaration, no emission — because the shape it takes is
//! answerable without either, and the round that emits resolvers over it should not be the first
//! place a `Send` bound or a missing-citizen sentence is exercised.
use crate::Resources;

use std::sync::{
  Arc,
  atomic::{AtomicUsize, Ordering},
};

use async_graphql::{EmptyMutation, EmptySubscription, Object, Schema};

use super::{search_slot, vector_slot};
use crate::{
  AsyncResource, NoColumns, Shared, SlotName,
  store::{FulltextEngine, FulltextMount, SlotHandle},
};

/// A declaration's stand-in — the brand a corpus is minted under, which never has a value.
struct Shots;

/// A second one, so the CLAIM about routing has two names to tell apart.
struct Subs;

/// The two elections' corpora, spelled as a declaration's emission would mint them.
const TITLE: &SlotName = SlotName::new("shots__title__lexical");
const BODY: &SlotName = SlotName::new("shots__body__lexical");

/// A per-slot HANDLE that remembers which corpus it was minted for — the fact the mint has to carry
/// and the brand deliberately does not prove.
#[derive(Clone, Debug, PartialEq, Eq)]
struct Corpus {
  slot: String,
}

impl FulltextEngine for Corpus {
  type Options = ();
  type SearchOptions = ();
  type Error = NoColumns;
  type Score = f32;
  type Address = ();
  /// The MANAGER, which is what makes this fixture worth writing: a handle whose connection is a
  /// real type is exactly the shape the old road could not serve, because `Connected::new(&(), ())`
  /// was the only pair a resolver could build.
  type Connection = Manager;
  type WriteBuffer = ();
  type ReadBuffer = ();

  fn buffer() -> Self::WriteBuffer {}
  fn finalize(_buf: Self::WriteBuffer) -> Self::Address {}
  fn open(_address: Self::Address) -> Self::ReadBuffer {}
}

/// The connection-manager a mount holds and lends.
#[derive(Debug)]
struct Manager {
  opened: &'static str,
}

/// A MOUNT of an application's own — the openness half, and the shape a blanket impl could not have
/// left room for: the store is held behind this type's own field and the corpus is minted from it.
struct Ft {
  manager: Manager,
  minted: Arc<AtomicUsize>,
}

impl AsyncResource for Ft {
  type Options = &'static str;
  type Error = core::convert::Infallible;

  fn build(
    _ctx: &Resources,
    options: Self::Options,
  ) -> impl core::future::Future<Output = Result<Self, Self::Error>> + Send {
    core::future::ready(Ok(Self {
      manager: Manager { opened: options },
      minted: Arc::new(AtomicUsize::new(0)),
    }))
  }
}

impl FulltextMount for Ft {
  type Handle = Corpus;

  fn corpus(&self, slot: impl Into<smol_bytes::Utf8Bytes>) -> Self::Handle {
    self.minted.fetch_add(1, Ordering::Relaxed);
    Corpus {
      slot: slot.into().to_string(),
    }
  }

  fn connection(&self) -> &Manager {
    &self.manager
  }
}

/// A SECOND mount, so the routing claim has two resources to tell apart — and, one family over, the
/// VECTOR mount the twin road is proved against.
struct Other {
  manager: Manager,
}

impl AsyncResource for Other {
  type Options = ();
  type Error = core::convert::Infallible;

  fn build(
    _ctx: &Resources,
    _options: Self::Options,
  ) -> impl core::future::Future<Output = Result<Self, Self::Error>> + Send {
    core::future::ready(Ok(Self {
      manager: Manager { opened: "other" },
    }))
  }
}

fn mounted() -> Shared<Ft> {
  Shared::new(Ft {
    manager: Manager { opened: "root" },
    minted: Arc::new(AtomicUsize::new(0)),
  })
}

struct Query;

#[Object]
impl Query {
  /// A resolver in the shape every emitted one takes: look the RESOURCE up, take the corpus and the
  /// manager out of ONE lookup, own the handle across the `await` — which is the `Send` claim this
  /// file exists to make.
  async fn searched(&self, ctx: &async_graphql::Context<'_>) -> async_graphql::Result<String> {
    let (mut slot, connection) = search_slot::<Ft, Shots>(ctx, "searched", TITLE)?;
    let handle: &mut SlotHandle<Corpus, Shots> = &mut slot;
    let held = core::future::ready(handle.engine().slot.clone()).await;
    Ok(format!("{held}@{}", connection.opened))
  }

  /// The SECOND election of the SAME mount, which is what makes two corpora out of one resource.
  async fn other(&self, ctx: &async_graphql::Context<'_>) -> async_graphql::Result<String> {
    let (slot, _) = search_slot::<Ft, Shots>(ctx, "other", BODY)?;
    Ok(slot.engine().slot.clone())
  }
}

fn schema(installed: bool) -> Schema<Query, EmptyMutation, EmptySubscription> {
  let builder = Schema::build(Query, EmptyMutation, EmptySubscription);
  let builder = if installed {
    builder.data(mounted())
  } else {
    builder
  };
  builder.finish()
}

/// **THE MINT HANDS OUT A HANDLE AN EXCLUSIVE BORROW CAN BE TAKEN OF**, which is the whole reason
/// the road hands back an owned handle rather than lending one.
///
/// The `&mut` is the assertion: `SlotHandle`'s read verbs take one and `Context::data` lends `&T`.
#[tokio::test]
async fn a_read_owns_the_handle_it_was_minted() {
  let answered = schema(true).execute("{ searched }").await;
  assert!(answered.errors.is_empty(), "{:?}", answered.errors);
  assert_eq!(
    answered.data.to_string(),
    "{searched: \"shots__title__lexical@root\"}",
    "the resolver did not reach its corpus, or did not reach its manager",
  );
}

/// **THE CONNECTION COMES BACK BESIDE THE HANDLE**, which is the half of the read a resolver could
/// not build for itself.
///
/// The answer above carries both — the corpus name the mint was given and the manager the mount
/// lent — out of ONE lookup, which is what stops a handle and a connection coming from two mounts.
#[test]
fn one_lookup_answers_with_the_corpus_and_the_manager() {
  let ft = Ft {
    manager: Manager { opened: "root" },
    minted: Arc::new(AtomicUsize::new(0)),
  };
  let handle = FulltextMount::corpus(&ft, TITLE.as_ref());
  assert_eq!(handle.slot, "shots__title__lexical");
  assert_eq!(FulltextMount::connection(&ft).opened, "root");
}

/// **ONE MOUNT HOLDS A CORPUS PER ELECTION.** The mint takes the election's own durable name, so two
/// elections pointing at one resource are two corpora — which is where BM25's index-wide statistics
/// stay in two universes.
#[tokio::test]
async fn one_mount_holds_a_corpus_per_election() {
  let answered = schema(true).execute("{ searched other }").await;
  assert!(answered.errors.is_empty(), "{:?}", answered.errors);
  let answer = answered.data.to_string();
  assert!(answer.contains("shots__title__lexical"), "{answer}");
  assert!(answer.contains("shots__body__lexical"), "{answer}");
}

/// **EACH READ MINTS ITS OWN**, so two concurrent resolvers never contend and no lock is taken.
#[test]
fn each_read_mints_its_own_corpus() {
  let minted = Arc::new(AtomicUsize::new(0));
  let ft = Ft {
    manager: Manager { opened: "root" },
    minted: Arc::clone(&minted),
  };
  let mut one = SlotHandle::<_, Shots>::mint(FulltextMount::corpus(&ft, TITLE.as_ref()));
  let mut two = SlotHandle::<_, Shots>::mint(FulltextMount::corpus(&ft, TITLE.as_ref()));
  let _: (
    &mut SlotHandle<Corpus, Shots>,
    &mut SlotHandle<Corpus, Shots>,
  ) = (&mut one, &mut two);
  assert_eq!(minted.load(Ordering::Relaxed), 2);
}

/// **AN UNINSTALLED RESOURCE REFUSES WITH THE `.data(…)` LINE THE DEPLOYMENT IS MISSING** — the three
/// facts that turn *a citizen is missing* into *this line is missing*: the field, the corpus and the
/// resource.
#[tokio::test]
async fn a_missing_resource_names_the_field_the_corpus_and_the_resource() {
  let answered = schema(false).execute("{ searched }").await;
  let refusal = answered
    .errors
    .first()
    .map(|refusal| refusal.message.clone())
    .expect("an uninstalled resource refuses");

  assert!(refusal.contains("`searched`"), "{refusal}");
  assert!(refusal.contains("shots__title__lexical"), "{refusal}");
  assert!(refusal.contains("Ft"), "{refusal}");
  assert!(refusal.contains("Shared::<"), "{refusal}");
}

/// **THE RESOURCE IS THE ROUTING.** Two resources of ONE KIND are two TYPES, so a lookup for one is
/// not answered by the other — which is what the retired per-(engine × declaration) door key bought
/// and what the resource axis buys for free.
#[test]
fn two_resources_of_one_kind_are_two_citizens() {
  use core::any::TypeId;

  assert_ne!(
    TypeId::of::<Shared<Ft>>(),
    TypeId::of::<Shared<Other>>(),
    "two resources shared one context key",
  );
}

/// **THE BRAND STILL SEPARATES DECLARATIONS.** The citizen is the resource now, and the DECLARATION
/// rides the handle's type — so a corpus branded for one declaration cannot be handed to another's
/// door.
#[test]
fn the_brand_still_names_the_declaration() {
  use core::any::TypeId;

  assert_ne!(
    TypeId::of::<SlotHandle<Corpus, Shots>>(),
    TypeId::of::<SlotHandle<Corpus, Subs>>(),
    "two declarations shared one brand",
  );
}

/// A TOY VECTOR ENGINE, remembering the corpus AND the width it was minted at — nothing in this
/// tree implements a vector backend, so the vector half of the road is proved against one written
/// here.
#[derive(Clone, Debug, PartialEq, Eq)]
struct Coordinates {
  slot: String,
  dim: usize,
}

impl crate::store::VectorEngine for Coordinates {
  type Options = ();
  type SearchOptions = ();
  type Error = NoColumns;
  type Score = f32;
  type Element = f32;
  type Address = ();
  type Connection = Manager;
  type WriteBuffer = ();
  type ReadBuffer = ();

  fn buffer() -> Self::WriteBuffer {}
  fn finalize(_buf: Self::WriteBuffer) -> Self::Address {}
  fn open(_address: Self::Address) -> Self::ReadBuffer {}
}

impl crate::store::VectorMount for Other {
  type Handle = Coordinates;

  fn corpus(&self, slot: impl Into<smol_bytes::Utf8Bytes>, dim: usize) -> Self::Handle {
    Coordinates {
      slot: slot.into().to_string(),
      dim,
    }
  }

  fn connection(&self) -> &Manager {
    &self.manager
  }
}

/// **THE VECTOR TWIN IS THE SAME ROAD**, and its one extra parameter is the width the two mount
/// seams differ by — carried to the mint, where a corpus's storage cannot be shaped without it.
#[tokio::test]
async fn the_vector_twin_carries_the_width_to_the_mint() {
  struct VQuery;

  #[Object]
  impl VQuery {
    async fn near(&self, ctx: &async_graphql::Context<'_>) -> async_graphql::Result<String> {
      let (slot, connection) = vector_slot::<Other, Shots>(ctx, "near", BODY, 768)?;
      Ok(format!(
        "{}/{}@{}",
        slot.engine().slot,
        slot.engine().dim,
        connection.opened
      ))
    }
  }

  let answered = Schema::build(VQuery, EmptyMutation, EmptySubscription)
    .data(Shared::new(Other {
      manager: Manager { opened: "lance" },
    }))
    .finish()
    .execute("{ near }")
    .await;
  assert!(answered.errors.is_empty(), "{:?}", answered.errors);
  assert_eq!(
    answered.data.to_string(),
    "{near: \"shots__body__lexical/768@lance\"}",
  );
}