Skip to main content

ice_rpc_rx/
lib.rs

1//! Reactive layer of ice-rpc: the stream vocabulary, the operators, the
2//! multicast primitive and the execution facade they need.
3//!
4//! This crate is the foundation of `ice-rpc`. It owns [`Observable`], [`Event`],
5//! [`ObservableError`] and [`RpcError`], and it knows **nothing about the wire**:
6//! no framing, no serialization format, no transport. `ice-rpc` depends on it and
7//! re-exports every item under its historical path, so a consumer of `ice-rpc`
8//! sees one single stream type and imports nothing new.
9//!
10//! | Module | Contents |
11//! |--------|----------|
12//! | `event` | [`Event`], [`ObservableError`] and the producer-side [`Sender`] |
13//! | `stream` | [`Observable`] and the local [`channel`] constructors |
14//! | `error` | [`RpcError`], the technical error of the whole stack |
15//! | `creation` | [`from`], [`of`], [`throw_error`], [`defer`], [`from_future`], [`ObservableInput`] |
16//! | `subject` | [`Subject`], the multicast source |
17//! | `subscribe` | [`Subscription`], the cancellation handle — and the `Future` awaited to join it |
18//! | `transform` | the operators carried by [`Observable`] |
19//! | [`rt`] | execution facade and [`CancellationToken`] |
20//!
21//! The operators are **inherent methods** on [`Observable`]: no extension trait to
22//! import, one single stream type from the first operator to the last.
23//!
24//! ```rust,ignore
25//! // `stream` is the native type returned by an ice-rpc service.
26//! let stream: ice_rpc_rx::Observable<i32, String> = proxy.foo().await;
27//!
28//! let odds = stream.filter(|v| *v % 2 == 1).map(|v| v * 10).take(5);
29//! let first = odds.first_value().await?;
30//! ```
31//!
32//! - [`Observable`] — the operators (`map`, `filter`, `distinct_until_changed`,
33//!   `map_err`, `scan`, `switch_map`, `take`, `skip`, `first`, `first_with`,
34//!   `merge`, `start_with`, `tap`, `finalize`, `delay`, `timeout`, `catch_error`,
35//!   `take_until`, `take_until_token`) and the
36//!   terminals (`first_value`, `last_value`, `collect`, `for_each`, `subscribe`,
37//!   `subscribe_all`, `next`, `recv`). Every operator is a pull-based
38//!   combinator: no intermediate channel, no spawned task. Each has its own
39//!   reference, with a runnable example, on [`Observable`].
40//! - [`Subject`] — the push side: a multi-producer / multi-consumer multicast
41//!   source. [`Subject::new`] multicasts to the current subscribers,
42//!   [`Subject::replay`] also replays the last `n` values (and the terminal
43//!   state) to late subscribers.
44//! - `Observable::subscribe` / `Observable::subscribe_all` — push-based
45//!   consumption through RxJS-style callbacks. [`Subscription`] is the
46//!   cancellation handle **and** a `Future`: `sub.await` joins the subscription,
47//!   the shape `JoinHandle` uses, while keeping the handle and
48//!   [`unsubscribe`](Subscription::unsubscribe)ing it is how a caller stops a
49//!   stream early.
50//! - [`from`], [`of`], [`throw_error`] — channel-free local constructors;
51//!   [`defer`] and [`from_future`] defer their work to the first poll, so a
52//!   service call is only issued when someone consumes the stream.
53//! - [`ObservableInput`] — the bridge a projection uses to accept **either** an
54//!   `Observable` or a `Future` that produces one, so an `async fn` client call
55//!   composes without an explicit [`defer`] (RxJS `ObservableInput`).
56//!
57//! ## Operators
58//!
59//! | ReactiveX category | Operators |
60//! |---|---|
61//! | Transforming | [`map`](Observable::map), [`map_err`](Observable::map_err), [`scan`](Observable::scan), [`switch_map`](Observable::switch_map) |
62//! | Filtering | [`filter`](Observable::filter), [`take`](Observable::take), [`distinct_until_changed`](Observable::distinct_until_changed), [`skip`](Observable::skip), [`first`](Observable::first), [`first_with`](Observable::first_with) |
63//! | Combining | [`merge`](Observable::merge), [`start_with`](Observable::start_with) |
64//! | Conditional / Boolean | [`take_until`](Observable::take_until), [`take_until_token`](Observable::take_until_token) |
65//! | Error handling | [`catch_error`](Observable::catch_error), [`retry_with`] |
66//! | Utility | [`tap`](Observable::tap), [`finalize`](Observable::finalize), [`delay`](Observable::delay), [`timeout`](Observable::timeout) |
67//! | Terminals (they end the chain) | [`collect`](Observable::collect), [`first_value`](Observable::first_value), [`last_value`](Observable::last_value), [`for_each`](Observable::for_each), [`subscribe`](Observable::subscribe), [`subscribe_all`](Observable::subscribe_all), [`next`](Observable::next), [`recv`](Observable::recv) |
68//!
69//! Two rules hold for every operator: it is **pull-based and lazy** (it only
70//! wraps its source in a boxed stream — no intermediate channel, no spawned
71//! task), and it never drops or reorders a terminal event unless its own
72//! documentation says otherwise. Only [`map_err`](Observable::map_err) and
73//! [`catch_error`](Observable::catch_error) act on the **business** error; a
74//! technical [`RpcError`] is fatal and travels untouched.
75//!
76//! ## Normalization
77//!
78//! A source may carry a single response as an internal single-sample
79//! optimization. [`Observable::recv`] normalizes it into `Next` followed by
80//! `Complete`, so consuming code always observes a uniform stream of `Next`
81//! values followed by a terminal event (`Complete` or `Error`).
82//!
83//! ## Timeouts
84//!
85//! [`Observable::timeout`] is a per-event **silence watchdog** on an
86//! active stream, reset after every event.
87
88#![cfg_attr(test, allow(clippy::unwrap_used))] // test code may panic
89
90mod creation;
91mod error;
92mod event;
93pub mod rt;
94mod stream;
95#[cfg(feature = "operators")]
96mod subject;
97#[cfg(feature = "operators")]
98mod subscribe;
99#[cfg(feature = "operators")]
100mod transform;
101
102// The reactive surface is gated behind `operators`, and so are its tests.
103#[cfg(all(test, feature = "operators"))]
104mod tests;
105
106pub use creation::{ObservableInput, defer, from, from_future, of, throw_error};
107pub use error::RpcError;
108pub use event::{Event, ObservableError, Sender};
109pub use rt::CancellationToken;
110pub use stream::{Observable, channel, unbounded_channel};
111#[cfg(feature = "operators")]
112pub use subject::Subject;
113#[cfg(feature = "operators")]
114pub use subscribe::Subscription;
115#[cfg(feature = "operators")]
116pub use transform::{RetryPolicy, retry_with};
117
118/// Internal seam consumed by the code generated by `ice-rpc-macros`.
119///
120/// `#[doc(hidden)]`, and **not** part of the public API: these symbols are
121/// semver-exempt for a consumer of `ice-rpc-rx`, but **not** for the codegen.
122/// The canonical terminals live here rather than at the crate root, so the root
123/// carries only what a developer writes by hand.
124#[doc(hidden)]
125pub mod codegen {
126    pub use crate::stream::{collect_values, first_event};
127}