Skip to main content

plexus_client/
progress.rs

1//! Progress as part of a method's return type.
2//!
3//! A method that reports progress says so in its signature: its item is
4//! `Progress<T, P>` — `impl Stream<Item = Result<Progress<T, P>, E>>`, or
5//! `impl Stream<Item = Progress<T, P>>` when it cannot fail. Progress sits
6//! *inside* the `Result` because it is on the success path: an err is never
7//! "in progress".
8//!
9//! [`Progress`] is never serialized as a whole. The server sends the two
10//! cases in different frames — [`Progress::Update`] as a progress frame
11//! carrying `P`, [`Progress::Item`] as a data frame carrying `T` — and a
12//! client that opts in sees them again as a [`Frame`](crate::Frame).
13
14use serde::{Deserialize, Serialize};
15
16/// One step of a method that reports progress: an intermediate report on the
17/// way to its items, or one of the items.
18///
19/// `P` is the method's progress type. It defaults to [`Note`] — the shape
20/// the progress frame has always carried — so `Progress<T>` is the untyped
21/// case and `Progress<T, MyStep>` the precise one.
22///
23/// ```
24/// use plexus_client::{Note, Progress};
25///
26/// enum ImportStep { Chunk { done: usize, of: usize } }
27///
28/// let step: Progress<u32, ImportStep> = Progress::Update(ImportStep::Chunk { done: 3, of: 10 });
29/// let done: Progress<u32, ImportStep> = Progress::Item(42);
30/// assert!(step.is_update());
31/// assert_eq!(done.into_item(), Some(42));
32///
33/// let untyped: Progress<u32> = Progress::Update(Note::new("indexing").with_percentage(50.0));
34/// assert!(untyped.is_update());
35/// ```
36///
37/// Deliberately **not** `Serialize`/`Deserialize`: the two cases travel in
38/// different frames, so there is no single wire value to encode.
39#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
40pub enum Progress<T, P = Note> {
41    /// An intermediate report. Travels as a progress frame carrying `P`.
42    Update(P),
43    /// One of the method's items. Travels as a data frame carrying `T`.
44    Item(T),
45}
46
47impl<T, P> Progress<T, P> {
48    /// `true` for [`Progress::Update`].
49    pub fn is_update(&self) -> bool {
50        matches!(self, Progress::Update(_))
51    }
52
53    /// `true` for [`Progress::Item`].
54    pub fn is_item(&self) -> bool {
55        matches!(self, Progress::Item(_))
56    }
57
58    /// The item, if this is one; an update is dropped.
59    pub fn into_item(self) -> Option<T> {
60        match self {
61            Progress::Item(t) => Some(t),
62            Progress::Update(_) => None,
63        }
64    }
65
66    /// The update, if this is one; an item is dropped.
67    pub fn into_update(self) -> Option<P> {
68        match self {
69            Progress::Update(p) => Some(p),
70            Progress::Item(_) => None,
71        }
72    }
73}
74
75/// The default progress type: a human-readable message and, optionally, how
76/// far along the work is.
77///
78/// Wire shape: `{"message": "…", "percentage": 50.0}`; `percentage` is
79/// omitted when the method cannot say (and absent decodes as `None`).
80#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
81#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
82pub struct Note {
83    /// What is happening, for a human.
84    pub message: String,
85    /// Completion, `0.0`–`100.0`, when the method can say.
86    #[serde(default, skip_serializing_if = "Option::is_none")]
87    pub percentage: Option<f32>,
88}
89
90impl Note {
91    /// A note with no percentage.
92    pub fn new(message: impl Into<String>) -> Self {
93        Self {
94            message: message.into(),
95            percentage: None,
96        }
97    }
98
99    /// This note, with `percentage` (`0.0`–`100.0`) set.
100    pub fn with_percentage(mut self, percentage: f32) -> Self {
101        self.percentage = Some(percentage);
102        self
103    }
104}