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