Skip to main content

Crate wa_wire_contract

Crate wa_wire_contract 

Source
Expand description

The normative wa-wire boundary format and negotiation types.

Every WhatsApp Web client library speaks the same wire protocol and exposes a different API. wa-wire makes the thing they already share — the wire itself — the interface, so an integration written once runs on any conforming engine.

§The layer model

  • L0-wire — the stanza as it arrived, payload still encrypted.
  • L0-plain — that frame plus the plaintexts the engine decrypted.
  • L1 — typed canonical events, derived from L0-plain.

L0 is normative and L1 is a derived view: nothing may appear in L1 that is not derivable from L0-plain. L0-plain → L1 is a pure function — protobuf parsing and mapping, no keys and no accumulated state — which is why it runs host-side, once, instead of being reimplemented per engine.

§What crosses the boundary

The frame bytes already exist inside every engine at the moment it decodes, and the frame never contained the plaintext anyway — <enc> carries ciphertext, and the plaintext arrives later from Signal. So an envelope is the frame verbatim plus a side table of plaintexts, each addressed by the path of the node it belongs to.

Nothing is re-encoded, so there is no encoding to choose. The frame is parsed exactly once, host-side, and only if something subscribed to L1.

use wa_wire_contract::{EnvelopeBuilder, EnvelopeRef, Flags, NodePath,
                       PlaintextEntry, PlaintextStatus};

// A <message> whose single <enc> child decrypted successfully.
let frame = b"\xf8\x03...";                 // unpacked binary-node bytes
let path = 0u16.to_le_bytes();              // child 0 of the root
let entries = [PlaintextEntry {
    path: NodePath::from_le_bytes(&path),
    status: PlaintextStatus::Ok,
    payload: b"decrypted protobuf",
}];

let bytes = EnvelopeBuilder::new(Flags::inbound(), frame)
    .with_entries(entries.iter().copied())
    .encode_to_vec()?;

let envelope = EnvelopeRef::decode(&bytes)?;
assert_eq!(envelope.frame(), frame);
let entry = envelope.entries().next().expect("one plaintext");
assert!(entry.status.is_ok());
assert_eq!(entry.payload, b"decrypted protobuf");

§What publication froze

Contract version 1 is fixed as of 0.1.0: the envelope layout, the ten capability identifiers, and the meaning of every field an envelope carries. An adapter written against this can be linked by a host built against it and neither has to ask the other’s version.

Fixed rather than final. What may still happen inside version 1:

  • new capability identifiers, which an older reader keeps as unknown text rather than refusing — a recording declares them by name and preserves the ones it cannot resolve;
  • new reserved-flag bits and new metadata tags, the latter carrying a critical bit that says whether skipping one is safe;
  • anything additive that an existing reader can ignore without being wrong.

What would need version 2: moving a field, changing what one means, or removing anything. ContractVersion::check compares by equality for that reason — a differing major means the layout may differ, and guessing is how silent corruption starts.

A WhatsApp-side protocol change never bumps this. L0 is total: the frame crosses verbatim, so at L0 there is nothing for a protocol change to break. Which WhatsApp build a derivation came from is Provenance, tracked separately and expected to move often.

§Two version axes

ContractVersion versions this boundary; Provenance records which whatspec build an L1 derivation came from. A WhatsApp protocol change moves provenance and leaves the contract version alone — otherwise every deployed adapter would break whenever the protocol shifted. L0 totality is what makes that safe: the frame crosses verbatim, so there is nothing at L0 for a protocol change to break.

§Cost

Decoding never allocates and never copies: an EnvelopeRef borrows from the buffer it was decoded from. Encoding writes once into a caller-supplied slice, or allocates exactly once with encode_to_vec.

Re-exports§

pub use capability::Capability;
pub use capability::CapabilitySet;
pub use capability::UnmetCapabilities;
pub use envelope::EnvelopeBuilder;
pub use envelope::EnvelopeRef;
pub use envelope::HEADER_LEN;
pub use envelope::PlaintextEntry;
pub use error::DecodeError;
pub use error::EncodeError;
pub use error::Field;
pub use flags::Direction;
pub use flags::Flags;
pub use flags::FrameOrigin;
pub use path::NodePath;
pub use provenance::Provenance;
pub use provenance::ProvenanceCheck;
pub use status::PlaintextStatus;
pub use version::ContractVersion;
pub use version::VersionMismatch;

Modules§

capability
What an adapter can and cannot do, declared rather than discovered.
envelope
The L0-plain envelope: frame bytes verbatim plus a plaintext side table.
error
Decode failures.
flags
The envelope flag word.
path
Addressing a node inside a frame.
provenance
Which whatspec build an L1 derivation came from.
status
Outcome of one decryption attempt.
version
Contract versioning.