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 |
§Many streams as one
[watch] merges a tuple of method streams into one whose item is exactly
the union of theirs — watch((tickets, chats, deployments)) yields
Watched3<A, B, C>, and dropping it drops (on a WsTransport:
unsubscribes) each (RETURNS-38). See watch.
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 contract::error_events;pub use contract::into_events;pub use contract::owned_call;pub use contract::BoxStream;pub use contract::FromClientError;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;pub use watch::watch;pub use watch::watch_with;pub use watch::Errors;pub use watch::Fallible;pub use watch::StopOnError;pub use watch::Watch;pub use watch::Watched10;pub use watch::Watched11;pub use watch::Watched12;pub use watch::Watched2;pub use watch::Watched3;pub use watch::Watched4;pub use watch::Watched5;pub use watch::Watched6;pub use watch::Watched7;pub use watch::Watched8;pub use watch::Watched9;pub use watch::Watching10;pub use watch::Watching11;pub use watch::Watching12;pub use watch::Watching2;pub use watch::Watching3;pub use watch::Watching4;pub use watch::Watching5;pub use watch::Watching6;pub use watch::Watching7;pub use watch::Watching8;pub use watch::Watching9;
Modules§
- contract
- MACRO-13 · what a trait the activation macro emits leans on.
- 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.
- watch
watch((a, b, c))— several method streams in, one stream out whose item is exactly the union of theirs (RETURNS-38).