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 opaque spelling, in both directions.
//!
//! The vectors are RFC 4648's own, in the §5 alphabet and with the padding dropped, so this is
//! checked against the standard rather than against itself. The refusals are the half a lenient
//! decoder gets wrong: every one of them is a SECOND spelling of a cursor that already has one, and
//! two spellings of one cursor are two cache keys, two log lines and two chances for a comparison
//! over the text to say no.

use super::{decode, encode};

/// RFC 4648 §10's test vectors, with the padding dropped — which is what makes the group lengths
/// 2, 3 and 4 all appear.
const VECTORS: [(&str, &str); 7] = [
  ("", ""),
  ("f", "Zg"),
  ("fo", "Zm8"),
  ("foo", "Zm9v"),
  ("foob", "Zm9vYg"),
  ("fooba", "Zm9vYmE"),
  ("foobar", "Zm9vYmFy"),
];

#[test]
fn the_encoding_is_rfc_4648_base64url_without_padding() {
  for (plain, encoded) in VECTORS {
    assert_eq!(encode(plain.as_bytes()), encoded, "encoding {plain:?}");
    assert_eq!(
      decode(encoded).as_deref(),
      Some(plain.as_bytes()),
      "decoding {encoded:?}"
    );
  }
}

/// The §5 alphabet, which is the whole reason this is base64url and not base64: `-` and `_` where
/// §4 has `+` and `/`, so a cursor is a URL query parameter with nothing to escape.
///
/// `0xfb 0xff` is the byte pair that reaches both symbols.
#[test]
fn the_two_symbols_that_make_it_url_safe_are_the_url_safe_ones() {
  assert_eq!(encode(&[0xfb, 0xff, 0xbf]), "-_-_");
  assert_eq!(decode("-_-_"), Some(vec![0xfb, 0xff, 0xbf]));
  assert_eq!(decode("+/+/"), None, "the §4 alphabet is not this one");
}

/// Every byte value round-trips, at every offset within a group — the property a cursor's frame
/// rests on, since the frame holds arbitrary bytes rather than text.
#[test]
fn every_byte_round_trips_at_every_alignment() {
  for lead in 0..3usize {
    let mut bytes = vec![0xa5; lead];
    bytes.extend(0..=255u8);
    assert_eq!(decode(&encode(&bytes)).as_deref(), Some(bytes.as_slice()));
  }
}

/// Padding is REFUSED rather than skipped. The encoder never writes it, so accepting it would make
/// `Zg` and `Zg==` two spellings of one cursor.
#[test]
fn padding_is_refused() {
  assert_eq!(decode("Zg=="), None);
  assert_eq!(decode("Zm8="), None);
}

/// A trailing group of ONE symbol carries six bits, which is not a byte — no encoding of any byte
/// string produces it, so a decoder that dropped them would accept a string the encoder cannot
/// have written.
#[test]
fn a_trailing_group_of_one_symbol_is_refused() {
  assert_eq!(decode("Z"), None);
  assert_eq!(decode("Zm9vZ"), None);
}

/// The bits a final group carries beyond whole bytes belong to no byte, so they must be zero. This
/// is the refusal a lenient decoder is most likely to skip, and it is the one that admits the most
/// second spellings: `Zg` and every one of `Zh` … `Zv` would otherwise all decode to `f`.
#[test]
fn a_final_group_whose_spare_bits_are_set_is_refused() {
  assert_eq!(decode("Zg"), Some(b"f".to_vec()));
  for spelling in ["Zh", "Zi", "Zv"] {
    assert_eq!(
      decode(spelling),
      None,
      "{spelling} is a second spelling of `f`"
    );
  }
  // Three symbols carry two spare bits, and the same argument applies to them.
  assert_eq!(decode("Zm8"), Some(b"fo".to_vec()));
  assert_eq!(decode("Zm9"), None);
}

/// A symbol outside the alphabet is refused wherever it sits, including the whitespace and the line
/// breaks a MIME-flavoured decoder would skip.
#[test]
fn a_symbol_outside_the_alphabet_is_refused() {
  for spelling in ["Zm9v!", "Zm 9v", "Zm9v\n", "Zm9v.Zm9v"] {
    assert_eq!(decode(spelling), None, "{spelling:?}");
  }
}