Skip to main content

wa_wire_codec/
lib.rs

1//! Zero-copy parsing of WhatsApp's binary-node encoding.
2//!
3//! `wa-wire` carries a stanza across the boundary exactly as the engine decoded
4//! it — nothing is re-encoded, so the frame in an envelope is still in
5//! WhatsApp's own format. This crate is what turns that frame into something
6//! navigable, host-side, and only when something actually asked for it.
7//!
8//! # Nothing is copied
9//!
10//! A [`NodeRef`] borrows the frame and re-walks it on demand; the encoding is
11//! self-delimiting, so a node never needs to know where it ends. Tokens are
12//! borrowed from the table. Raw payloads are sub-slices of the frame.
13//!
14//! The two forms whose text exists nowhere in the buffer — packed digit runs
15//! and JIDs — stay in parts rather than being joined, and compare and render
16//! on demand:
17//!
18//! ```
19//! # use wa_wire_codec::{Parser, tokens};
20//! # let parser = Parser::new(tokens::TABLE);
21//! # let frame = &[0xf8, 0x02, 0x05, 0x00][..];
22//! # let node = parser.parse(frame).unwrap();
23//! // No allocation: the comparison walks the parts.
24//! let is_text = node.attr_eq("type", "text");
25//! # let _ = is_text;
26//! ```
27//!
28//! # The token table is a parameter
29//!
30//! WhatsApp's dictionaries move with the client version. Under RFC-009 that is
31//! a matter of *provenance*, not of contract version, so the table is passed in
32//! rather than compiled in. The bundled one is generated and committed, so a
33//! protocol change arrives as a reviewable diff.
34//!
35//! ```
36//! use wa_wire_codec::{Parser, TokenTable, tokens};
37//!
38//! let parser = Parser::new(tokens::TABLE);          // the bundled table
39//! let custom = Parser::new(TokenTable::new(&[], &[])); // or your own
40//! # let _ = (parser, custom);
41//! ```
42//!
43//! # Paths line up with envelopes
44//!
45//! A plaintext entry in a `wa-wire-contract` envelope addresses its node by a
46//! path of child indices. [`NodeRef::at_path`] walks exactly that path, which
47//! is how a decrypted payload is matched back to the `<enc>` it came from.
48//!
49//! # Validation
50//!
51//! [`Parser::parse`] validates the entire tree, so every accessor on the result
52//! is infallible. Malformed input is rejected up front and specifically enough
53//! to tell a protocol change apart from corruption.
54
55#![no_std]
56#![cfg_attr(
57    test,
58    allow(
59        clippy::expect_used,
60        clippy::unwrap_used,
61        clippy::panic,
62        clippy::indexing_slicing,
63        clippy::arithmetic_side_effects,
64        clippy::cast_possible_truncation,
65    )
66)]
67
68pub mod error;
69pub mod jid;
70pub mod node;
71pub mod packed;
72mod reader;
73pub mod token;
74pub mod value;
75
76#[cfg(feature = "bundled-tokens")]
77pub mod tokens;
78
79pub use error::ParseError;
80pub use jid::{Jid, User};
81pub use node::{Attrs, Children, Content, DEFAULT_MAX_DEPTH, NodeRef, Parser};
82pub use packed::{Alphabet, Packed};
83pub use token::TokenTable;
84pub use value::Value;