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

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].

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

TypeWhat it isOn 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
Notethe 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, exhaustivekind-tagged object
wire_resultserde 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::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 untyped::FromRoute;
pub use untyped::ShapeCheck;
pub use untyped::Untyped;
pub use parent::ParentHash;
pub use parent::ParentShape;
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
What a trait the activation macro emits leans on (MACRO-13, RETURNS-36), and what is left of the client-implements-the-trait rule (RETURNS-47).
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 scripted Transport with 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.
parent
PERF.115-43: #[derive(plexus_macros::Deserialize)]’s runtime, reached through __rt::type_first. NEST-16 · what a graft’s macro reads of its parent’s client.
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.
untyped
NEST-14 · a client for a node whose interface is not known when the program is written: an untyped peer slot, a #[child(opaque)], a tree mounted at run time.
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}.