Skip to main content

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}