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
31//!         ▼
32//!   Transport::call(MethodRef, Value) ──► ItemStream    (wire items)
33//!         │
34//!         ▼
35//!   decode::<E>(..)                   ──► EventStream<E> (typed events)
36//! ```
37//!
38//! Two failure layers stay apart the whole way down: a
39//! [`TransportError`] is the connection failing, a
40//! [`ClientError::Remote`] is the server answering with an in-band `error`
41//! item. See [`error`].
42//!
43//! ## Transports
44//!
45//! [`MemoryTransport`] ships here because it is the only transport with no
46//! I/O and therefore the only one that is wasm-safe by construction; it is
47//! the test double. The in-process transport lives on the `plexus-core`
48//! side, because it drives a real `Activation`.
49//!
50//! [`WsTransport`] — WebSocket JSON-RPC, the transport that carries the full
51//! envelope — ships here too, but **behind a feature**, because a socket is
52//! I/O and the four-dependency core must stay the default:
53//!
54//! | Feature | Backend | Target |
55//! |---|---|---|
56//! | *(none)* | — | the wasm-clean core: `serde`, `serde_json`, `futures-core`, `futures-util` |
57//! | `ws-native` | `tokio-tungstenite` | native |
58//! | `ws-web` | `web_sys::WebSocket` | `wasm32-unknown-unknown` |
59//!
60//! Both features expose the same `WsTransport` type and the same
61//! `WsTransport::connect(url, hub_namespace)`, so a consumer picks the
62//! backend in `Cargo.toml` and changes no code. See [`ws`].
63
64#![forbid(unsafe_code)]
65#![deny(missing_debug_implementations)]
66
67pub mod decode;
68pub mod envelope;
69pub mod error;
70pub mod event;
71pub mod memory;
72pub mod transport;
73
74#[cfg(any(feature = "ws-native", feature = "ws-web"))]
75pub mod ws;
76
77pub use decode::{collect_data, decode, error_stream, EventStream};
78pub use envelope::{StreamItem, StreamMetadata};
79pub use error::{ClientError, TransportError, TransportErrorKind};
80pub use event::ClientEvent;
81pub use memory::MemoryTransport;
82pub use transport::{ItemStream, MethodRef, Transport};
83
84#[cfg(any(feature = "ws-native", feature = "ws-web"))]
85pub use ws::WsTransport;
86
87/// Re-exported so generated client code never needs `serde_json` in the
88/// consuming crate's own `Cargo.toml`.
89#[doc(hidden)]
90pub mod __rt {
91    pub use serde_json;
92}