wa_wire_adapter/lib.rs
1//! What a `wa-wire` adapter must provide, and the plumbing every Rust adapter
2//! shares.
3//!
4//! An adapter is the thin piece that lives inside an engine, observes stanzas,
5//! and hands them on. It is deliberately dumb: emit what the engine saw and
6//! stop. Everything that could be interpreted differently between engines —
7//! parsing, L1 derivation — happens host-side, once, so an adapter has nothing
8//! to diverge on and little to break when the engine moves underneath it.
9//!
10//! # What crosses
11//!
12//! A [`RawStanza`] is the pre-encoding shape of an envelope: the frame bytes
13//! the engine decoded, plus any payloads it decrypted, each addressed by the
14//! path of the node it came from.
15//!
16//! ```
17//! use wa_wire_adapter::{NodePathBuf, Plaintext, RawStanza, StanzaSink};
18//!
19//! # fn example(frame: &[u8], decrypted: &[u8]) {
20//! // The adapter walked to child 0 and found an <enc> it decrypted.
21//! let mut path = NodePathBuf::new();
22//! path.push(0).expect("within the depth limit");
23//! let plaintexts = [Plaintext::ok(path.as_path(), decrypted)];
24//!
25//! let stanza = RawStanza::inbound(frame).with_plaintexts(&plaintexts);
26//!
27//! let mut sink = |stanza: RawStanza<'_>| {
28//! // In-process: read the frame straight out, no encoding at all.
29//! let _ = stanza.frame;
30//! };
31//! sink.accept(stanza);
32//! # }
33//! ```
34//!
35//! A sink receives the stanza rather than a finished buffer, so an in-process
36//! consumer never pays for encoding. A sidecar consumer calls
37//! [`RawStanza::encode_to_vec`] or [`RawStanza::encode_into_slice`] itself.
38//!
39//! # Declared, then checked
40//!
41//! No engine can do everything, and the gaps are real: one covers the auth
42//! phase and cannot take over dispatch, another takes over but skips
43//! `success`/`failure`. [`AdapterInfo`] carries what an adapter claims, and
44//! [`AdapterInfo::verify`] checks stanzas against those claims — so a
45//! capability that stops being true fails a test instead of quietly misleading
46//! a consumer.
47//!
48//! # Cost
49//!
50//! Nothing here allocates. Paths are built in a fixed-capacity buffer, frames
51//! and payloads are borrowed from the engine, and encoding — when it happens at
52//! all — writes once into a caller-supplied slice.
53
54#![no_std]
55#![cfg_attr(
56 test,
57 allow(
58 clippy::expect_used,
59 clippy::unwrap_used,
60 clippy::panic,
61 clippy::indexing_slicing,
62 clippy::arithmetic_side_effects,
63 clippy::cast_possible_truncation,
64 )
65)]
66
67#[cfg(feature = "alloc")]
68extern crate alloc;
69
70pub mod info;
71pub mod path;
72#[cfg(feature = "alloc")]
73pub mod send;
74pub mod sink;
75pub mod stanza;
76
77pub use info::{AdapterInfo, Violation};
78pub use path::{MAX_DEPTH, NodePathBuf, PathTooDeep};
79#[cfg(feature = "alloc")]
80pub use send::{RequestError, RequestFuture, SendError, SendFuture, StanzaRequester, StanzaSender};
81pub use sink::{CountingSink, NullSink, StanzaSink};
82pub use stanza::{Plaintext, RawStanza};
83
84// Re-exported so an adapter needs one dependency, not two.
85pub use wa_wire_contract::{
86 Capability, CapabilitySet, ContractVersion, Direction, Flags, FrameOrigin, NodePath,
87 PlaintextStatus, Provenance, UnmetCapabilities,
88};