Expand description
What a wa-wire adapter must provide, and the plumbing every Rust adapter
shares.
An adapter is the thin piece that lives inside an engine, observes stanzas, and hands them on. It is deliberately dumb: emit what the engine saw and stop. Everything that could be interpreted differently between engines — parsing, L1 derivation — happens host-side, once, so an adapter has nothing to diverge on and little to break when the engine moves underneath it.
§What crosses
A RawStanza is the pre-encoding shape of an envelope: the frame bytes
the engine decoded, plus any payloads it decrypted, each addressed by the
path of the node it came from.
use wa_wire_adapter::{NodePathBuf, Plaintext, RawStanza, StanzaSink};
// The adapter walked to child 0 and found an <enc> it decrypted.
let mut path = NodePathBuf::new();
path.push(0).expect("within the depth limit");
let plaintexts = [Plaintext::ok(path.as_path(), decrypted)];
let stanza = RawStanza::inbound(frame).with_plaintexts(&plaintexts);
let mut sink = |stanza: RawStanza<'_>| {
// In-process: read the frame straight out, no encoding at all.
let _ = stanza.frame;
};
sink.accept(stanza);A sink receives the stanza rather than a finished buffer, so an in-process
consumer never pays for encoding. A sidecar consumer calls
RawStanza::encode_to_vec or RawStanza::encode_into_slice itself.
§Declared, then checked
No engine can do everything, and the gaps are real: one covers the auth
phase and cannot take over dispatch, another takes over but skips
success/failure. AdapterInfo carries what an adapter claims, and
AdapterInfo::verify checks stanzas against those claims — so a
capability that stops being true fails a test instead of quietly misleading
a consumer.
§Cost
Nothing here allocates. Paths are built in a fixed-capacity buffer, frames and payloads are borrowed from the engine, and encoding — when it happens at all — writes once into a caller-supplied slice.
Re-exports§
pub use info::AdapterInfo;pub use info::Violation;pub use path::MAX_DEPTH;pub use path::NodePathBuf;pub use path::PathTooDeep;pub use send::RequestError;pub use send::RequestFuture;pub use send::SendError;pub use send::SendFuture;pub use send::StanzaRequester;pub use send::StanzaSender;pub use sink::CountingSink;pub use sink::NullSink;pub use sink::StanzaSink;pub use stanza::Plaintext;pub use stanza::RawStanza;
Modules§
- info
- What an adapter says about itself, and whether it keeps its word.
- path
- Building a node path while walking a stanza.
- send
- Sending a stanza, whichever engine is underneath.
- sink
- Where an adapter delivers stanzas.
- stanza
- What an engine hands over for one stanza.
Structs§
- Capability
Set - A set of capabilities, packed into a bitmask.
- Contract
Version - The major version of the boundary layout and negotiation rules.
- Flags
- The decoded flag word.
- Node
Path - A borrowed node path: little-endian
u16components over the envelope’s own buffer. - Provenance
- Identifies the
whatspecmanifest an L1 derivation was generated from. - Unmet
Capabilities - A consumer required capabilities the adapter does not have.
Enums§
- Capability
- One thing an adapter may or may not be able to do.
- Direction
- Which way a stanza was travelling.
- Frame
Origin - Where the frame bytes in an envelope came from.
- Plaintext
Status - Whether a plaintext entry holds usable bytes, and if not, why.