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::{
  pin::pin,
  task::{Context, Poll, Waker},
};

use super::{AsyncBlobEngine, AsyncBlobStore, AsyncLocate, Connected};
use crate::{BlobRecord, Identifiable, Transformer};

/// 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 artifact: the compound lineage key `(media, frame)` and a byte payload, with the format
// stated at the TYPE. The shape every blob declaration has.
struct Thumbnail {
  media: u64,
  frame: u32,
  bytes: Vec<u8>,
}

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

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

impl Identifiable for Thumbnail {
  type Id = u32;

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

impl Transformer for Thumbnail {
  type Key = ThumbnailKey;
  type Lineage = ThumbnailLineage;
  type Record = Self;
  // A blob store addresses this record and queries nothing about it: no wire face, so no filter —
  // and no stored column, so no order capability beside this block either.
  type Graphql = ();

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

impl BlobRecord for Thumbnail {
  type Bytes = Vec<u8>;

  fn bytes(&self) -> &Vec<u8> {
    &self.bytes
  }

  fn extension() -> Option<&'static str> {
    Some("png")
  }
}

// A record with no extension, exercising the default — an extensionless artifact family is the
// shape a record that overrides nothing gets.
struct Waveform(Vec<u8>);

impl BlobRecord for Waveform {
  type Bytes = Vec<u8>;

  fn bytes(&self) -> &Vec<u8> {
    &self.0
  }
}

/// The record face: the payload by reference, the format from the TYPE.
///
/// `extension` is reached as `T::extension()` with no value in hand, which is the whole content of
/// its being type-level: a by-key `get` holds no record and must still reconstruct the address a
/// `put` wrote.
#[test]
fn a_blob_record_states_its_bytes_and_its_format() {
  let thumb = Thumbnail {
    media: 7,
    frame: 12,
    bytes: vec![0x89, 0x50],
  };

  assert_eq!(thumb.bytes(), &[0x89, 0x50]);
  assert_eq!(<Thumbnail as BlobRecord>::extension(), Some("png"));
  assert_eq!(<Waveform as BlobRecord>::extension(), None);

  fn format_of<T: BlobRecord>() -> Option<&'static str> {
    T::extension()
  }
  assert_eq!(format_of::<Thumbnail>(), Some("png"));
}

/// The two capabilities are independent: a bound naming [`BlobRecord`] alone reaches the bytes and
/// the format, and a record with no [`Transformer`] address still has both.
#[test]
fn the_payload_face_carries_no_identity() {
  fn bytes_of<T: BlobRecord>(record: &T) -> &T::Bytes {
    record.bytes()
  }

  assert_eq!(bytes_of(&Waveform(vec![1, 2, 3])), &[1, 2, 3]);
}

/// The unused face is a live implementation of the seam, which is what makes the seam's shape
/// provable: every associated type resolves, `put` takes a bare record, and `get` projects the key.
#[test]
fn the_unused_face_answers_the_whole_seam() {
  let thumb = Thumbnail {
    media: 7,
    frame: 12,
    bytes: vec![0x89],
  };

  assert_eq!(
    block_on(AsyncBlobEngine::<Thumbnail>::put(
      &(),
      Connected::new(&(), ()),
      &thumb
    )),
    Ok(())
  );
  assert_eq!(
    block_on(AsyncBlobEngine::<Thumbnail>::get(
      &(),
      Connected::new(&(), ()),
      &thumb.key()
    )),
    Ok(Vec::new())
  );
}

/// `put` is reachable with NO identity bound in scope, and `get` is reachable only with one — the
/// split the trait states by putting `where R: Transformer` on one method and not on the type.
///
/// Written as two generic functions rather than as calls, because a bound is what is being asserted:
/// the first compiles with `R` bounded by nothing at all, which is what "unbounded over `R`" means.
#[test]
fn only_the_read_side_projects_the_key() {
  fn store_anything<R, D>(db: &D, record: &R) -> impl Future<Output = Result<(), D::Error>>
  where
    D: AsyncBlobEngine<R, Connection = (), WriteContext<'static> = ()>,
  {
    db.put(Connected::new(&(), ()), record)
  }

  fn read_by_key<R, D>(db: &D, key: &R::Key) -> impl Future<Output = Result<D::Payload, D::Error>>
  where
    R: Transformer,
    D: AsyncBlobEngine<R, Connection = (), ReadContext<'static> = ()>,
  {
    db.get(Connected::new(&(), ()), key)
  }

  let thumb = Thumbnail {
    media: 1,
    frame: 2,
    bytes: vec![9],
  };
  assert_eq!(
    block_on(store_anything::<Thumbnail, ()>(&(), &thumb)),
    Ok(())
  );
  assert_eq!(
    block_on(read_by_key::<Thumbnail, ()>(&(), &thumb.key())),
    Ok(Vec::new())
  );
}

// A store whose handle is the unused face, standing in for a real backend's two layers: the manager
// is opened once and the handle it mints is stateless, holding only its slot.
struct NullStore {
  root: &'static str,
}

impl AsyncBlobStore for NullStore {
  type Options = &'static str;
  type Error = core::convert::Infallible;
  type Handle = ();

  async fn open(options: Self::Options) -> Result<Self, Self::Error> {
    Ok(Self { root: options })
  }

  fn blob(&self, _slot: impl Into<smol_bytes::Utf8Bytes>) -> Self::Handle {}
}

/// The construction layer: open once, mint per slot. `blob` is sync and infallible, so a caller
/// mints a handle wherever it needs one without threading a `Result` or an await.
#[test]
fn a_store_opens_once_and_mints_per_slot() {
  let store = block_on(NullStore::open("/var/blobs")).expect("the null store opens");

  assert_eq!(store.root, "/var/blobs");
  // A slot is text the caller supplies, so both doors into the crate's one string type reach it.
  store.blob("thumbnail");
  store.blob(String::from("waveform"));
}

/// [`AsyncLocate`] is OPTIONAL, and the unused face declines it — asserted by a bound that resolves for
/// the faces that answer it and by the absence of an impl here. The capability's shape is pinned by
/// implementing it once, on a face that also carries the `AsyncBlobEngine` supertrait it cannot spell without.
#[test]
fn the_address_capability_is_a_separate_opt_in() {
  struct Addressed;

  // The resolution failure, a SEPARATE type from the face's `Error`: under the supertrait a second
  // `type Error` makes every generic `L::Error` use `E0221`-ambiguous.
  #[derive(Debug, PartialEq)]
  struct Unaddressable;

  impl core::fmt::Display for Unaddressable {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
      f.write_str("the key renders no address")
    }
  }

  impl core::error::Error for Unaddressable {}

  impl<R> AsyncBlobEngine<R> for Addressed {
    type Options = ();
    type Error = core::convert::Infallible;
    type Payload = Vec<u8>;
    type Connection = ();
    type ReadContext<'a> = ();
    type WriteContext<'a> = ();

    fn put(
      &self,
      _ctx: Connected<'_, Self::Connection, Self::WriteContext<'_>>,
      _record: &R,
    ) -> impl Future<Output = Result<(), Self::Error>> + Send {
      core::future::ready(Ok(()))
    }

    fn get(
      &self,
      _ctx: Connected<'_, Self::Connection, Self::ReadContext<'_>>,
      _key: &R::Key,
    ) -> impl Future<Output = Result<Self::Payload, Self::Error>> + Send
    where
      R: Transformer,
    {
      core::future::ready(Ok(Vec::new()))
    }

    fn read(
      &self,
      _ctx: Connected<'_, Self::Connection, Self::ReadContext<'_>>,
      _key: &R::Key,
      _suffix: Option<&str>,
    ) -> impl Future<Output = Result<Option<Self::Payload>, Self::Error>> + Send
    where
      R: Transformer,
    {
      core::future::ready(Ok(None))
    }
  }

  // The `Ref` is this face's own choice — a string here, a path or a URL elsewhere — which is the
  // property the trait leaves open. `Location` is the same property one step further out, and this
  // face DECLINES the shipped citizen to prove it is one: `Placed` implements nothing of this
  // crate's and names nothing of this crate's, and it is a perfectly good location.
  #[derive(Debug, PartialEq)]
  struct Placed {
    url: String,
    bucket: &'static str,
  }

  impl<R> AsyncLocate<R> for Addressed {
    type Ref<'a> = String;
    type Location = Placed;
    type LocateError = Unaddressable;

    fn locate<'a>(
      &'a self,
      _ctx: Connected<'a, Self::Connection, Self::ReadContext<'a>>,
      _key: &'a R::Key,
      suffix: Option<&str>,
    ) -> Result<Self::Ref<'a>, Self::LocateError>
    where
      R: Transformer,
    {
      Ok(match suffix {
        Some(suffix) => format!("thumbnail/7/12.{suffix}"),
        None => "thumbnail/7/12".to_owned(),
      })
    }

    fn location<'a>(&'a self, reference: Self::Ref<'a>) -> Result<Placed, Self::LocateError> {
      Ok(Placed {
        url: format!("s3://cards/{reference}"),
        bucket: "cards",
      })
    }
  }

  let key = ThumbnailKey {
    media: 7,
    frame: 12,
  };
  assert_eq!(
    AsyncLocate::<Thumbnail>::locate(&Addressed, Connected::new(&(), ()), &key, Some("png")),
    Ok("thumbnail/7/12.png".to_owned())
  );
  // The suffix is the CALLER's, so the same key under no suffix is a different address — which is
  // what makes the parameter a parameter rather than a decoration.
  assert_eq!(
    AsyncLocate::<Thumbnail>::locate(&Addressed, Connected::new(&(), ()), &key, None),
    Ok("thumbnail/7/12".to_owned())
  );
  assert_eq!(
    AsyncLocate::<Thumbnail>::location(&Addressed, "thumbnail/7/12.png".to_owned()),
    Ok(Placed {
      url: "s3://cards/thumbnail/7/12.png".to_owned(),
      bucket: "cards",
    })
  );
}