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;