Skip to main content

plexus_client/
lib.rs

1//! # plexus-client
2//!
3//! The **wasm-safe client runtime** for Plexus RPC: the wire envelope a
4//! client receives, the `Transport` seam every wire implementation
5//! satisfies, and the decoder that turns wire items into an activation's own
6//! typed events.
7//!
8//! This crate is the runtime half of `#[plexus_macros::activation(client)]`.
9//! The macro emits the per-activation typed client; everything the emitted
10//! code leans on lives here, so the generated code stays small and every
11//! transport is written once for all activations.
12//!
13//! ## Why it is a separate crate
14//!
15//! `plexus-core` is the server: tokio (full), jsonrpsee, rmcp, http. None of
16//! that builds for `wasm32-unknown-unknown`, and gating ~9k lines of
17//! `plexus.rs`/`schema.rs` behind features to make it would be a far larger
18//! and riskier change than extracting the ~400 lines a *client* actually
19//! needs. So the client contract lives here, with four dependencies —
20//! `serde`, `serde_json`, `futures-core`, `futures-util` — all of which
21//! build for wasm32.
22//!
23//! `cargo build -p plexus-client --target wasm32-unknown-unknown` is the
24//! regression gate on that claim.
25//!
26//! ## The shape
27//!
28//! ```text
29//!   generated client method
30//!         │  builds the by-name params object from typed arguments (Params)
31//!         ▼
32//!   Transport::call(MethodRef, Value) ──► ItemStream          (wire items)
33//!         │
34//!         ├─ one-item method  ── call_one ──► Result<I, ClientError>
35//!         └─ many-item method ──────────────► MethodStream<'_, I, P, {Ns}Event>
36//!                                               ├─ Stream<Item = Result<I, ClientError>>   (progress dropped)
37//!                                               ├─ .with_progress() → Result<Frame<I, P>, ClientError>
38//!                                               └─ .events()        → Result<{Ns}Event, ClientError>
39//! ```
40//!
41//! `I` is the method's item — a plain `T`, or `Result<T, E>` decoded from its
42//! `{"ok"}` / `{"err"}` wire form — `P` its progress type ([`NoProgress`] when
43//! it declares none) and `{Ns}Event` the activation's aggregate, which the
44//! macro derives beside the client.
45//!
46//! Two layers stay apart the whole way down (RETURNS-1 decision 8): a
47//! [`ClientError`] is the call failing — the connection
48//! ([`ClientError::Transport`]) or the server's typed error frame
49//! ([`ClientError::Remote`]`(`[`RemoteError`]`)`) — and an `err` item is the
50//! activation saying no, which arrives as a value. `?` is the call failing;
51//! a match on the item is the activation's answer. See [`error`].
52//!
53//! ## Transports
54//!
55//! [`MemoryTransport`] ships here because it is the only transport with no
56//! I/O and therefore the only one that is wasm-safe by construction; it is
57//! the test double. The in-process transport lives on the `plexus-core`
58//! side, because it drives a real `Activation`.
59//!
60//! [`WsTransport`] — WebSocket JSON-RPC, the transport that carries the full
61//! envelope — ships here too, but **behind a feature**, because a socket is
62//! I/O and the four-dependency core must stay the default:
63//!
64//! | Feature | Backend | Target |
65//! |---|---|---|
66//! | *(none)* | — | the wasm-clean core: `serde`, `serde_json`, `futures-core`, `futures-util` |
67//! | `ws-native` | `tokio-tungstenite` | native |
68//! | `ws-web` | `web_sys::WebSocket` | `wasm32-unknown-unknown` |
69//!
70//! ## Many streams as one
71//!
72//! [`watch`] merges a tuple of method streams into one whose item is exactly
73//! the union of theirs — `watch((tickets, chats, deployments))` yields
74//! `Watched3<A, B, C>`, and dropping it drops (on a `WsTransport`:
75//! unsubscribes) each (RETURNS-38). See [`watch`](mod@watch).
76//!
77//! Both features expose the same `WsTransport` type and the same
78//! `WsTransport::connect(url, hub_namespace)`, so a consumer picks the
79//! backend in `Cargo.toml` and changes no code. See [`ws`].
80//!
81//! ## The 0.7 vocabulary
82//!
83//! The types every party to a precise-returns call names — the server
84//! author, the macro, the generated client, the generators' mirrors — live
85//! here once, because this is the one crate all of them link:
86//!
87//! | Type | What it is | On the wire |
88//! |---|---|---|
89//! | [`Progress<T, P = Note>`](Progress) | a method's item when it reports progress: `Update(P)` \| `Item(T)` | never as a whole: `Update` → progress frame, `Item` → data frame |
90//! | [`Note`] | the default progress type | `{"message": …, "percentage": …}` |
91//! | [`Frame<I, P>`](Frame) | what an opted-in client stream yields: `Item(I)` \| `Progress(P)` | client-side only |
92//! | [`RemoteError`] (+ [`ParamProblem`], [`DenyReason`]) | why a call failed — typed, exhaustive | `kind`-tagged object |
93//! | [`wire_result`] | serde `with` module for a Result item | `{"ok": t}` \| `{"err": e}` |
94//!
95//! `Note` and `RemoteError` implement `schemars::JsonSchema` under the
96//! `schema` feature (off by default: a wasm32 consumer that only decodes
97//! needs none of it).
98
99#![forbid(unsafe_code)]
100#![deny(missing_debug_implementations)]
101
102pub mod contract;
103pub mod decode;
104pub mod envelope;
105pub mod error;
106pub mod frame;
107pub mod lift;
108pub mod memory;
109pub mod method_stream;
110pub mod params;
111pub mod progress;
112pub mod remote_error;
113pub mod route;
114/// RETURNS-36: a peer on plexus-wire's spec as main wrote it, read as 0.8.
115pub mod spec05;
116pub mod transport;
117/// PERF.115-43: `#[derive(plexus_macros::Deserialize)]`'s runtime, reached
118/// through `__rt::type_first`.
119mod type_first;
120pub mod watch;
121pub mod wire_result;
122
123#[cfg(any(feature = "ws-native", feature = "ws-web"))]
124pub mod ws;
125
126pub use contract::{
127    error_events, into_events, owned_call, owned_call_raw, owned_call_raw_with_input, trait_many, trait_one, trait_one_with_input, trait_progress, trait_result_progress,
128    BoxFuture, BoxStream, FromClientError, MaybeSend,
129};
130pub use decode::{decode, decode_raw, decode_result, decode_with_progress};
131pub use envelope::{Content, RawItem, StreamItem, StreamMetadata};
132pub use error::{ClientError, NameRefusal, TransportError, TransportErrorKind};
133pub use frame::Frame;
134pub use lift::{Aggregated, HasClient, Lift, Named, Root, Static, Wrap};
135pub use route::Route;
136pub use memory::MemoryTransport;
137pub use method_stream::{call_one, call_one_with_input, Decoder, EventOf, Events, MethodStream, NoProgress, WithProgress};
138pub use params::Params;
139pub use progress::{Note, Progress};
140pub use remote_error::{DenyReason, OtherError, ParamProblem, RemoteError};
141pub use transport::{encode_input, InputItem, InputItems, ItemStream, MethodRef, RawItemStream, RoutePath, Transport};
142pub use watch::{
143    watch, watch_with, Errors, Fallible, StopOnError, Watch, Watched10, Watched11, Watched12, Watched2, Watched3,
144    Watched4, Watched5, Watched6, Watched7, Watched8, Watched9, Watching10, Watching11, Watching12, Watching2,
145    Watching3, Watching4, Watching5, Watching6, Watching7, Watching8, Watching9,
146};
147
148#[cfg(any(feature = "ws-native", feature = "ws-web"))]
149pub use ws::WsTransport;
150
151/// Re-exported so generated client code never needs `serde` or `serde_json`
152/// in the consuming crate's own `Cargo.toml`: the `{Ns}Event` aggregate
153/// derives through `__rt::serde` (`#[serde(crate = "…")]`).
154#[doc(hidden)]
155pub mod __rt {
156    pub use serde;
157    pub use serde_json;
158    pub use futures_core::Stream;
159
160    /// PERF.115-43: what `#[derive(plexus_macros::Deserialize)]` emits calls:
161    /// an internally tagged enum read with its tag first, serde's buffered
162    /// read where it is not (see the module's source, `type_first.rs`).
163    pub mod type_first {
164        pub use crate::type_first::{deserialize, TypeFirst};
165    }
166}