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 rows [`codec_citizen`](super::codec_citizen) writes for all three at once, asserted once for
//! all three: the DOCUMENT form, the DOCUMENT READ, and the KEYSET POSITION.
//!
//! Every other row the macro emits is about ONE type's grammar and is asserted in that type's own
//! file — the door, the fold, the roster. These are about the SHAPE the three share, and a shape
//! asserted three times is three places for one claim to drift. It is
//! [`lang::tests`](crate::primitives::lang)'s own division, over this house.
//!
//! The bind and the SQL decode are not here for that file's reason: a bind renders SQL, so what
//! proves it is an engine taking the statement, which `tests/codec_citizen.rs` is. A BSON value is a
//! value and needs no engine to be looked at, which is what makes the MONGO read assertable here
//! beside the write it mirrors.

use super::{AudioCodec, SubtitleCodec, VideoCodec};

/// **A CODEC CARRIES AS BSON's `String`, HOLDING THE CANONICAL SLUG** — the same text the `TEXT`
/// column binds and the same bytes the cursor writes.
///
/// The fold is the half that matters at a boundary: a muxer's `H264` and a probe's `h264` reach a
/// document as the one string a query built from either compares against, because both sides
/// canonicalised before they met.
#[cfg(feature = "mongo")]
#[test]
fn a_codec_carries_as_the_canonical_slug() {
  use bson::Bson;

  use crate::MongoCarrier;

  assert_eq!(
    VideoCodec::new("h264").to_bson(),
    Bson::String(String::from("h264"))
  );
  assert_eq!(
    AudioCodec::new("aac").to_bson(),
    Bson::String(String::from("aac"))
  );
  assert_eq!(
    SubtitleCodec::new("subrip").to_bson(),
    Bson::String(String::from("subrip"))
  );

  for (sent, canonical) in [("H264", "h264"), ("H264", "h264"), ("AV1", "av1")] {
    assert_eq!(
      VideoCodec::new(sent).to_bson(),
      VideoCodec::new(canonical).to_bson(),
      "`{sent}` and `{canonical}` reach one document",
    );
  }

  // An UNREGISTERED name carries too, and losslessly — the open vocabulary reaching the document
  // layer intact, which is the property a numeric road could not have offered it.
  assert_eq!(
    VideoCodec::new("some_codec_9000").to_bson(),
    Bson::String(String::from("some_codec_9000")),
  );
}

/// **THE READ IS THE WRITE'S MIRROR** — a codec written through [`MongoCarrier`](crate::MongoCarrier)
/// reads back through [`MongoExtract`](crate::query::mongo::MongoExtract) as the same value, for all
/// three at once.
#[cfg(feature = "mongo")]
#[test]
fn a_codec_reads_back_the_document_it_carried_as() {
  use crate::{MongoCarrier, query::mongo::MongoExtract};

  for sent in ["h264", "H264", "av1", "some_codec_9000", ""] {
    let codec = VideoCodec::new(sent);
    let written = codec.to_bson();
    assert_eq!(VideoCodec::extract(Some(&written)), Ok(codec), "`{sent}`");
  }

  for sent in ["aac", "OPUS", "flac"] {
    let codec = AudioCodec::new(sent);
    let written = codec.to_bson();
    assert_eq!(AudioCodec::extract(Some(&written)), Ok(codec), "`{sent}`");
  }

  for sent in ["subrip", "ASS", "dvb_subtitle"] {
    let codec = SubtitleCodec::new(sent);
    let written = codec.to_bson();
    assert_eq!(
      SubtitleCodec::extract(Some(&written)),
      Ok(codec),
      "`{sent}`"
    );
  }
}

/// **A HAND-WRITTEN DOCUMENT FOLDS AT THE READ DOOR TOO** — the canonicalisation is the READ's and
/// not only the write's, so a document some other writer produced comes back as the value this
/// crate would have written.
#[cfg(feature = "mongo")]
#[test]
fn a_hand_written_document_folds_at_the_read_door() {
  use bson::Bson;

  use crate::query::mongo::MongoExtract;

  assert_eq!(
    VideoCodec::extract(Some(&Bson::String(String::from("H264")))),
    Ok(VideoCodec::new("h264")),
    "a document written in the wrong case reads back canonical",
  );

  // And a string naming no codec is a VALUE rather than a refusal, which is where this house parts
  // from the subtag one: there is no `Range` arm on this read because there is nothing to range
  // over.
  assert_eq!(
    VideoCodec::extract(Some(&Bson::String(String::from("!!!")))),
    Ok(VideoCodec::new("!!!")),
  );
}

/// **THE REFUSAL NAMES ABSENCE AND THE WRONG TYPE, AND NOTHING ELSE** — the two-thirds of the
/// register's three-way vocabulary this house can still answer with.
#[cfg(feature = "mongo")]
#[test]
fn a_codec_read_refuses_absence_and_the_wrong_type_by_name() {
  use bson::Bson;

  use crate::query::mongo::{MongoExtract, MongoTypeError};

  assert_eq!(VideoCodec::extract(None), Err(MongoTypeError::Absent));
  assert_eq!(AudioCodec::extract(None), Err(MongoTypeError::Absent));
  assert_eq!(SubtitleCodec::extract(None), Err(MongoTypeError::Absent));

  // A wrong BSON type still says WHICH type arrived, that half of the refusal costing nothing to
  // keep precise.
  let refused = VideoCodec::extract(Some(&Bson::Int32(7)));
  assert!(
    matches!(refused, Err(MongoTypeError::Type { .. })),
    "a number where a codec belongs is a TYPE refusal, got {refused:?}",
  );

  assert!(matches!(
    VideoCodec::extract(Some(&Bson::Boolean(true))),
    Err(MongoTypeError::Type { .. })
  ));
}

/// **THE KEYSET POSITION IS THE CANONICAL SLUG's UTF-8**, and it reads back as the value it was
/// written from.
///
/// The read CANONICALISES rather than validating, this vocabulary having no spelling to refuse — so
/// what a forged cursor can still fail on is bytes that are not UTF-8 at all, which is the last
/// assertion here.
#[test]
fn the_cursor_position_is_the_slug_and_round_trips() {
  use crate::CursorValue;

  for sent in ["h264", "H264", "some_codec_9000", ""] {
    let codec = VideoCodec::new(sent);

    let mut written = Vec::new();
    codec.write_cursor(&mut written);

    assert_eq!(
      written,
      codec.as_str().as_bytes(),
      "`{sent}` writes its canonical slug and nothing around it",
    );
    assert_eq!(
      VideoCodec::read_cursor(&written),
      Some(codec),
      "`{sent}` reads back as itself",
    );
  }

  // The order the cursor pages in is the order the type walks, which is what keeps a keyset page
  // from skipping a row.
  let mut written = Vec::new();
  VideoCodec::new("av1").write_cursor(&mut written);
  let mut later = Vec::new();
  VideoCodec::new("h264").write_cursor(&mut later);
  assert!(
    written < later,
    "the cursor bytes carry the type's own order"
  );

  // NOT UTF-8 — the one refusal a forged position can still earn here.
  assert_eq!(VideoCodec::read_cursor(&[0xff, 0xfe]), None);
  assert_eq!(AudioCodec::read_cursor(&[0xff, 0xfe]), None);
  assert_eq!(SubtitleCodec::read_cursor(&[0xff, 0xfe]), None);
}

/// **A CURSOR READ CANONICALISES**, so a client that hands back a position in the wrong case gets
/// the row it was paging from rather than one that does not exist.
#[test]
fn a_cursor_read_canonicalises() {
  use crate::CursorValue;

  assert_eq!(
    VideoCodec::read_cursor(b"H264"),
    Some(VideoCodec::new("h264")),
  );
}