Skip to main content

Crate wa_wire_adapter

Crate wa_wire_adapter 

Source
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§

CapabilitySet
A set of capabilities, packed into a bitmask.
ContractVersion
The major version of the boundary layout and negotiation rules.
Flags
The decoded flag word.
NodePath
A borrowed node path: little-endian u16 components over the envelope’s own buffer.
Provenance
Identifies the whatspec manifest an L1 derivation was generated from.
UnmetCapabilities
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.
FrameOrigin
Where the frame bytes in an envelope came from.
PlaintextStatus
Whether a plaintext entry holds usable bytes, and if not, why.