Skip to main content

wa_wire_proto/
lib.rs

1//! Zero-copy reader for the protobuf wire format.
2//!
3//! The sibling of [`wa-wire-codec`]. That one parses the stanza; this one
4//! parses what the stanza's `<enc>` children decrypt to, which is where every
5//! message body lives. Same rules: `no_std`, no dependencies, borrowing from
6//! the buffer rather than copying out of it.
7//!
8//! ```
9//! use wa_wire_proto::{Reader, Value};
10//!
11//! // field 1, length-delimited, "hi"
12//! let buf = [0x0a, 0x02, b'h', b'i'];
13//! let text = Reader::new(&buf)
14//!     .find_last(1)?
15//!     .and_then(Value::as_str);
16//! assert_eq!(text, Some("hi"));
17//! # Ok::<(), wa_wire_proto::Error>(())
18//! ```
19//!
20//! # What it does not do
21//!
22//! It does not know any schema. A field is a number and some bytes, and what
23//! those mean is the caller's business. That is deliberate: the payloads here
24//! come from a protocol that adds fields without asking, and a reader that
25//! refused an unknown field would fail on exactly the traffic worth looking at.
26//!
27//! # Totality
28//!
29//! Every byte sequence either yields fields or a reportable error, and no
30//! sequence panics. Once a read fails the reader stops, so a caller looping
31//! over [`Reader::next`] cannot spin on the same bad byte.
32//!
33//! [`wa-wire-codec`]: https://docs.rs/wa-wire-codec
34
35#![no_std]
36#![cfg_attr(
37    test,
38    allow(
39        clippy::expect_used,
40        clippy::unwrap_used,
41        clippy::panic,
42        clippy::indexing_slicing,
43        clippy::arithmetic_side_effects,
44    )
45)]
46
47use core::fmt;
48
49/// How deep groups may nest before a payload is treated as malformed.
50///
51/// Generous by orders of magnitude: nothing in WhatsApp's schema uses groups
52/// at all, and a payload nesting them deeper than this is one nobody sent. The
53/// bound exists because the alternative is a growable stack, and this crate
54/// has no allocator.
55const MAX_GROUP_DEPTH: usize = 32;
56
57/// Why a payload could not be read.
58///
59/// A payload arrives from another party's encoder, so a malformed one is an
60/// ordinary input rather than a bug: reportable, never a panic.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62#[non_exhaustive]
63pub enum Error {
64    /// A varint ran past the end of the buffer, or past ten bytes.
65    ///
66    /// Ten is the most a `u64` can need, so an eleventh continuation byte is a
67    /// malformed input rather than a bigger number.
68    MalformedVarint,
69    /// The buffer ended in the middle of a field.
70    UnexpectedEnd {
71        /// Bytes the field needed.
72        needed: usize,
73        /// Bytes left.
74        available: usize,
75    },
76    /// A tag named wire type 6 or 7, which the format does not define.
77    UnknownWireType(u8),
78    /// A tag named field number zero, which the format forbids.
79    ZeroFieldNumber,
80    /// A group was opened and never closed.
81    UnterminatedGroup {
82        /// The field number that opened it.
83        number: u32,
84    },
85    /// A group ended that was never opened.
86    UnexpectedGroupEnd {
87        /// The field number that closed it.
88        number: u32,
89    },
90}
91
92impl fmt::Display for Error {
93    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
94        match self {
95            Self::MalformedVarint => f.write_str("malformed varint"),
96            Self::UnexpectedEnd { needed, available } => write!(
97                f,
98                "payload ended mid-field: needed {needed} byte(s), {available} available"
99            ),
100            Self::UnknownWireType(wire) => write!(f, "wire type {wire} is not defined"),
101            Self::ZeroFieldNumber => f.write_str("field number 0 is not allowed"),
102            Self::UnterminatedGroup { number } => {
103                write!(f, "group {number} was opened and never closed")
104            }
105            Self::UnexpectedGroupEnd { number } => {
106                write!(f, "group {number} was closed but never opened")
107            }
108        }
109    }
110}
111
112impl core::error::Error for Error {}
113
114/// One field's value, borrowed from the payload.
115#[derive(Debug, Clone, Copy, PartialEq, Eq)]
116pub enum Value<'a> {
117    /// Wire type 0. Also carries `bool`, the `int`/`uint`/`sint` families and
118    /// enums, which is why the interpretation is left to the caller.
119    Varint(u64),
120    /// Wire type 1: `fixed64`, `sfixed64`, `double`.
121    Fixed64(u64),
122    /// Wire type 2: `string`, `bytes`, embedded messages, packed repeats.
123    Bytes(&'a [u8]),
124    /// Wire type 3 and 4: everything between the start and the matching end.
125    ///
126    /// Deprecated in the format and unused by this protocol, but read rather
127    /// than refused: a reader that stopped here would stop on a payload it
128    /// could otherwise have handed over whole.
129    Group(&'a [u8]),
130    /// Wire type 5: `fixed32`, `sfixed32`, `float`.
131    Fixed32(u32),
132}
133
134impl<'a> Value<'a> {
135    /// The varint, if this is one.
136    #[must_use]
137    pub const fn as_u64(self) -> Option<u64> {
138        match self {
139            // A `fixed64` is a `u64` that chose a different encoding, so a
140            // caller asking for the number should not have to care which.
141            Self::Varint(value) | Self::Fixed64(value) => Some(value),
142            _ => None,
143        }
144    }
145
146    /// The varint narrowed to `u32`, if it fits.
147    #[must_use]
148    pub fn as_u32(self) -> Option<u32> {
149        u32::try_from(self.as_u64()?).ok()
150    }
151
152    /// A `bool`, which the format encodes as a varint.
153    #[must_use]
154    pub fn as_bool(self) -> Option<bool> {
155        Some(self.as_u64()? != 0)
156    }
157
158    /// A zig-zag `sint64`.
159    #[must_use]
160    pub fn as_sint64(self) -> Option<i64> {
161        let raw = self.as_u64()?;
162        // The standard zig-zag decode, written without a cast: `raw >> 1`
163        // always fits, and the negative branch is spelled out so a reader can
164        // check it against the encoding rather than against a bit trick.
165        let half = i64::try_from(raw >> 1).ok()?;
166        Some(if raw & 1 == 0 {
167            half
168        } else {
169            half.checked_neg()?.checked_sub(1)?
170        })
171    }
172
173    /// The bytes, if this is a length-delimited field or a group.
174    #[must_use]
175    pub const fn as_bytes(self) -> Option<&'a [u8]> {
176        match self {
177            Self::Bytes(bytes) | Self::Group(bytes) => Some(bytes),
178            _ => None,
179        }
180    }
181
182    /// The bytes as UTF-8.
183    ///
184    /// `None` for a field that is not length-delimited *and* for one whose
185    /// bytes are not UTF-8, because a `string` field carrying something else
186    /// is a payload disagreeing with its own schema.
187    #[must_use]
188    pub fn as_str(self) -> Option<&'a str> {
189        core::str::from_utf8(self.as_bytes()?).ok()
190    }
191
192    /// Read this field as a nested message.
193    #[must_use]
194    pub fn as_message(self) -> Option<Reader<'a>> {
195        Some(Reader::new(self.as_bytes()?))
196    }
197}
198
199/// One field: its number and its value.
200#[derive(Debug, Clone, Copy, PartialEq, Eq)]
201pub struct Field<'a> {
202    /// The field number the encoder wrote.
203    pub number: u32,
204    /// What it carried.
205    pub value: Value<'a>,
206}
207
208/// Walks a payload, one field at a time.
209#[derive(Debug, Clone, Copy)]
210pub struct Reader<'a> {
211    rest: &'a [u8],
212    failed: bool,
213}
214
215impl<'a> Reader<'a> {
216    /// Read `payload`.
217    #[must_use]
218    pub const fn new(payload: &'a [u8]) -> Self {
219        Self {
220            rest: payload,
221            failed: false,
222        }
223    }
224
225    /// Bytes not yet read.
226    #[must_use]
227    pub const fn remaining(&self) -> &'a [u8] {
228        self.rest
229    }
230
231    /// Whether a read has failed, after which nothing more is produced.
232    #[must_use]
233    pub const fn is_failed(&self) -> bool {
234        self.failed
235    }
236
237    /// The next field, or `None` at the end.
238    ///
239    /// Fuses on error: a caller looping over this cannot spin on one bad byte.
240    #[allow(clippy::should_implement_trait, reason = "fallible and fusing")]
241    pub fn next(&mut self) -> Option<Result<Field<'a>, Error>> {
242        if self.failed || self.rest.is_empty() {
243            return None;
244        }
245        match self.read_field() {
246            Ok(field) => Some(Ok(field)),
247            Err(error) => {
248                self.failed = true;
249                Some(Err(error))
250            }
251        }
252    }
253
254    /// The last field numbered `number`, if any.
255    ///
256    /// The *last*, because the format says a repeated scalar resolves to the
257    /// one written last, and a payload that repeats a field is legal.
258    ///
259    /// # Errors
260    ///
261    /// [`Error`] if the payload is malformed before the search ends.
262    pub fn find_last(mut self, number: u32) -> Result<Option<Value<'a>>, Error> {
263        let mut found = None;
264        while let Some(field) = self.next() {
265            let field = field?;
266            if field.number == number {
267                found = Some(field.value);
268            }
269        }
270        Ok(found)
271    }
272
273    fn read_field(&mut self) -> Result<Field<'a>, Error> {
274        let tag = self.read_varint()?;
275        let number = u32::try_from(tag >> 3).map_err(|_| Error::MalformedVarint)?;
276        if number == 0 {
277            return Err(Error::ZeroFieldNumber);
278        }
279        let wire = u8::try_from(tag & 7).unwrap_or(u8::MAX);
280
281        let value = match wire {
282            0 => Value::Varint(self.read_varint()?),
283            1 => Value::Fixed64(u64::from_le_bytes(self.read_array::<8>()?)),
284            2 => {
285                let len =
286                    usize::try_from(self.read_varint()?).map_err(|_| Error::UnexpectedEnd {
287                        needed: usize::MAX,
288                        available: self.rest.len(),
289                    })?;
290                Value::Bytes(self.take(len)?)
291            }
292            3 => Value::Group(self.read_group(number)?),
293            4 => return Err(Error::UnexpectedGroupEnd { number }),
294            5 => Value::Fixed32(u32::from_le_bytes(self.read_array::<4>()?)),
295            other => return Err(Error::UnknownWireType(other)),
296        };
297        Ok(Field { number, value })
298    }
299
300    /// Everything between a start-group tag and its matching end.
301    fn read_group(&mut self, number: u32) -> Result<&'a [u8], Error> {
302        let body = self.rest;
303        // The numbers of the groups currently open, outermost first.
304        //
305        // A depth counter alone only checks the outermost close: `group 1,
306        // group 2, end 3, end 1` balances, and the mismatched `end 3` passes
307        // unremarked because the check waits for depth to reach zero. Every
308        // end-group names the field it closes, so every one can be checked
309        // against the start it is supposed to match.
310        //
311        // A fixed array rather than a growable stack, this crate having no
312        // allocator. The bound is generous by orders of magnitude: nothing in
313        // WhatsApp's schema uses groups at all, and a payload nesting them
314        // deeper than this is a payload nobody sent.
315        let mut open = [0u32; MAX_GROUP_DEPTH];
316        let mut depth = 1usize;
317        *open.first_mut().ok_or(Error::MalformedVarint)? = number;
318        loop {
319            let before = self.rest.len();
320            let tag = self.read_varint()?;
321            let inner = u32::try_from(tag >> 3).map_err(|_| Error::MalformedVarint)?;
322            if inner == 0 {
323                return Err(Error::ZeroFieldNumber);
324            }
325            match tag & 7 {
326                0 => {
327                    self.read_varint()?;
328                }
329                1 => {
330                    self.read_array::<8>()?;
331                }
332                2 => {
333                    let len = payload_len(self.read_varint()?, self.rest.len())?;
334                    self.take(len)?;
335                }
336                3 => {
337                    let Some(slot) = open.get_mut(depth) else {
338                        return Err(Error::UnexpectedGroupEnd { number: inner });
339                    };
340                    *slot = inner;
341                    depth = depth.saturating_add(1);
342                }
343                4 => {
344                    depth = depth.saturating_sub(1);
345                    // Each end-group against the start it closes, not only the
346                    // outermost one.
347                    if open.get(depth).copied() != Some(inner) {
348                        return Err(Error::UnexpectedGroupEnd { number: inner });
349                    }
350                    if depth == 0 {
351                        // Everything before the tag that closed it.
352                        let end = body.len().saturating_sub(before);
353                        return body.get(..end).ok_or(Error::UnterminatedGroup { number });
354                    }
355                }
356                5 => {
357                    self.read_array::<4>()?;
358                }
359                other => {
360                    return Err(Error::UnknownWireType(
361                        u8::try_from(other).unwrap_or(u8::MAX),
362                    ));
363                }
364            }
365            if self.rest.is_empty() {
366                return Err(Error::UnterminatedGroup { number });
367            }
368        }
369    }
370
371    fn read_varint(&mut self) -> Result<u64, Error> {
372        let mut value = 0u64;
373        for index in 0u32..10 {
374            let byte = *self.rest.first().ok_or(Error::MalformedVarint)?;
375            self.rest = self.rest.get(1..).unwrap_or(&[]);
376            // Nine groups of seven bits reach bit 62; the tenth byte carries
377            // bit 63 and nothing else. A `2` there shifts left by 63 and falls
378            // out of the word, so the reader would accept nine `0x80`s and a
379            // `0x02` as *zero* — a malformed varint read as a value, which is
380            // worse than one refused.
381            if index == 9 && byte & 0xFE != 0 {
382                return Err(Error::MalformedVarint);
383            }
384            value |= u64::from(byte & 0x7F) << index.saturating_mul(7);
385            if byte & 0x80 == 0 {
386                return Ok(value);
387            }
388        }
389        Err(Error::MalformedVarint)
390    }
391
392    fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error> {
393        let bytes = self.take(N)?;
394        <[u8; N]>::try_from(bytes).map_err(|_| Error::UnexpectedEnd {
395            needed: N,
396            available: 0,
397        })
398    }
399
400    fn take(&mut self, n: usize) -> Result<&'a [u8], Error> {
401        let (head, tail) = self.rest.split_at_checked(n).ok_or(Error::UnexpectedEnd {
402            needed: n,
403            available: self.rest.len(),
404        })?;
405        self.rest = tail;
406        Ok(head)
407    }
408}
409
410/// Narrow a length prefix to this target's `usize`.
411///
412/// A free function so the limit stays testable: `usize` is 32-bit on wasm32 and
413/// on the ESP32 targets this ecosystem builds for, and a length written by
414/// somebody else can exceed it there. Reaching the branch through the reader
415/// would need a four-gigabyte payload on a 64-bit host.
416fn payload_len(raw: u64, available: usize) -> Result<usize, Error> {
417    usize::try_from(raw).map_err(|_| Error::UnexpectedEnd {
418        needed: usize::MAX,
419        available,
420    })
421}
422
423#[cfg(test)]
424#[path = "lib_tests.rs"]
425mod tests;