Skip to main content

reef_core/
opaque.rs

1//! Owned provider-extension payloads and validated envelopes.
2
3use std::error::Error;
4use std::fmt::{self, Debug, Display, Formatter};
5
6use crate::redact::Bytes;
7
8/// An owned sequence of uninterpreted bytes.
9///
10/// # Equality
11///
12/// Two payloads are equal when they carry the same bytes in the same order, and
13/// that is the whole of it. Nothing here is normalized, unescaped or parsed
14/// before the comparison, because core never parsed these bytes in the first
15/// place: two payloads that a provider would read as the same value are unequal
16/// whenever their bytes differ. The relation is total, so this is an
17/// [`Eq`], and a payload's length is public through
18/// [`as_bytes`](Payload::as_bytes) — equality says nothing that was not already
19/// observable.
20#[derive(Clone, Eq, PartialEq)]
21pub struct Payload(Box<[u8]>);
22
23impl Debug for Payload {
24    /// States how many bytes arrived, never which ones.
25    ///
26    /// These bytes are provider content that reef never parsed, so a size is
27    /// the most a formatter can say about them and is also the fact worth
28    /// saying: "the provider sent an empty compat blob" is a real bug report.
29    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
30        Bytes(self.0.len()).fmt(formatter)
31    }
32}
33
34impl Payload {
35    /// Takes ownership of a byte vector without parsing it.
36    #[must_use]
37    pub fn from_vec(bytes: Vec<u8>) -> Self {
38        Self(bytes.into_boxed_slice())
39    }
40
41    /// Copies an arbitrary byte slice without parsing it.
42    #[must_use]
43    pub fn copy_from_slice(bytes: &[u8]) -> Self {
44        Self(Box::from(bytes))
45    }
46
47    /// Borrows the exact payload bytes.
48    #[must_use]
49    pub fn as_bytes(&self) -> &[u8] {
50        &self.0
51    }
52
53    /// Transfers ownership of the exact payload bytes.
54    #[must_use]
55    pub fn into_bytes(self) -> Box<[u8]> {
56        self.0
57    }
58}
59
60/// A validated, namespaced provider-extension payload.
61///
62/// `namespace` and `kind` print in full: they are the routing key a hook
63/// matches on, and a rendering that hid them would be useless. `data` inherits
64/// [`Payload`]'s size-only rendering.
65///
66/// # Equality
67///
68/// Field by field: same namespace, same kind, and a [`Payload`] equal by the
69/// byte-wise rule that type documents. Validation accepts the payload without
70/// normalizing it, so equality is **not** JSON equality — `{"a":1}` and
71/// `{ "a" : 1 }` are both valid, mean the same thing to whoever wrote them, and
72/// are two different envelopes here. Reading them as one would require core to
73/// own a JSON value model, decide key order, duplicate keys and number
74/// normalization, and thereby interpret the channel it exists in order not to
75/// interpret.
76///
77/// ```
78/// use reef_core::opaque;
79///
80/// let envelope = |data: &[u8]| {
81///     opaque::Envelope::try_new(
82///         "example.compat".to_owned(),
83///         "matrix".to_owned(),
84///         opaque::Payload::copy_from_slice(data),
85///     )
86///     .unwrap()
87/// };
88///
89/// assert_eq!(envelope(br#"{"a":1}"#), envelope(br#"{"a":1}"#));
90/// // Same JSON to a provider; different bytes, so a different envelope.
91/// assert_ne!(envelope(br#"{"a":1}"#), envelope(br#"{ "a" : 1 }"#));
92/// ```
93#[derive(Clone, Debug, Eq, PartialEq)]
94pub struct Envelope {
95    namespace: String,
96    kind: String,
97    data: Payload,
98}
99
100/// A stable envelope-shape validation error.
101#[derive(Clone, Copy, Debug, Eq, PartialEq)]
102#[non_exhaustive]
103pub enum EnvelopeError {
104    /// The namespace is empty.
105    EmptyNamespace,
106    /// The provider-defined kind is empty.
107    EmptyKind,
108    /// The payload has no bytes.
109    EmptyData,
110    /// The payload is not syntactically valid JSON.
111    InvalidJson,
112}
113
114impl Display for EnvelopeError {
115    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
116        formatter.write_str(match self {
117            Self::EmptyNamespace => "opaque envelope namespace is empty",
118            Self::EmptyKind => "opaque envelope kind is empty",
119            Self::EmptyData => "opaque envelope data is empty",
120            Self::InvalidJson => "opaque envelope data is not valid JSON",
121        })
122    }
123}
124
125impl Error for EnvelopeError {}
126
127impl Envelope {
128    /// Creates an envelope after validating only its portable outer shape.
129    ///
130    /// Validation is a syntax boundary and nothing more: namespace, kind, and
131    /// data are non-empty, and data must be syntactically valid JSON. That
132    /// boundary accepts non-UTF-8 bytes inside quoted strings, rejects more
133    /// than 10,000 nested containers, and never normalizes the retained bytes.
134    ///
135    /// # Errors
136    ///
137    /// The four conditions are checked in this order, so the first one that holds
138    /// is the one reported.
139    ///
140    /// - [`EnvelopeError::EmptyNamespace`] if `namespace` has no characters.
141    /// - [`EnvelopeError::EmptyKind`] if `kind` has no characters.
142    /// - [`EnvelopeError::EmptyData`] if `data` carries no bytes. An envelope
143    ///   whose payload says nothing is not a payload; a namespace and kind alone
144    ///   are routing, not content.
145    /// - [`EnvelopeError::InvalidJson`] if `data` is not syntactically valid JSON
146    ///   by the boundary above — including one nested more than 10,000 containers
147    ///   deep, which that boundary rejects rather than accepting unbounded
148    ///   recursion.
149    ///
150    /// Nothing here inspects what the namespace *means*: an envelope no hook
151    /// recognises is valid, and recognising one is composition-layer policy.
152    pub fn try_new(namespace: String, kind: String, data: Payload) -> Result<Self, EnvelopeError> {
153        if namespace.is_empty() {
154            return Err(EnvelopeError::EmptyNamespace);
155        }
156        if kind.is_empty() {
157            return Err(EnvelopeError::EmptyKind);
158        }
159        if data.as_bytes().is_empty() {
160            return Err(EnvelopeError::EmptyData);
161        }
162        if !valid_json(data.as_bytes()) {
163            return Err(EnvelopeError::InvalidJson);
164        }
165        Ok(Self {
166            namespace,
167            kind,
168            data,
169        })
170    }
171
172    /// Returns the provider namespace.
173    #[must_use]
174    pub fn namespace(&self) -> &str {
175        &self.namespace
176    }
177
178    /// Returns the provider-defined payload kind.
179    #[must_use]
180    pub fn kind(&self) -> &str {
181        &self.kind
182    }
183
184    /// Returns the exact validated payload bytes.
185    #[must_use]
186    pub const fn data(&self) -> &Payload {
187        &self.data
188    }
189
190    /// Transfers ownership of all envelope parts.
191    #[must_use]
192    pub fn into_parts(self) -> (String, String, Payload) {
193        (self.namespace, self.kind, self.data)
194    }
195}
196
197// The nesting bound of the syntax boundary a payload is validated against: deep
198// enough that no real provider extension reaches it, shallow enough that a
199// hostile one cannot drive the validator into unbounded recursion.
200const MAX_JSON_DEPTH: usize = 10_000;
201
202#[derive(Clone, Copy)]
203enum State {
204    RootValue,
205    RootDone,
206    ArrayFirst,
207    ArrayValue,
208    ArraySeparator,
209    ObjectFirst,
210    ObjectKey,
211    ObjectColon,
212    ObjectValue,
213    ObjectSeparator,
214}
215
216fn valid_json(bytes: &[u8]) -> bool {
217    let mut parser = JsonParser {
218        bytes,
219        position: 0,
220        states: vec![State::RootValue],
221    };
222    parser.parse()
223}
224
225struct JsonParser<'a> {
226    bytes: &'a [u8],
227    position: usize,
228    states: Vec<State>,
229}
230
231impl JsonParser<'_> {
232    fn parse(&mut self) -> bool {
233        loop {
234            self.skip_whitespace();
235            match *self.states.last().expect("root state is retained") {
236                State::RootValue => {
237                    if !self.parse_value(State::RootDone) {
238                        return false;
239                    }
240                }
241                State::RootDone => return self.position == self.bytes.len(),
242                State::ArrayFirst => {
243                    if self.take(b']') {
244                        self.states.pop();
245                    } else if !self.parse_value(State::ArraySeparator) {
246                        return false;
247                    }
248                }
249                State::ArrayValue => {
250                    if !self.parse_value(State::ArraySeparator) {
251                        return false;
252                    }
253                }
254                State::ArraySeparator => {
255                    if self.take(b',') {
256                        *self.states.last_mut().expect("state exists") = State::ArrayValue;
257                    } else if self.take(b']') {
258                        self.states.pop();
259                    } else {
260                        return false;
261                    }
262                }
263                State::ObjectFirst => {
264                    if self.take(b'}') {
265                        self.states.pop();
266                    } else {
267                        *self.states.last_mut().expect("state exists") = State::ObjectKey;
268                    }
269                }
270                State::ObjectKey => {
271                    if !self.parse_string() {
272                        return false;
273                    }
274                    *self.states.last_mut().expect("state exists") = State::ObjectColon;
275                }
276                State::ObjectColon => {
277                    if !self.take(b':') {
278                        return false;
279                    }
280                    *self.states.last_mut().expect("state exists") = State::ObjectValue;
281                }
282                State::ObjectValue => {
283                    if !self.parse_value(State::ObjectSeparator) {
284                        return false;
285                    }
286                }
287                State::ObjectSeparator => {
288                    if self.take(b',') {
289                        *self.states.last_mut().expect("state exists") = State::ObjectKey;
290                    } else if self.take(b'}') {
291                        self.states.pop();
292                    } else {
293                        return false;
294                    }
295                }
296            }
297        }
298    }
299
300    fn parse_value(&mut self, next: State) -> bool {
301        self.skip_whitespace();
302        *self.states.last_mut().expect("state exists") = next;
303        match self.peek() {
304            Some(b'{') => {
305                self.position += 1;
306                self.push_container(State::ObjectFirst)
307            }
308            Some(b'[') => {
309                self.position += 1;
310                self.push_container(State::ArrayFirst)
311            }
312            Some(b'"') => self.parse_string(),
313            Some(b't') => self.parse_literal(b"true"),
314            Some(b'f') => self.parse_literal(b"false"),
315            Some(b'n') => self.parse_literal(b"null"),
316            Some(b'-' | b'0'..=b'9') => self.parse_number(),
317            _ => false,
318        }
319    }
320
321    fn push_container(&mut self, state: State) -> bool {
322        if self.states.len() > MAX_JSON_DEPTH {
323            return false;
324        }
325        self.states.push(state);
326        true
327    }
328
329    fn parse_literal(&mut self, literal: &[u8]) -> bool {
330        if self.bytes[self.position..].starts_with(literal) {
331            self.position += literal.len();
332            true
333        } else {
334            false
335        }
336    }
337
338    fn parse_string(&mut self) -> bool {
339        if !self.take(b'"') {
340            return false;
341        }
342        while let Some(byte) = self.peek() {
343            self.position += 1;
344            match byte {
345                b'"' => return true,
346                b'\\' => match self.peek() {
347                    Some(b'"' | b'\\' | b'/' | b'b' | b'f' | b'n' | b'r' | b't') => {
348                        self.position += 1;
349                    }
350                    Some(b'u') => {
351                        self.position += 1;
352                        for _ in 0..4 {
353                            if !self.peek().is_some_and(|digit| digit.is_ascii_hexdigit()) {
354                                return false;
355                            }
356                            self.position += 1;
357                        }
358                    }
359                    _ => return false,
360                },
361                0..=0x1f => return false,
362                _ => {}
363            }
364        }
365        false
366    }
367
368    fn parse_number(&mut self) -> bool {
369        if self.take(b'-') && self.peek().is_none() {
370            return false;
371        }
372        match self.peek() {
373            Some(b'0') => self.position += 1,
374            Some(b'1'..=b'9') => self.take_digits(),
375            _ => return false,
376        }
377        if self.take(b'.') {
378            if !self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
379                return false;
380            }
381            self.take_digits();
382        }
383        if matches!(self.peek(), Some(b'e' | b'E')) {
384            self.position += 1;
385            if matches!(self.peek(), Some(b'+' | b'-')) {
386                self.position += 1;
387            }
388            if !self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
389                return false;
390            }
391            self.take_digits();
392        }
393        true
394    }
395
396    fn take_digits(&mut self) {
397        while self.peek().is_some_and(|byte| byte.is_ascii_digit()) {
398            self.position += 1;
399        }
400    }
401
402    fn skip_whitespace(&mut self) {
403        while matches!(self.peek(), Some(b' ' | b'\n' | b'\r' | b'\t')) {
404            self.position += 1;
405        }
406    }
407
408    fn take(&mut self, expected: u8) -> bool {
409        if self.peek() == Some(expected) {
410            self.position += 1;
411            true
412        } else {
413            false
414        }
415    }
416
417    fn peek(&self) -> Option<u8> {
418        self.bytes.get(self.position).copied()
419    }
420}
421
422/// The serialized form of [`Payload`] and [`Envelope`] (ADR-019 D5).
423///
424/// A payload is a byte string with no wrapper around it, because the wrapper is
425/// a Rust representation detail. An envelope is the three fields `namespace`,
426/// `kind` and `data`, and reading one re-runs [`Envelope::try_new`]: a session
427/// file is untrusted input, so the validator that guards the call site guards the
428/// file too.
429#[cfg(feature = "serde")]
430mod serde_impl {
431    use std::fmt::{self, Formatter};
432
433    use serde_core::de::{Deserialize, Deserializer, Error as _, MapAccess, SeqAccess, Visitor};
434    use serde_core::ser::{Serialize, SerializeStruct, Serializer};
435
436    use super::{Envelope, Payload};
437    use crate::wire::{self, ByteBuf, Bytes, IdentifierSeed};
438
439    const ENVELOPE_FIELDS: &[&str] = &["namespace", "kind", "data"];
440
441    impl Serialize for Payload {
442        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
443        where
444            S: Serializer,
445        {
446            Bytes(&self.0).serialize(serializer)
447        }
448    }
449
450    impl<'de> Deserialize<'de> for Payload {
451        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
452        where
453            D: Deserializer<'de>,
454        {
455            ByteBuf::deserialize(deserializer).map(|buffer| Self(buffer.0))
456        }
457    }
458
459    impl Serialize for Envelope {
460        fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
461        where
462            S: Serializer,
463        {
464            let mut record = serializer.serialize_struct("Envelope", 3)?;
465            record.serialize_field("namespace", &self.namespace)?;
466            record.serialize_field("kind", &self.kind)?;
467            record.serialize_field("data", &self.data)?;
468            record.end()
469        }
470    }
471
472    impl<'de> Deserialize<'de> for Envelope {
473        fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
474        where
475            D: Deserializer<'de>,
476        {
477            deserializer.deserialize_struct("Envelope", ENVELOPE_FIELDS, EnvelopeVisitor)
478        }
479    }
480
481    struct EnvelopeVisitor;
482
483    impl EnvelopeVisitor {
484        fn build<E>(namespace: String, kind: String, data: Payload) -> Result<Envelope, E>
485        where
486            E: serde_core::de::Error,
487        {
488            Envelope::try_new(namespace, kind, data).map_err(E::custom)
489        }
490    }
491
492    impl<'de> Visitor<'de> for EnvelopeVisitor {
493        type Value = Envelope;
494
495        fn expecting(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
496            formatter.write_str("an opaque envelope")
497        }
498
499        fn visit_seq<A>(self, mut sequence: A) -> Result<Self::Value, A::Error>
500        where
501            A: SeqAccess<'de>,
502        {
503            let namespace = wire::element(&mut sequence, 0)?;
504            let kind = wire::element(&mut sequence, 1)?;
505            let data = wire::element(&mut sequence, 2)?;
506            Self::build(namespace, kind, data)
507        }
508
509        fn visit_map<A>(self, mut entries: A) -> Result<Self::Value, A::Error>
510        where
511            A: MapAccess<'de>,
512        {
513            let mut namespace = None;
514            let mut kind = None;
515            let mut data = None;
516            while let Some(field) = entries.next_key_seed(IdentifierSeed(ENVELOPE_FIELDS))? {
517                match field.0.as_str() {
518                    "namespace" => {
519                        wire::accept(&mut namespace, entries.next_value()?, "namespace")?
520                    }
521                    "kind" => wire::accept(&mut kind, entries.next_value()?, "kind")?,
522                    "data" => wire::accept(&mut data, entries.next_value()?, "data")?,
523                    unknown => return Err(A::Error::unknown_field(unknown, ENVELOPE_FIELDS)),
524                }
525            }
526            Self::build(
527                wire::require(namespace, "namespace")?,
528                wire::require(kind, "kind")?,
529                wire::require(data, "data")?,
530            )
531        }
532    }
533}
534
535#[cfg(test)]
536#[path = "opaque_tests.rs"]
537mod opaque_tests;