Skip to main content

plexus_client/
contract.rs

1//! What a trait the activation macro emits leans on (MACRO-13, RETURNS-36),
2//! and what is left of the client-implements-the-trait rule (RETURNS-47).
3//!
4//! `#[plexus_macros::activation(trait = "Foo")]` (or a bodiless contract)
5//! emits `trait Foo`, each method under its own return type, boxed: a
6//! one-item method's a [`BoxFuture`] of its item, a stream form's a
7//! [`BoxStream`] of its items. The activation implements it; the client does
8//! not (RETURNS-47, superseding RETURNS-43): its methods answer
9//! `Result<T, ClientError>` or a `MethodStream`, so a client failure is a
10//! `Result` its caller handles, never a value folded into `T`, and every item
11//! type works — `u64`, `bool`, `Vec<T>` — with nothing to implement.
12//!
13//! [`FromClientError`] is what that rule asked of every item type. Nothing
14//! the macro emits asks for it any more; it stays for the code that
15//! implements it.
16
17use crate::error::ClientError;
18use futures_core::Stream;
19use std::future::Future;
20use std::pin::Pin;
21
22/// A boxed stream of `T` — the return type of every method of a trait the
23/// activation macro emits. `Send` off wasm32, as [`crate::ItemStream`] is; on
24/// wasm32 the browser's futures are `!Send`, so the bound is dropped.
25#[cfg(not(target_arch = "wasm32"))]
26pub type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + Send + 'a>>;
27
28/// A boxed stream of `T`. See the non-wasm32 variant.
29#[cfg(target_arch = "wasm32")]
30pub type BoxStream<'a, T> = Pin<Box<dyn Stream<Item = T> + 'a>>;
31
32/// A boxed future of `T` — what a one-item method of an emitted trait
33/// returns (RETURNS-36). `Send` off wasm32, as [`BoxStream`] is.
34#[cfg(not(target_arch = "wasm32"))]
35pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + Send + 'a>>;
36
37/// A boxed future of `T`. See the non-wasm32 variant.
38#[cfg(target_arch = "wasm32")]
39pub type BoxFuture<'a, T> = Pin<Box<dyn Future<Output = T> + 'a>>;
40
41/// `Send` off wasm32, nothing on it: the bound a client puts on what it
42/// moves into a boxed future or stream (an `Input`'s items, BIDIR-6).
43#[cfg(not(target_arch = "wasm32"))]
44pub trait MaybeSend: Send {}
45#[cfg(not(target_arch = "wasm32"))]
46impl<T: Send> MaybeSend for T {}
47/// See the non-wasm32 variant.
48#[cfg(target_arch = "wasm32")]
49pub trait MaybeSend {}
50#[cfg(target_arch = "wasm32")]
51impl<T> MaybeSend for T {}
52
53/// An event type that can carry a client failure in band.
54///
55/// RETURNS-47: no longer required of anything — the generated client
56/// implements no trait and answers `Result<T, ClientError>` — and kept for
57/// the code that implements it. Before, the client's implementation of an
58/// emitted trait yielded a client failure as `E::from_client_error(err)`.
59/// An event enum carried it as its in-band error variant:
60///
61/// ```
62/// # #[derive(Debug)] enum EchoEvent { Said { text: String }, Error { message: String } }
63/// impl plexus_client::FromClientError for EchoEvent {
64///     fn from_client_error(error: plexus_client::ClientError) -> Self {
65///         EchoEvent::Error { message: error.to_string() }
66///     }
67/// }
68/// ```
69pub trait FromClientError {
70    /// The event that stands for `error`. It is the last item of its stream.
71    fn from_client_error(error: ClientError) -> Self;
72}
73
74/// A Result item carries a client failure as its error (RETURNS-36).
75impl<T, E: FromClientError> FromClientError for Result<T, E> {
76    fn from_client_error(error: ClientError) -> Self {
77        Err(E::from_client_error(error))
78    }
79}
80
81/// A progress item carries a client failure as its item (RETURNS-36).
82impl<T: FromClientError, P> FromClientError for crate::progress::Progress<T, P> {
83    fn from_client_error(error: ClientError) -> Self {
84        crate::progress::Progress::Item(T::from_client_error(error))
85    }
86}
87
88/// A string carries a client failure as its message.
89impl FromClientError for String {
90    fn from_client_error(error: ClientError) -> Self {
91        error.to_string()
92    }
93}