Skip to main content

Crate plexus_client

Crate plexus_client 

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

FeatureBackendTarget
(none)—the wasm-clean core: serde, serde_json, futures-core, futures-util
ws-nativetokio-tungstenitenative
ws-webweb_sys::WebSocketwasm32-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 scripted Transport with 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).