Skip to main content

wa_wire_contract/
lib.rs

1//! The normative `wa-wire` boundary format and negotiation types.
2//!
3//! Every WhatsApp Web client library speaks the same wire protocol and exposes
4//! a different API. `wa-wire` makes the thing they already share — the wire
5//! itself — the interface, so an integration written once runs on any
6//! conforming engine.
7//!
8//! # The layer model
9//!
10//! - **L0-wire** — the stanza as it arrived, payload still encrypted.
11//! - **L0-plain** — that frame plus the plaintexts the engine decrypted.
12//! - **L1** — typed canonical events, derived from L0-plain.
13//!
14//! L0 is normative and L1 is a derived view: nothing may appear in L1 that is
15//! not derivable from L0-plain. `L0-plain → L1` is a pure function — protobuf
16//! parsing and mapping, no keys and no accumulated state — which is why it runs
17//! host-side, once, instead of being reimplemented per engine.
18//!
19//! # What crosses the boundary
20//!
21//! The frame bytes already exist inside every engine at the moment it decodes,
22//! and the frame never contained the plaintext anyway — `<enc>` carries
23//! ciphertext, and the plaintext arrives later from Signal. So an envelope is
24//! **the frame verbatim plus a side table of plaintexts**, each addressed by
25//! the path of the node it belongs to.
26//!
27//! Nothing is re-encoded, so there is no encoding to choose. The frame is
28//! parsed exactly once, host-side, and only if something subscribed to L1.
29//!
30//! ```
31//! use wa_wire_contract::{EnvelopeBuilder, EnvelopeRef, Flags, NodePath,
32//!                        PlaintextEntry, PlaintextStatus};
33//!
34//! // A <message> whose single <enc> child decrypted successfully.
35//! let frame = b"\xf8\x03...";                 // unpacked binary-node bytes
36//! let path = 0u16.to_le_bytes();              // child 0 of the root
37//! let entries = [PlaintextEntry {
38//!     path: NodePath::from_le_bytes(&path),
39//!     status: PlaintextStatus::Ok,
40//!     payload: b"decrypted protobuf",
41//! }];
42//!
43//! let bytes = EnvelopeBuilder::new(Flags::inbound(), frame)
44//!     .with_entries(entries.iter().copied())
45//!     .encode_to_vec()?;
46//!
47//! let envelope = EnvelopeRef::decode(&bytes)?;
48//! assert_eq!(envelope.frame(), frame);
49//! let entry = envelope.entries().next().expect("one plaintext");
50//! assert!(entry.status.is_ok());
51//! assert_eq!(entry.payload, b"decrypted protobuf");
52//! # Ok::<(), Box<dyn core::error::Error>>(())
53//! ```
54//!
55//! # What publication froze
56//!
57//! Contract version 1 is fixed as of 0.1.0: the envelope layout, the ten
58//! capability identifiers, and the meaning of every field an envelope carries.
59//! An adapter written against this can be linked by a host built against it
60//! and neither has to ask the other's version.
61//!
62//! Fixed rather than final. What may still happen inside version 1:
63//!
64//! - **new capability identifiers**, which an older reader keeps as unknown
65//!   text rather than refusing — a recording declares them by name and
66//!   preserves the ones it cannot resolve;
67//! - **new reserved-flag bits and new metadata tags**, the latter carrying a
68//!   critical bit that says whether skipping one is safe;
69//! - anything additive that an existing reader can ignore without being wrong.
70//!
71//! What would need version 2: moving a field, changing what one means, or
72//! removing anything. `ContractVersion::check` compares by equality for that
73//! reason — a differing major means the layout may differ, and guessing is how
74//! silent corruption starts.
75//!
76//! **A WhatsApp-side protocol change never bumps this.** L0 is total: the frame
77//! crosses verbatim, so at L0 there is nothing for a protocol change to break.
78//! Which WhatsApp build a derivation came from is [`Provenance`], tracked
79//! separately and expected to move often.
80//!
81//! # Two version axes
82//!
83//! [`ContractVersion`] versions *this* boundary; [`Provenance`] records which
84//! `whatspec` build an L1 derivation came from. A WhatsApp protocol change
85//! moves provenance and leaves the contract version alone — otherwise every
86//! deployed adapter would break whenever the protocol shifted. L0 totality is
87//! what makes that safe: the frame crosses verbatim, so there is nothing at L0
88//! for a protocol change to break.
89//!
90//! # Cost
91//!
92//! Decoding never allocates and never copies: an [`EnvelopeRef`] borrows from
93//! the buffer it was decoded from. Encoding writes once into a caller-supplied
94//! slice, or allocates exactly once with [`encode_to_vec`].
95//!
96//! [`encode_to_vec`]: EnvelopeBuilder::encode_to_vec
97
98#![no_std]
99// Tests assert on known-good fixtures, so panicking on a broken one is the
100// point. The library itself stays free of these.
101#![cfg_attr(
102    test,
103    allow(
104        clippy::expect_used,
105        clippy::unwrap_used,
106        clippy::panic,
107        clippy::indexing_slicing,
108        clippy::arithmetic_side_effects,
109        clippy::cast_possible_truncation,
110    )
111)]
112
113#[cfg(feature = "alloc")]
114extern crate alloc;
115
116pub mod capability;
117pub mod envelope;
118pub mod error;
119pub mod flags;
120pub mod path;
121pub mod provenance;
122pub mod status;
123pub mod version;
124
125pub use capability::{Capability, CapabilitySet, UnmetCapabilities};
126pub use envelope::{EnvelopeBuilder, EnvelopeRef, HEADER_LEN, PlaintextEntry};
127pub use error::{DecodeError, EncodeError, Field};
128pub use flags::{Direction, Flags, FrameOrigin};
129pub use path::NodePath;
130pub use provenance::{Provenance, ProvenanceCheck};
131pub use status::PlaintextStatus;
132pub use version::{ContractVersion, VersionMismatch};