shaul_core/event.rs
1use std::panic::AssertUnwindSafe;
2use std::path::PathBuf;
3use std::sync::Arc;
4
5use serde::{Deserialize, Serialize};
6use tokio::sync::broadcast;
7
8use crate::checksum::Checksum;
9use crate::task::{TaskId, TaskState};
10use crate::telemetry::{NoopTelemetry, Telemetry, metrics};
11use crate::util::now_ms;
12
13/// A structured progress event. The CLI consumes the same stream for both
14/// human-readable progress bars and `--json` output.
15#[derive(Clone, Debug, Serialize, Deserialize)]
16pub struct DownloadEvent {
17 /// Creation time in milliseconds since the UNIX epoch.
18 pub timestamp_ms: u64,
19 /// What happened; flattened into the serialized object under the `event`
20 /// tag.
21 #[serde(flatten)]
22 pub kind: EventKind,
23}
24
25impl DownloadEvent {
26 /// Create an event of `kind` stamped with the current time.
27 pub fn new(kind: EventKind) -> Self {
28 Self {
29 timestamp_ms: now_ms(),
30 kind,
31 }
32 }
33}
34
35#[derive(Clone, Debug, Serialize, Deserialize)]
36#[serde(tag = "event", rename_all = "snake_case")]
37#[non_exhaustive]
38/// Everything that can happen to a task between creation and completion.
39///
40/// Serialized with an `event` tag in `snake_case`; consumers should tolerate
41/// unknown variants because the enum is non-exhaustive.
42pub enum EventKind {
43 /// A task was registered and persisted, before any transfer starts.
44 TaskAdded {
45 /// Task that was added.
46 task_id: TaskId,
47 /// Task's link, rendered as a string.
48 link: String,
49 },
50 /// A task began running in a worker.
51 TaskStarted {
52 /// Task that started.
53 task_id: TaskId,
54 /// Task's link, rendered as a string.
55 link: String,
56 },
57 /// A task was explicitly moved to another state, such as being requeued.
58 TaskStateChanged {
59 /// Task whose state changed.
60 task_id: TaskId,
61 /// New state of the task.
62 state: TaskState,
63 },
64 /// A file started transferring, or was found already complete.
65 FileStarted {
66 /// Task the file belongs to.
67 task_id: TaskId,
68 /// Destination-relative path of the file, using `/` separators.
69 file: String,
70 /// Expected size in bytes, when known.
71 total_bytes: Option<u64>,
72 },
73 /// Byte-level progress for one file.
74 Progress {
75 /// Task the file belongs to.
76 task_id: TaskId,
77 /// Destination-relative path of the file, using `/` separators.
78 file: String,
79 /// Bytes transferred so far, including resumed data.
80 downloaded_bytes: u64,
81 /// Expected size in bytes, when known.
82 total_bytes: Option<u64>,
83 },
84 /// A file finished downloading and passed the engine's finalizers.
85 FileCompleted {
86 /// Task the file belongs to.
87 task_id: TaskId,
88 /// Destination-relative path of the file, using `/` separators.
89 file: String,
90 /// Final location of the file on disk.
91 path: PathBuf,
92 /// Final size in bytes.
93 size: u64,
94 /// Whether the content was verified, including BitTorrent piece
95 /// verification.
96 checksum_verified: bool,
97 },
98 /// Checksum verification began for one file.
99 VerificationStarted {
100 /// Task the file belongs to.
101 task_id: TaskId,
102 /// Destination-relative path of the file, using `/` separators.
103 file: String,
104 /// Checksum algorithm name, such as `sha256`.
105 algorithm: String,
106 /// Expected digest as lowercase hex.
107 expected: String,
108 },
109 /// Checksum verification finished for one file.
110 VerificationCompleted {
111 /// Task the file belongs to.
112 task_id: TaskId,
113 /// Destination-relative path of the file, using `/` separators.
114 file: String,
115 /// Whether the computed digest matched the expected one.
116 ok: bool,
117 /// Computed digest as lowercase hex.
118 actual: String,
119 },
120 /// Extraction of an archive began.
121 ExtractionStarted {
122 /// Task the archive belongs to.
123 task_id: TaskId,
124 /// Destination-relative path of the archive, using `/` separators.
125 file: String,
126 /// Directory the archive is extracted into.
127 target: PathBuf,
128 },
129 /// Extraction of an archive finished.
130 ExtractionCompleted {
131 /// Task the archive belongs to.
132 task_id: TaskId,
133 /// Destination-relative path of the archive, using `/` separators.
134 file: String,
135 /// Directory the archive was extracted into.
136 target: PathBuf,
137 /// Number of files written by the extraction.
138 files_extracted: u64,
139 },
140 /// A non-fatal problem that did not abort the download.
141 Warning {
142 /// Task the warning relates to, when it is tied to one.
143 task_id: Option<TaskId>,
144 /// Human-readable warning text.
145 message: String,
146 },
147 /// The task completed successfully after all finalizers ran.
148 TaskCompleted {
149 /// Task that completed.
150 task_id: TaskId,
151 /// Number of files in the task.
152 files: usize,
153 /// Total size of those files in bytes.
154 bytes: u64,
155 },
156 /// The task failed and will not continue on its own.
157 TaskFailed {
158 /// Task that failed.
159 task_id: TaskId,
160 /// Final error message.
161 error: String,
162 },
163 /// The task was paused and can be resumed later.
164 TaskPaused {
165 /// Task that was paused.
166 task_id: TaskId,
167 },
168 /// The task was cancelled and will not be resumed.
169 TaskCancelled {
170 /// Task that was cancelled.
171 task_id: TaskId,
172 },
173 // New variants must be appended so existing enum discriminants stay
174 // stable for callers that cast `EventKind` values.
175 /// A transfer attempt failed and the backend will retry it.
176 Retry {
177 /// Task being retried.
178 task_id: TaskId,
179 /// Destination-relative path of the file, using `/` separators.
180 file: String,
181 /// One-based retry attempt number.
182 attempt: u32,
183 /// Why the previous attempt failed.
184 error: String,
185 },
186}
187
188/// Cloneable handle used to broadcast [`DownloadEvent`]s to subscribers.
189///
190/// Clones share the same broadcast channel. Delivery is best effort: emitting
191/// with no subscribers is a no-op, and a receiver that falls behind may miss
192/// some events.
193pub struct EventSink {
194 sender: broadcast::Sender<DownloadEvent>,
195 // `Arc<dyn Telemetry>` is not `UnwindSafe` because the trait has no
196 // unwind-safety bound. The sink never observes telemetry while unwinding;
197 // asserting that here keeps `EventSink` and `FinalizeContext` unwind-safe
198 // for existing callers without narrowing `Telemetry`.
199 telemetry: AssertUnwindSafe<Arc<dyn Telemetry>>,
200}
201
202impl Clone for EventSink {
203 fn clone(&self) -> Self {
204 Self {
205 sender: self.sender.clone(),
206 telemetry: AssertUnwindSafe(Arc::clone(&self.telemetry.0)),
207 }
208 }
209}
210
211impl EventSink {
212 /// Create a sink and its first receiver. The broadcast buffer holds at
213 /// least 16 events even when `capacity` is smaller.
214 pub fn channel(capacity: usize) -> (Self, broadcast::Receiver<DownloadEvent>) {
215 let (sender, receiver) = broadcast::channel(capacity.max(16));
216 (
217 Self {
218 sender,
219 telemetry: AssertUnwindSafe(Arc::new(NoopTelemetry)),
220 },
221 receiver,
222 )
223 }
224
225 /// Attach a telemetry sink used for events that also carry a count, such
226 /// as [`EventKind::Retry`].
227 pub fn with_telemetry(mut self, telemetry: Arc<dyn Telemetry>) -> Self {
228 self.telemetry = AssertUnwindSafe(telemetry);
229 self
230 }
231
232 /// Replace the telemetry sink on an existing handle.
233 pub fn set_telemetry(&mut self, telemetry: Arc<dyn Telemetry>) {
234 self.telemetry = AssertUnwindSafe(telemetry);
235 }
236
237 /// Broadcast a new event stamped with the current time.
238 pub fn emit(&self, kind: EventKind) {
239 if matches!(&kind, EventKind::Retry { .. }) {
240 self.telemetry.0.counter(metrics::RETRIES, 1, &[]);
241 }
242 let _ = self.sender.send(DownloadEvent::new(kind));
243 }
244
245 /// Returns the telemetry sink attached to this event stream.
246 pub fn telemetry(&self) -> &Arc<dyn Telemetry> {
247 &self.telemetry.0
248 }
249
250 /// Open another receiver; only events emitted after this call are seen.
251 pub fn subscribe(&self) -> broadcast::Receiver<DownloadEvent> {
252 self.sender.subscribe()
253 }
254}
255
256impl Default for EventSink {
257 fn default() -> Self {
258 Self::channel(1024).0
259 }
260}
261
262#[allow(dead_code)]
263fn _assert_checksum_serializable(_: &Checksum) {}
264
265#[cfg(test)]
266mod tests {
267 use super::*;
268 use std::sync::atomic::{AtomicUsize, Ordering};
269
270 struct RetryCounter(Arc<AtomicUsize>);
271
272 impl Telemetry for RetryCounter {
273 fn counter(&self, name: &str, value: u64, _labels: &[(&str, &str)]) {
274 if name == metrics::RETRIES {
275 self.0.fetch_add(value as usize, Ordering::SeqCst);
276 }
277 }
278 }
279
280 #[test]
281 fn event_sink_remains_unwind_safe() {
282 fn assert_unwind_safe<T: std::panic::UnwindSafe + std::panic::RefUnwindSafe>() {}
283 assert_unwind_safe::<EventSink>();
284 assert_unwind_safe::<crate::finalizer::FinalizeContext<'static>>();
285 }
286
287 #[test]
288 fn retry_events_increment_the_retry_metric() {
289 let (mut sink, _receiver) = EventSink::channel(16);
290 let count = Arc::new(AtomicUsize::new(0));
291 sink.set_telemetry(Arc::new(RetryCounter(count.clone())));
292 sink.emit(EventKind::Retry {
293 task_id: uuid::Uuid::new_v4(),
294 file: "file.bin".to_string(),
295 attempt: 1,
296 error: "temporary".to_string(),
297 });
298 assert_eq!(count.load(Ordering::SeqCst), 1);
299 }
300}