wa-wire-codec 0.1.0

Zero-copy parser for WhatsApp's binary-node encoding, over pluggable token tables
Documentation
# wa-wire-codec

A parser for WhatsApp's binary-node encoding, over pluggable token tables.

[`wa-wire-contract`](../wa-wire-contract) carries a stanza across the boundary
exactly as the engine decoded it — nothing is re-encoded, so the frame inside an
envelope is still in WhatsApp's own format. This crate is what makes that frame
navigable: host-side, once, and only if something asked.

## Nothing is copied

A `NodeRef` borrows the frame and re-walks it on demand. The encoding is
self-delimiting, so a node never needs to know where it ends, and there is
nothing to build up front. Tokens are borrowed from the table; raw payloads are
sub-slices of the frame.

Two forms have text that exists nowhere in the buffer — packed digit runs and
JIDs — and those stay **in parts** rather than being joined. They compare and
render on demand:

```rust
// No allocation: the comparison walks the parts.
let is_text = node.attr_eq("type", "text");
```

This is the difference between a parser you can run per stanza and one you
budget for. The read paths carry
[measured time and allocation budgets](../wa-wire-alloc-check) so the property
cannot quietly stop being true.

## The token table is a parameter

WhatsApp's dictionaries move with the client version. Under RFC-009 that is
*provenance*, not contract version, so the table is passed in rather than
compiled in:

```rust
let parser = Parser::new(tokens::TABLE);              // the bundled table
let custom = Parser::new(TokenTable::new(&[], &[]));  // or your own
```

The bundled table is generated from whatspec and committed
(`python3 tools/generate-tokens.py`), so a dictionary change arrives as a
reviewable diff rather than a build artifact. A host that supplies its own can
drop the `bundled-tokens` feature.

Two recordings parsed under different dictionaries are not comparable, and
saying so is [`wa-wire-recording`](../wa-wire-recording)'s job, not this crate's.

## Paths address nodes

The contract addresses each plaintext by the path of the node it came from; this
crate walks that path. If the two ever disagreed about what a path means, a
decrypted message would be attributed to the wrong recipient — so the agreement
is [asserted in a test](tests/envelope_integration.rs), not assumed.

## Scope

`no_std`, no dependencies. This crate reads the *stanza*; the protobuf inside an
`<enc>` is [`wa-wire-proto`](../wa-wire-proto). Both parse wire formats written
by somebody else, and both are held to the same rule about malformed input:
report it, never panic.