Skip to main content

wa_wire_codec/
token.rs

1//! Tag bytes and the token dictionaries they index into.
2//!
3//! The table is a parameter rather than a constant. WhatsApp's dictionaries
4//! move with the client version, and RFC-009 makes that a matter of
5//! provenance, not of contract version — so a host generated from a different
6//! `whatspec` build supplies its own table instead of needing a different
7//! parser.
8
9/// An empty value, and the terminator for an absent node body.
10pub const LIST_EMPTY: u8 = 0;
11/// A bare stream-end frame.
12pub const STREAM_END: u8 = 2;
13
14/// First double-byte dictionary tag.
15pub const DICTIONARY_0: u8 = 236;
16/// Last double-byte dictionary tag.
17pub const DICTIONARY_3: u8 = 239;
18
19/// An interop JID.
20pub const JID_INTEROP: u8 = 245;
21/// A Messenger JID.
22pub const JID_FB: u8 = 246;
23/// A user JID with an explicit domain type and device.
24pub const JID_USER: u8 = 247;
25/// A list whose length fits in one byte.
26pub const LIST_8: u8 = 248;
27/// A list whose length needs two bytes.
28pub const LIST_16: u8 = 249;
29/// A `user@server` JID.
30pub const JID_PAIR: u8 = 250;
31/// A run of packed hexadecimal digits.
32pub const HEX_8: u8 = 251;
33/// Bytes with an 8-bit length.
34pub const BINARY_8: u8 = 252;
35/// Bytes with a 20-bit length.
36pub const BINARY_20: u8 = 253;
37/// Bytes with a 32-bit length.
38pub const BINARY_32: u8 = 254;
39/// A run of packed nibble digits.
40pub const NIBBLE_8: u8 = 255;
41
42/// Domain type byte: a phone-number JID.
43pub const DOMAIN_TYPE_PN: u8 = 0x00;
44/// Domain type byte: a LID JID.
45pub const DOMAIN_TYPE_LID: u8 = 0x01;
46/// Domain type byte: a hosted LID JID.
47pub const DOMAIN_TYPE_HOSTED_LID: u8 = 0x81;
48/// Mask selecting the hosted bit of a domain type.
49pub const DOMAIN_TYPE_HOSTED_MASK: u8 = 0x80;
50/// Mask selecting the LID bit of a domain type.
51pub const DOMAIN_TYPE_LID_MASK: u8 = 0x01;
52
53/// The default server for phone-number JIDs.
54pub const SERVER_PN: &str = "s.whatsapp.net";
55/// The server for LID JIDs.
56pub const SERVER_LID: &str = "lid";
57/// The server for hosted phone-number JIDs.
58pub const SERVER_HOSTED: &str = "hosted";
59/// The server for hosted LID JIDs.
60pub const SERVER_HOSTED_LID: &str = "hosted.lid";
61/// The server for interop JIDs.
62pub const SERVER_INTEROP: &str = "interop";
63/// The server for Messenger JIDs.
64pub const SERVER_MSGR: &str = "msgr";
65
66/// Digits a packed nibble run can encode. The last four slots are unassigned
67/// and decode to the replacement character rather than failing, matching what
68/// every engine already does.
69pub const NIBBLE_ALPHABET: [char; 16] = [
70    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '.', '\u{FFFD}', '\u{FFFD}', '\u{FFFD}',
71    '\u{FFFD}',
72];
73
74/// Digits a packed hex run can encode.
75pub const HEX_ALPHABET: [char; 16] = [
76    '0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', 'B', 'C', 'D', 'E', 'F',
77];
78
79/// The token dictionaries a frame's tags index into.
80#[derive(Debug, Clone, Copy, PartialEq, Eq)]
81pub struct TokenTable<'a> {
82    single_byte: &'a [&'a str],
83    dictionaries: &'a [&'a [&'a str]],
84}
85
86impl<'a> TokenTable<'a> {
87    /// Build a table from a single-byte list and the double-byte dictionaries.
88    #[must_use]
89    pub const fn new(single_byte: &'a [&'a str], dictionaries: &'a [&'a [&'a str]]) -> Self {
90        Self {
91            single_byte,
92            dictionaries,
93        }
94    }
95
96    /// An empty table. Every token lookup fails, which is what a host wants
97    /// while it is still deciding which spec build to load.
98    #[must_use]
99    pub const fn empty() -> Self {
100        Self {
101            single_byte: &[],
102            dictionaries: &[],
103        }
104    }
105
106    /// The single-byte token for `tag`.
107    ///
108    /// The tag byte *is* the index. Slot 0 is never a real token — that byte
109    /// means `LIST_EMPTY` on the wire — so a table carries a placeholder there
110    /// rather than shifting everything by one. Getting this off by one silently
111    /// resolves every token to its neighbour, so it is pinned by a test against
112    /// the engine's own table.
113    #[must_use]
114    pub fn single_byte(&self, tag: u8) -> Option<&'a str> {
115        self.single_byte.get(usize::from(tag)).copied()
116    }
117
118    /// The token at `index` of dictionary `dictionary`.
119    #[must_use]
120    pub fn dictionary(&self, dictionary: u8, index: u8) -> Option<&'a str> {
121        let dictionary = self.dictionaries.get(usize::from(dictionary))?;
122        dictionary.get(usize::from(index)).copied()
123    }
124
125    /// How many single-byte tokens the table holds.
126    #[must_use]
127    pub const fn single_byte_len(&self) -> usize {
128        self.single_byte.len()
129    }
130
131    /// How many double-byte dictionaries the table holds.
132    #[must_use]
133    pub const fn dictionary_count(&self) -> usize {
134        self.dictionaries.len()
135    }
136}
137
138impl Default for TokenTable<'_> {
139    fn default() -> Self {
140        Self::empty()
141    }
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    static SINGLE: [&str; 4] = ["<none>", "alpha", "beta", "gamma"];
149    static DICT_A: [&str; 2] = ["one", "two"];
150    static DICT_B: [&str; 1] = ["three"];
151    static DICTS: [&[&str]; 2] = [&DICT_A, &DICT_B];
152
153    fn table() -> TokenTable<'static> {
154        TokenTable::new(&SINGLE, &DICTS)
155    }
156
157    #[test]
158    fn the_tag_byte_indexes_the_table_directly() {
159        let table = table();
160        // Slot 0 is the placeholder for LIST_EMPTY; the engine's own table
161        // carries one, and shifting instead would resolve every token to its
162        // neighbour.
163        assert_eq!(table.single_byte(0), Some("<none>"));
164        assert_eq!(table.single_byte(1), Some("alpha"));
165        assert_eq!(table.single_byte(2), Some("beta"));
166        assert_eq!(table.single_byte(3), Some("gamma"));
167        assert_eq!(table.single_byte(4), None);
168        assert_eq!(table.single_byte(u8::MAX), None);
169    }
170
171    #[test]
172    fn dictionary_lookups_are_bounded_on_both_axes() {
173        let table = table();
174        assert_eq!(table.dictionary(0, 0), Some("one"));
175        assert_eq!(table.dictionary(0, 1), Some("two"));
176        assert_eq!(table.dictionary(1, 0), Some("three"));
177
178        assert_eq!(table.dictionary(0, 2), None, "index past the dictionary");
179        assert_eq!(table.dictionary(1, 1), None);
180        assert_eq!(table.dictionary(2, 0), None, "no such dictionary");
181        assert_eq!(table.dictionary(u8::MAX, u8::MAX), None);
182    }
183
184    #[test]
185    fn sizes_are_reported() {
186        let table = table();
187        assert_eq!(table.single_byte_len(), 4);
188        assert_eq!(table.dictionary_count(), 2);
189    }
190
191    #[test]
192    fn the_empty_table_resolves_nothing() {
193        let empty = TokenTable::empty();
194        assert_eq!(empty.single_byte_len(), 0);
195        assert_eq!(empty.dictionary_count(), 0);
196        assert_eq!(empty.single_byte(0), None);
197        assert_eq!(empty.single_byte(1), None);
198        assert_eq!(empty.dictionary(0, 0), None);
199        assert_eq!(empty, TokenTable::default());
200    }
201
202    #[test]
203    fn tag_constants_are_pinned() {
204        // These are the wire; changing one breaks every frame.
205        assert_eq!(LIST_EMPTY, 0);
206        assert_eq!(STREAM_END, 2);
207        assert_eq!(DICTIONARY_0, 236);
208        assert_eq!(DICTIONARY_3, 239);
209        assert_eq!(JID_INTEROP, 245);
210        assert_eq!(JID_FB, 246);
211        assert_eq!(JID_USER, 247);
212        assert_eq!(LIST_8, 248);
213        assert_eq!(LIST_16, 249);
214        assert_eq!(JID_PAIR, 250);
215        assert_eq!(HEX_8, 251);
216        assert_eq!(BINARY_8, 252);
217        assert_eq!(BINARY_20, 253);
218        assert_eq!(BINARY_32, 254);
219        assert_eq!(NIBBLE_8, 255);
220        assert_eq!(usize::from(DICTIONARY_3 - DICTIONARY_0) + 1, 4);
221    }
222
223    #[test]
224    fn alphabets_cover_a_full_nibble() {
225        assert_eq!(NIBBLE_ALPHABET.len(), 16);
226        assert_eq!(HEX_ALPHABET.len(), 16);
227        assert_eq!(
228            &NIBBLE_ALPHABET[..12],
229            &['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '-', '.']
230        );
231        assert!(NIBBLE_ALPHABET[12..].iter().all(|c| *c == '\u{FFFD}'));
232        assert_eq!(HEX_ALPHABET[10], 'A');
233        assert_eq!(HEX_ALPHABET[15], 'F');
234    }
235
236    #[test]
237    fn domain_type_masks_classify_correctly() {
238        assert_eq!(DOMAIN_TYPE_PN & DOMAIN_TYPE_HOSTED_MASK, 0);
239        assert_eq!(DOMAIN_TYPE_LID & DOMAIN_TYPE_LID_MASK, 1);
240        assert_ne!(DOMAIN_TYPE_HOSTED_LID & DOMAIN_TYPE_HOSTED_MASK, 0);
241        assert_ne!(DOMAIN_TYPE_HOSTED_LID & DOMAIN_TYPE_LID_MASK, 0);
242    }
243}