Expand description
§plexus-client
The wasm-safe client runtime for Plexus RPC: the wire envelope a
client receives, the Transport seam every wire implementation
satisfies, and the decoder that turns wire items into an activation’s own
typed events.
This crate is the runtime half of #[plexus_macros::activation(client)].
The macro emits the per-activation typed client; everything the emitted
code leans on lives here, so the generated code stays small and every
transport is written once for all activations.
§Why it is a separate crate
plexus-core is the server: tokio (full), jsonrpsee, rmcp, http. None of
that builds for wasm32-unknown-unknown, and gating ~9k lines of
plexus.rs/schema.rs behind features to make it would be a far larger
and riskier change than extracting the ~400 lines a client actually
needs. So the client contract lives here, with four dependencies —
serde, serde_json, futures-core, futures-util — all of which
build for wasm32.
cargo build -p plexus-client --target wasm32-unknown-unknown is the
regression gate on that claim.
§The shape
generated client method
│ builds the by-name params object from typed arguments
▼
Transport::call(MethodRef, Value) ──► ItemStream (wire items)
│
▼
decode::<E>(..) ──► EventStream<E> (typed events)Two failure layers stay apart the whole way down: a
TransportError is the connection failing, a
ClientError::Remote is the server answering with an in-band error
item. See error.
§Transports
MemoryTransport ships here because it is the only transport with no
I/O and therefore the only one that is wasm-safe by construction; it is
the test double. The in-process transport lives on the plexus-core
side, because it drives a real Activation.
[WsTransport] — WebSocket JSON-RPC, the transport that carries the full
envelope — ships here too, but behind a feature, because a socket is
I/O and the four-dependency core must stay the default:
| Feature | Backend | Target |
|---|---|---|
| (none) | — | the wasm-clean core: serde, serde_json, futures-core, futures-util |
ws-native | tokio-tungstenite | native |
ws-web | web_sys::WebSocket | wasm32-unknown-unknown |
Both features expose the same WsTransport type and the same
WsTransport::connect(url, hub_namespace), so a consumer picks the
backend in Cargo.toml and changes no code. See [ws].
Re-exports§
pub use decode::collect_data;pub use decode::decode;pub use decode::error_stream;pub use decode::EventStream;pub use envelope::StreamItem;pub use envelope::StreamMetadata;pub use error::ClientError;pub use error::TransportError;pub use error::TransportErrorKind;pub use event::ClientEvent;pub use memory::MemoryTransport;pub use transport::ItemStream;pub use transport::MethodRef;pub use transport::Transport;
Modules§
- decode
- Turning a wire-item stream into a typed event stream.
- envelope
- The Plexus wire envelope, as a client sees it.
- error
- The two error layers a Plexus client sees, kept apart by type.
- event
- What a typed client hands its caller.
- memory
MemoryTransport— a scriptedTransportwith no server behind it.- transport
- The transport seam: one small trait every wire implementation satisfies, and the strongly-typed method reference the generated client hands it.