plexus_client/transport.rs
1//! The transport seam: one small trait every wire implementation satisfies,
2//! and the strongly-typed method reference the generated client hands it.
3
4use crate::envelope::StreamItem;
5use crate::error::TransportError;
6use futures_core::Stream;
7use serde_json::Value;
8use std::fmt;
9use std::pin::Pin;
10
11/// A boxed stream of wire items.
12///
13/// `Send` is required off wasm32 (so native callers can `tokio::spawn` a
14/// client stream) and **not** required on wasm32, where the browser futures a
15/// transport must build on (`JsFuture`, `ReadableStreamDefaultReader`) are
16/// `!Send` by construction.
17#[cfg(not(target_arch = "wasm32"))]
18pub type ItemStream<'a> =
19 Pin<Box<dyn Stream<Item = Result<StreamItem, TransportError>> + Send + 'a>>;
20
21/// A boxed stream of wire items. See the non-wasm32 variant for the
22/// `Send`-bound rationale.
23#[cfg(target_arch = "wasm32")]
24pub type ItemStream<'a> = Pin<Box<dyn Stream<Item = Result<StreamItem, TransportError>> + 'a>>;
25
26/// A fully qualified Plexus method — the activation namespace and the method
27/// name, kept as separate fields because the transports need them
28/// differently:
29///
30/// | Transport | Uses |
31/// |---|---|
32/// | WebSocket JSON-RPC | `"{namespace}.{method}"` as the `params.method` of a `{hub}.call` subscription |
33/// | REST + SSE | `POST /rest/{namespace}/{method}` |
34/// | in-process | `namespace` selects the activation, `method` is passed to `Activation::call` |
35///
36/// A pre-joined `&str` would force every transport to re-split it, and a
37/// mis-split is silent. The generated client emits `MethodRef::new(..)` as a
38/// const, so this costs nothing at the call site.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
40pub struct MethodRef {
41 namespace: &'static str,
42 method: &'static str,
43}
44
45impl MethodRef {
46 pub const fn new(namespace: &'static str, method: &'static str) -> Self {
47 Self { namespace, method }
48 }
49
50 /// The activation namespace, e.g. `"tickets"`.
51 pub const fn namespace(&self) -> &'static str {
52 self.namespace
53 }
54
55 /// The bare method name, e.g. `"watch"`.
56 pub const fn method(&self) -> &'static str {
57 self.method
58 }
59
60 /// The dotted form the hub's `call` method expects, e.g.
61 /// `"tickets.watch"`.
62 pub fn qualified(&self) -> String {
63 format!("{}.{}", self.namespace, self.method)
64 }
65}
66
67impl fmt::Display for MethodRef {
68 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
69 write!(f, "{}.{}", self.namespace, self.method)
70 }
71}
72
73/// One Plexus wire implementation.
74///
75/// Every method call on a generated client turns into exactly one
76/// `Transport::call`. The returned stream yields the response items in order
77/// and ends after the terminal one (`done` or `error`); a transport that
78/// loses the connection mid-stream reports it as a
79/// [`TransportError`](crate::TransportError) item rather than by ending
80/// silently.
81///
82/// Implementations must **not** interpret `params` — the generated client
83/// has already built the by-name object the schema expects.
84pub trait Transport {
85 fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_>;
86}
87
88/// So a client can be handed `&T`, `Arc<T>`, `Box<T>`, … interchangeably.
89impl<T: Transport + ?Sized> Transport for &T {
90 fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_> {
91 (**self).call(method, params)
92 }
93}
94
95impl<T: Transport + ?Sized> Transport for Box<T> {
96 fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_> {
97 (**self).call(method, params)
98 }
99}
100
101impl<T: Transport + ?Sized> Transport for std::rc::Rc<T> {
102 fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_> {
103 (**self).call(method, params)
104 }
105}
106
107impl<T: Transport + ?Sized> Transport for std::sync::Arc<T> {
108 fn call(&self, method: MethodRef, params: Value) -> ItemStream<'_> {
109 (**self).call(method, params)
110 }
111}