1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
//! # 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
//!
//! ```text
//! 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`](mod@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>`](Progress) | 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>`](Frame) | 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).
/// RETURNS-36: a peer on plexus-wire's spec as main wrote it, read as 0.8.
/// PERF.115-43: `#[derive(plexus_macros::Deserialize)]`'s runtime, reached
/// through `__rt::type_first`.
pub use ;
pub use ;
pub use ;
pub use ;
pub use Frame;
pub use ;
pub use Route;
pub use MemoryTransport;
pub use ;
pub use Params;
pub use ;
pub use ;
pub use ;
pub use ;
pub use WsTransport;
/// Re-exported so generated client code never needs `serde` or `serde_json`
/// in the consuming crate's own `Cargo.toml`: the `{Ns}Event` aggregate
/// derives through `__rt::serde` (`#[serde(crate = "…")]`).