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 (Params)
▼
Transport::call(MethodRef, Value) ──► ItemStream (wire items)
│
├─ one-item method ── call_one ──► Result<I, ClientError>
└─ many-item method ──────────────► MethodStream<'_, I, P, {Ns}Event>
├─ Stream<Item = Result<I, ClientError>> (progress dropped)
├─ .with_progress() → Result<Frame<I, P>, ClientError>
└─ .events() → Result<{Ns}Event, ClientError>I is the method’s item — a plain T, or Result<T, E> decoded from its
{"ok"} / {"err"} wire form — P its progress type (NoProgress when
it declares none) and {Ns}Event the activation’s aggregate, which the
macro derives beside the client.
Two layers stay apart the whole way down (RETURNS-1 decision 8): a
ClientError is the call failing — the connection
(ClientError::Transport) or the server’s typed error frame
(ClientError::Remote(RemoteError)) — and an err item is the
activation saying no, which arrives as a value. ? is the call failing;
a match on the item is the activation’s answer. 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].
§The 0.7 vocabulary
The types every party to a precise-returns call names — the server author, the macro, the generated client, the generators’ mirrors — live here once, because this is the one crate all of them link:
| Type | What it is | On the wire |
|---|---|---|
Progress<T, P = Note> | a method’s item when it reports progress: Update(P) | Item(T) | never as a whole: Update → progress frame, Item → data frame |
Note | the default progress type | {"message": …, "percentage": …} |
Frame<I, P> | what an opted-in client stream yields: Item(I) | Progress(P) | client-side only |
RemoteError (+ ParamProblem, DenyReason) | why a call failed — typed, exhaustive | kind-tagged object |
wire_result | serde with module for a Result item | {"ok": t} | {"err": e} |
Note and RemoteError implement schemars::JsonSchema under the
schema feature (off by default: a wasm32 consumer that only decodes
needs none of it).
Re-exports§
pub use contract::error_events;pub use contract::into_events;pub use contract::owned_call;pub use contract::owned_call_raw;pub use contract::owned_call_raw_with_input;pub use contract::trait_many;pub use contract::trait_one;pub use contract::trait_one_with_input;pub use contract::trait_progress;pub use contract::trait_result_progress;pub use contract::BoxFuture;pub use contract::BoxStream;pub use contract::FromClientError;pub use contract::MaybeSend;pub use decode::decode;pub use decode::decode_raw;pub use decode::decode_result;pub use decode::decode_with_progress;pub use envelope::Content;pub use envelope::RawItem;pub use envelope::StreamItem;pub use envelope::StreamMetadata;pub use error::ClientError;pub use error::NameRefusal;pub use error::TransportError;pub use error::TransportErrorKind;pub use frame::Frame;pub use lift::Aggregated;pub use lift::HasClient;pub use lift::Lift;pub use lift::Named;pub use lift::Root;pub use lift::Static;pub use lift::Wrap;pub use route::Route;pub use memory::MemoryTransport;pub use method_stream::call_one;pub use method_stream::call_one_with_input;pub use method_stream::Decoder;pub use method_stream::EventOf;pub use method_stream::Events;pub use method_stream::MethodStream;pub use method_stream::NoProgress;pub use method_stream::WithProgress;pub use params::Params;pub use progress::Note;pub use progress::Progress;pub use remote_error::DenyReason;pub use remote_error::OtherError;pub use remote_error::ParamProblem;pub use remote_error::RemoteError;pub use transport::encode_input;pub use transport::InputItem;pub use transport::InputItems;pub use transport::ItemStream;pub use transport::MethodRef;pub use transport::RawItemStream;pub use transport::RoutePath;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
- The macro-free typed path: a transport’s wire items, typed by hand.
- envelope
- The Plexus wire envelope, as a client sees it.
- error
- The two error layers a Plexus client sees, kept apart by type.
- frame
- What a client stream yields once its caller opts into progress.
- lift
- RETURNS-46 · the aggregate up the tree: how a call made through a parent’s client yields the parent’s aggregate.
- memory
MemoryTransport— a scriptedTransportwith no server behind it.- method_
stream - What a many-item method’s client call returns:
MethodStream. - params
- The by-name params object a typed call sends.
- progress
- Progress as part of a method’s return type.
- remote_
error - The typed, exhaustive vocabulary of call failures.
- route
- RETURNS-46 · where a generated client’s calls go, and whether they may.
- spec05
- RETURNS-36: a peer on plexus-wire’s spec as main wrote it, read as 0.8.
RETURNS-36 · a peer on plexus-wire’s spec as main wrote it (spec/03, 05),
read into 0.8’s shapes — one rule for the client and plexus-core’s child
seam (its
remote_child::peer), never guessed from anything the peer did not say: - 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).- wire_
result - The wire encoding of a Result item:
Ok(t)⇄{"ok": t},Err(e)⇄{"err": e}.