reef-core 0.4.0

Provider-neutral primitives for building LLM agents: run lifecycle, transcript, tools, hooks
Documentation
#![cfg(test)]

use super::{Envelope, EnvelopeError, Payload, valid_json};
use crate::redact_tests::{SECRET, assert_redacted, assert_states};
use std::error::Error;

fn payload(bytes: &[u8]) -> Payload {
    Payload::copy_from_slice(bytes)
}

fn nested_json(openers: &[u8]) -> Vec<u8> {
    let mut bytes = Vec::with_capacity(openers.len() * 6 + 1);
    for opener in openers {
        bytes.push(*opener);
        if *opener == b'{' {
            bytes.extend_from_slice(br#""k":"#);
        }
    }
    bytes.push(b'0');
    for opener in openers.iter().rev() {
        bytes.push(if *opener == b'{' { b'}' } else { b']' });
    }
    bytes
}

#[test]
fn payload_preserves_arbitrary_bytes_and_ownership() {
    let source = vec![0, 0xff, b'{'];
    let copied = Payload::copy_from_slice(&source);
    let owned = Payload::from_vec(source);
    assert_eq!(copied.as_bytes(), [0, 0xff, b'{']);
    assert_eq!(owned.into_bytes().as_ref(), [0, 0xff, b'{']);
    assert!(Payload::from_vec(Vec::new()).as_bytes().is_empty());

    let original = payload(b"raw");
    let clone = original.clone();
    let mut transferred = original.into_bytes();
    transferred[0] = b'X';
    assert_eq!(clone.as_bytes(), b"raw");
}

#[test]
fn envelope_accepts_every_json_top_level_and_preserves_bytes() {
    let values: [&[u8]; 12] = [
        br#"{"a":[1,-2.5e+3,true,false,null]}"#,
        br#"[]"#,
        br#"{}"#,
        br#""text""#,
        br#""escapes: \"\\\/\b\f\n\r\t\u00af""#,
        "\"λ\"".as_bytes(),
        b"0",
        b"-0",
        b"12",
        b"1.25",
        b"6E-2",
        b" true \n",
    ];

    for bytes in values {
        let envelope = Envelope::try_new("example/provider".into(), "fact".into(), payload(bytes))
            .expect("valid JSON");
        assert_eq!(envelope.namespace(), "example/provider");
        assert_eq!(envelope.kind(), "fact");
        assert_eq!(envelope.data().as_bytes(), bytes);

        let clone = envelope.clone();
        let (namespace, kind, data) = envelope.into_parts();
        assert_eq!(
            (namespace.as_str(), kind.as_str()),
            ("example/provider", "fact")
        );
        assert_eq!(data.as_bytes(), bytes);
        assert_eq!(clone.data().as_bytes(), bytes);
    }
}

#[test]
fn quoted_invalid_utf8_stays_inside_the_syntax_boundary() {
    let values: &[&[u8]] = &[
        &[b'"', 0xff, b'"'],
        &[b'"', 0xc0, 0xaf, b'"'],
        &[b'[', b'"', 0xe2, 0x82, b'"', b']'],
    ];

    for bytes in values {
        assert!(valid_json(bytes), "rejected quoted bytes {bytes:?}");
        let envelope = Envelope::try_new("ns".into(), "k".into(), payload(bytes))
            .expect("the syntax boundary accepts quoted invalid UTF-8 bytes");
        assert_eq!(envelope.data().as_bytes(), *bytes);
    }
}

#[test]
fn envelope_reports_each_stable_shape_error() {
    let cases = [
        (
            Envelope::try_new(String::new(), "k".into(), payload(b"{}")),
            EnvelopeError::EmptyNamespace,
            "opaque envelope namespace is empty",
        ),
        (
            Envelope::try_new("ns".into(), String::new(), payload(b"{}")),
            EnvelopeError::EmptyKind,
            "opaque envelope kind is empty",
        ),
        (
            Envelope::try_new("ns".into(), "k".into(), payload(b"")),
            EnvelopeError::EmptyData,
            "opaque envelope data is empty",
        ),
        (
            Envelope::try_new("ns".into(), "k".into(), payload(b"{")),
            EnvelopeError::InvalidJson,
            "opaque envelope data is not valid JSON",
        ),
    ];

    for (result, expected, message) in cases {
        let error = match result {
            Ok(_) => panic!("invalid envelope was accepted"),
            Err(error) => error,
        };
        assert_eq!(error, expected);
        assert_eq!(error.to_string(), message);
        assert!(error.source().is_none());
    }
}

#[test]
fn malformed_json_corpus_is_rejected() {
    let invalid: &[&[u8]] = &[
        b"",
        b" ",
        b"x",
        b"tru",
        b"fals",
        b"nul",
        b"true false",
        b"[",
        b"[1",
        b"[1,]",
        b"[1 2]",
        b"[1:2]",
        b"{",
        b"{]",
        b"{\"a\"}",
        b"{\"a\":}",
        b"{\"a\":1,}",
        b"{\"a\":1 \"b\":2}",
        b"{1:2}",
        b"\"",
        b"\"\\",
        b"\"\\x\"",
        b"\"\\u0\"",
        b"\"\\u00xz\"",
        b"\"line\nfeed\"",
        b"-",
        b"01",
        b"1.",
        b"1e",
        b"1e+",
        b"--1",
        &[0xff],
    ];

    for bytes in invalid {
        assert!(!valid_json(bytes), "accepted {bytes:?}");
    }
}

#[test]
fn iterative_validator_holds_max_json_depth_without_recursion() {
    let arrays = vec![b'['; 10_000];
    let objects = vec![b'{'; 10_000];
    let mixed: Vec<u8> = (0..10_000)
        .map(|depth| if depth % 2 == 0 { b'[' } else { b'{' })
        .collect();

    assert!(valid_json(&nested_json(&arrays)));
    assert!(valid_json(&nested_json(&objects)));
    assert!(valid_json(&nested_json(&mixed)));

    let mut too_deep_arrays = arrays;
    too_deep_arrays.push(b'[');
    let mut too_deep_mixed = mixed;
    too_deep_mixed.push(b'[');
    assert!(!valid_json(&nested_json(&too_deep_arrays)));
    assert!(!valid_json(&nested_json(&too_deep_mixed)));
}

#[test]
fn payload_debug_states_a_size_and_never_a_byte() {
    let secret = payload(SECRET.as_bytes());
    assert_redacted(&secret);
    assert_eq!(format!("{secret:?}"), "<21 bytes>");
    assert_eq!(format!("{:?}", payload(b"")), "<0 bytes>");
}

#[test]
fn envelope_debug_routes_in_full_and_sizes_the_payload() {
    // The namespace and kind are the routing key a hook matches on, so a
    // rendering that hid them would be useless; only `data` is provider content.
    let envelope = Envelope::try_new(
        "example.compat".into(),
        "matrix".into(),
        Payload::copy_from_slice(format!(r#"{{"token":"{SECRET}"}}"#).as_bytes()),
    )
    .expect("fixture is valid JSON");
    assert_redacted(&envelope);
    assert_states(
        &envelope,
        &[
            r#"namespace: "example.compat""#,
            r#"kind: "matrix""#,
            "data: <33 bytes>",
        ],
    );
}

#[test]
fn payload_equality_is_byte_wise_and_reflexive() {
    let bytes = payload(b"\x00\xffraw");
    assert_eq!(bytes, bytes.clone());
    assert_eq!(bytes, Payload::from_vec(vec![0, 0xff, b'r', b'a', b'w']));
    assert_ne!(bytes, payload(b"\x00\xffRAW"));
    // Length alone is not it, in either direction.
    assert_ne!(bytes, payload(b"\x00\xffra"));
    assert_eq!(payload(b""), payload(b""));
}

#[test]
fn envelope_equality_compares_bytes_rather_than_the_json_they_spell() {
    let envelope = |namespace: &str, kind: &str, data: &[u8]| {
        Envelope::try_new(
            namespace.into(),
            kind.into(),
            Payload::copy_from_slice(data),
        )
        .expect("every fixture here is valid JSON")
    };
    let subject = envelope("example.compat", "matrix", br#"{"a":1}"#);

    assert_eq!(subject, subject.clone());
    assert_ne!(subject, envelope("example.other", "matrix", br#"{"a":1}"#));
    assert_ne!(subject, envelope("example.compat", "other", br#"{"a":1}"#));
    assert_ne!(subject, envelope("example.compat", "matrix", br#"{"a":2}"#));

    // The decision this pins: two payloads a provider would read as the same
    // value are two different envelopes, because reading them as one would mean
    // core interpreting the channel it exists in order not to interpret.
    assert_ne!(
        subject,
        envelope("example.compat", "matrix", br#"{ "a" : 1 }"#)
    );
    assert_ne!(
        subject,
        envelope("example.compat", "matrix", br#"{"a":1.0}"#)
    );
}

/// What the `serde` feature adds to this module, and what it refuses.
#[cfg(feature = "serde")]
mod serde_format {
    use super::{Envelope, Payload, payload};
    use crate::wire::wire_tests::{assert_expecting, assert_refusal, encode, round_trip};

    const ENVELOPE_JSON: &str = r#"{"namespace":"provider","kind":"segment","data":[123,125]}"#;

    fn envelope() -> Envelope {
        Envelope::try_new("provider".into(), "segment".into(), payload(b"{}"))
            .expect("the fixture is valid JSON")
    }

    #[test]
    fn a_payload_keeps_bytes_no_json_writer_would_choose() {
        let original = payload(&[0, 0xff, b'{']);
        assert_eq!(encode(&original), "[0,255,123]");
        assert_eq!(round_trip(&original).as_bytes(), [0, 0xff, b'{']);
        assert!(
            round_trip(&Payload::from_vec(Vec::new()))
                .as_bytes()
                .is_empty()
        );
    }

    #[test]
    fn an_envelope_reads_from_both_the_map_and_the_sequence_form() {
        assert_eq!(encode(&envelope()), ENVELOPE_JSON);
        assert_eq!(encode(&round_trip(&envelope())), ENVELOPE_JSON);

        let from_sequence: Envelope = serde_json::from_str(r#"["provider","segment",[123,125]]"#)
            .expect("a compact format writes a struct as its fields in order");
        assert_eq!(encode(&from_sequence), ENVELOPE_JSON);
    }

    /// A session file is untrusted input, so ingress re-runs the constructor.
    #[test]
    fn reading_an_envelope_re_runs_the_validator_the_call_site_gets() {
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"","kind":"k","data":[123,125]}"#),
            "namespace is empty",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"n","kind":"","data":[123,125]}"#),
            "kind is empty",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"n","kind":"k","data":[]}"#),
            "data is empty",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"n","kind":"k","data":[123]}"#),
            "not valid JSON",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"["n","k",[123]]"#),
            "not valid JSON",
        );
    }

    #[test]
    fn an_envelope_refuses_an_unknown_repeated_missing_or_mistyped_document() {
        assert_refusal(
            serde_json::from_str::<Envelope>(
                r#"{"namespace":"n","kind":"k","data":[123,125],"extra":1}"#,
            ),
            "unknown field `extra`",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"n","kind":"k","kind":"k"}"#),
            "duplicate field `kind`",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"{"namespace":"n","kind":"k"}"#),
            "missing field `data`",
        );
        assert_refusal(
            serde_json::from_str::<Envelope>(r#"["n"]"#),
            "every struct field",
        );
        assert_expecting::<Envelope>("an opaque envelope");
    }
}