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
//! Progress as part of a method's return type.
//!
//! A method that reports progress says so in its signature: its item is
//! `Progress<T, P>` — `impl Stream<Item = Result<Progress<T, P>, E>>`, or
//! `impl Stream<Item = Progress<T, P>>` when it cannot fail. Progress sits
//! *inside* the `Result` because it is on the success path: an err is never
//! "in progress".
//!
//! [`Progress`] is never serialized as a whole. The server sends the two
//! cases in different frames — [`Progress::Update`] as a progress frame
//! carrying `P`, [`Progress::Item`] as a data frame carrying `T` — and a
//! client that opts in sees them again as a [`Frame`](crate::Frame).
use ;
/// One step of a method that reports progress: an intermediate report on the
/// way to its items, or one of the items.
///
/// `P` is the method's progress type. It defaults to [`Note`] — the shape
/// the progress frame has always carried — so `Progress<T>` is the untyped
/// case and `Progress<T, MyStep>` the precise one.
///
/// ```
/// use plexus_client::{Note, Progress};
///
/// enum ImportStep { Chunk { done: usize, of: usize } }
///
/// let step: Progress<u32, ImportStep> = Progress::Update(ImportStep::Chunk { done: 3, of: 10 });
/// let done: Progress<u32, ImportStep> = Progress::Item(42);
/// assert!(step.is_update());
/// assert_eq!(done.into_item(), Some(42));
///
/// let untyped: Progress<u32> = Progress::Update(Note::new("indexing").with_percentage(50.0));
/// assert!(untyped.is_update());
/// ```
///
/// Deliberately **not** `Serialize`/`Deserialize`: the two cases travel in
/// different frames, so there is no single wire value to encode.
/// The default progress type: a human-readable message and, optionally, how
/// far along the work is.
///
/// Wire shape: `{"message": "…", "percentage": 50.0}`; `percentage` is
/// omitted when the method cannot say (and absent decodes as `None`).