wa_wire_l1/lib.rs
1//! The L1 derivation: typed canonical events from parsed stanzas.
2//!
3//! L0 is normative and this is the derived view. Nothing appears here that is
4//! not derivable from a parsed stanza, and the derivation is **pure** — no key
5//! material, no accumulated state — which is what lets it run host-side, once,
6//! instead of being reimplemented inside every engine.
7//!
8//! ```
9//! # #[cfg(feature = "testing")] {
10//! use wa_wire_l1::{Event, derive, testing::{Fixture, parse}};
11//!
12//! let stanza = Fixture::node("receipt")
13//! .attr("id", "ABCD1234")
14//! .jid_attr("from", "5511999998888")
15//! .attr("type", "read")
16//! .build();
17//!
18//! let event = derive(&parse(&stanza)).expect("derives");
19//! assert_eq!(event.tag(), "receipt");
20//! # }
21//! ```
22//!
23//! # Generated, not written
24//!
25//! Everything in [`generated`] comes from whatspec's `incoming` domain, which
26//! describes how WhatsApp Web itself parses each stanza. The generator emits
27//! *structure* — which extraction primitive to call, in what order, into which
28//! field. The primitives live in [`extract`] and are written by hand, so a
29//! protocol change moves shapes and calls rather than rules.
30//!
31//! The output is committed rather than built, so a protocol change arrives as a
32//! reviewable diff. CI regenerates and requires no change.
33//!
34//! # What it cannot express yet
35//!
36//! [`generated::UNMODELLED_FIELDS`] names every field the generator could not
37//! emit, rather than dropping it in silence. That distinction matters: a
38//! derivation that quietly omitted a field would look complete and be wrong,
39//! and no conformance run could tell — every engine would agree on the same
40//! missing field.
41//!
42//! # Cost
43//!
44//! Deriving borrows from the frame. String fields stay as [`Value`], because
45//! the text of a packed digit run or a JID exists nowhere in the buffer to
46//! borrow; comparing and rendering them is allocation-free. Repeated children
47//! are iterators, not collections, so a caller that wants the first does not
48//! pay for the rest.
49//!
50//! [`Value`]: wa_wire_codec::Value
51
52#![no_std]
53#![cfg_attr(
54 test,
55 allow(
56 clippy::expect_used,
57 clippy::unwrap_used,
58 clippy::panic,
59 clippy::indexing_slicing,
60 clippy::arithmetic_side_effects,
61 clippy::cast_possible_truncation,
62 )
63)]
64
65extern crate alloc;
66
67pub mod content;
68pub mod error;
69pub mod extract;
70pub mod generated;
71
72// Declared here rather than from `generated/mod.rs`, which a different
73// generator emits and would drop the line on its next run — the same reason
74// `content::field` is declared where it is.
75#[path = "generated/outgoing.rs"]
76pub mod outgoing;
77pub mod provenance;
78pub mod semantic;
79
80#[cfg(any(test, feature = "testing"))]
81pub mod testing;
82
83pub use error::{DeriveError, Field};
84pub use generated::{Event, KNOWN_TAGS, PROVENANCE, SHAPE_NAMES, UNMODELLED_FIELDS, derive};
85pub use outgoing::{
86 MERGED_OUTGOING, OUTGOING_TAGS, OutgoingEvent, UNMODELLED_OUTGOING, UNREACHABLE_OUTGOING,
87 derive_outgoing,
88};
89pub use provenance::Provenance;