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
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
//! Status transition methods for RequestGroup.
//!
//! Mirrors C++ `RequestGroup` state transitions: start, pause, resume,
//! remove, complete, error, and halt. These methods mutate the download
//! status and record timing information.
use tracing::debug;
use crate::engine::download_event_hooks::{DownloadEvent, DownloadEventHooks};
use crate::error::Result;
use crate::util::rwlock_ext::RwLockRecover;
use super::halt_reason::HaltReason;
use super::result_code::DownloadResultCode;
use super::status::DownloadStatus;
impl super::RequestGroup {
/// Publish a terminal lifecycle event to the process-wide observer bus.
///
/// The status transition itself is the only choke point that every
/// download command passes through. Emitting here guarantees terminal
/// lifecycle notifications reach RPC clients; the event bus de-duplicates
/// one-shot events when the engine loop also observes the transition.
///
/// Only observers are notified — **not** the `--on-download-*` shell
/// hooks. Spawning a child process requires a Tokio runtime, and these
/// setters are also called from synchronous contexts; shell hooks stay
/// owned by the engine-loop hook sites where a runtime is guaranteed.
fn notify_terminal_event(&self, event: DownloadEvent) {
self.notify_activity_changed();
DownloadEventHooks::shared().notify_listeners_scoped(
event,
&self.gid.to_hex_string(),
self.event_scope_id(),
);
}
// ── Status Transitions ───────────────────────────────────────────────
/// Transition to `Active` status and record the start time.
///
/// Mirrors C++ `RequestGroup::setState(STATE_ACTIVE)`.
pub fn start(&mut self) -> Result<()> {
let mut status = self.status.recover_mut();
let mut start_time = self.start_time.recover_mut();
*status = DownloadStatus::Active;
*start_time = Some(std::time::Instant::now());
self.progress.reset_network_activity();
self.notify_lifecycle_changed();
tracing::info!("Starting download task #{}", self.gid.value());
Ok(())
}
/// Transition to `Paused` status (graceful pause).
///
/// In-flight chunks are allowed to finish before the download loop stops.
/// Mirrors C++ `pauseRequested_ = true`.
pub fn pause(&mut self) -> Result<()> {
let mut status = self.status.recover_mut();
if matches!(*status, DownloadStatus::Active | DownloadStatus::Waiting) {
*status = DownloadStatus::Paused;
self.control_flags.request_halt();
self.request_pause();
self.notify_lifecycle_changed();
tracing::info!("Pausing download task #{}", self.gid.value());
}
Ok(())
}
/// Force-pause: set both pause and force-pause flags so the download loop
/// aborts in-flight commands immediately. Mirrors C++ `forcePauseRequested`.
pub fn force_pause(&mut self) -> Result<()> {
let mut status = self.status.recover_mut();
if matches!(*status, DownloadStatus::Active | DownloadStatus::Waiting) {
*status = DownloadStatus::Paused;
self.control_flags.request_force_halt();
self.control_flags.request_force_pause();
self.notify_lifecycle_changed();
tracing::info!("Force-pausing download task #{}", self.gid.value());
}
Ok(())
}
/// Resume a paused download. Running commands remain Active; stopped groups
/// transition to Waiting so the request group manager can schedule them.
pub fn resume(&mut self) -> Result<()> {
let mut status = self.status.recover_mut();
if matches!(*status, DownloadStatus::Paused) {
*status = if self.num_commands() > 0 {
DownloadStatus::Active
} else {
DownloadStatus::Waiting
};
self.clear_command_failure();
self.clear_pause();
self.control_flags.clear_halt();
// Also clear a pending restart intent so a group that was paused
// by `reduce_to_limit()` (which sets the restart flag alongside
// pause) does not carry a stale flag after a manual unpause.
self.control_flags.clear_restart();
self.notify_lifecycle_changed();
tracing::info!("Resuming download task #{}", self.gid.value());
}
Ok(())
}
/// Transition to `Removed` status and record the halt reason.
///
/// Mirrors C++ `RequestGroup::setState(STATE_REMOVED)` with
/// `haltReason_ = USER_REQUEST`.
pub fn remove(&mut self) -> Result<()> {
let mut status = self.status.recover_mut();
let mut end_time = self.end_time.recover_mut();
*status = DownloadStatus::Removed;
*end_time = Some(std::time::Instant::now());
*self.halt_reason.recover_mut() = HaltReason::UserRequest;
self.notify_lifecycle_changed();
tracing::info!("Removing download task #{}", self.gid.value());
Ok(())
}
/// Mark the group as removed after its command has stopped.
pub fn mark_removed(&self) {
*self.status.recover_mut() = DownloadStatus::Removed;
*self.end_time.recover_mut() = Some(std::time::Instant::now());
*self.halt_reason.recover_mut() = HaltReason::UserRequest;
self.notify_lifecycle_changed();
tracing::info!(gid = self.gid.value(), "Marked download as removed");
}
/// Request a graceful halt (let in-flight chunks finish).
/// Mirrors C++ `setHaltRequested(true, reason)`.
pub fn request_halt(&self, reason: HaltReason) {
self.control_flags.request_halt();
*self.halt_reason.recover_mut() = reason;
self.notify_lifecycle_changed();
tracing::info!(gid = self.gid.value(), ?reason, "Halt requested");
}
/// Request a forced halt (abort immediately, even mid-write).
/// Mirrors C++ `setForceHaltRequested(true, reason)`.
pub fn request_force_halt(&self, reason: HaltReason) {
self.control_flags.request_force_halt();
*self.halt_reason.recover_mut() = reason;
self.notify_lifecycle_changed();
tracing::info!(gid = self.gid.value(), ?reason, "Force halt requested");
}
/// Mark the payload as complete and enter seed-only mode.
///
/// This mirrors C++ `RequestGroup::enableSeedOnly()`: the torrent stays
/// alive for seeding, while the payload is no longer an active download.
pub fn enable_seed_only(&self) {
if self.options().bt_detach_seed_only {
self.seed_only
.store(true, std::sync::atomic::Ordering::Release);
}
}
/// Return whether this group has entered seed-only mode.
pub fn is_seed_only(&self) -> bool {
self.seed_only.load(std::sync::atomic::Ordering::Acquire)
}
/// Transition to `Complete` status and record the end time.
///
/// Sets completed_length equal to total_length (mirrors C++ behavior
/// where the download is considered 100% done).
pub fn complete(&mut self) -> Result<()> {
// Scope the guards so no lock is held while observers run.
{
let mut status = self.status.recover_mut();
let mut end_time = self.end_time.recover_mut();
let total = self.progress.total_length();
*status = DownloadStatus::Complete;
*end_time = Some(std::time::Instant::now());
self.progress.set_completed_length(total);
}
tracing::info!("Completing download task #{}", self.gid.value());
self.notify_terminal_event(DownloadEvent::Complete);
Ok(())
}
/// Transition to `Error` status with an error message.
pub fn error(&mut self, err: impl Into<String>) -> Result<()> {
self.clear_bt_peer_snapshots();
let message = err.into();
{
let mut status = self.status.recover_mut();
let mut end_time = self.end_time.recover_mut();
*status = DownloadStatus::Error(message.clone());
*end_time = Some(std::time::Instant::now());
}
*self.last_error_message.recover_mut() = message;
*self.last_error_code.recover_mut() = DownloadResultCode::UnknownError;
tracing::debug!("Download task #{} encountered error", self.gid.value());
self.notify_terminal_event(DownloadEvent::Error);
Ok(())
}
/// Mark the download as complete using interior mutability (`&self`).
///
/// Unlike `complete(&mut self)`, this method only requires `&self` so it
/// can be called from the engine loop which holds the group behind an
/// `Arc<std::sync::RwLock<RequestGroup>>` without needing a write lock
/// on the outer guard.
pub fn mark_complete(&self) {
let total = self.progress.total_length();
*self.status.recover_mut() = DownloadStatus::Complete;
*self.end_time.recover_mut() = Some(std::time::Instant::now());
self.progress.set_completed_length(total);
tracing::info!(gid = self.gid.value(), "Marked download as complete");
self.notify_terminal_event(DownloadEvent::Complete);
}
/// Mark the download as errored using interior mutability (`&self`).
///
/// Stores the error message in `last_error_message` and the error code
/// in `last_error_code`, then transitions status to `Error`.
pub fn mark_error(&self, message: String) {
self.mark_error_with_code(DownloadResultCode::UnknownError, message);
}
/// Mark the download as errored while preserving the mapped aria2 code.
pub fn mark_error_with_code(&self, code: DownloadResultCode, message: String) {
*self.last_error_message.recover_mut() = message.clone();
*self.last_error_code.recover_mut() = code;
*self.status.recover_mut() = DownloadStatus::Error(message);
*self.end_time.recover_mut() = Some(std::time::Instant::now());
tracing::info!(gid = self.gid.value(), ?code, "Marked download as errored");
self.notify_terminal_event(DownloadEvent::Error);
}
/// Mark a timeout as a terminal error while retaining its structured code.
pub fn mark_timeout(&self) {
self.clear_bt_peer_snapshots();
*self.last_error_message.recover_mut() = "Download timed out".to_string();
*self.last_error_code.recover_mut() = DownloadResultCode::TimeOut;
*self.status.recover_mut() = DownloadStatus::Error("Download timed out".to_string());
*self.end_time.recover_mut() = Some(std::time::Instant::now());
tracing::info!(gid = self.gid.value(), "Marked download as timed out");
self.notify_terminal_event(DownloadEvent::Error);
}
/// Mark the download as paused using interior mutability (`&self`).
///
/// Used by the engine loop when a running task terminates because a
/// pause was requested (`aria2.pause` / `aria2.forcePause`). The group
/// stays in `Paused` status so it can be unpaused and re-promoted,
/// instead of being recorded as an error. Mirrors C++ where
/// pause-requested groups return to the reserved queue.
pub fn mark_paused(&self) {
*self.status.recover_mut() = DownloadStatus::Paused;
// C++ keeps pause as lifecycle state and leaves lastErrorCode and its
// message untouched. In particular, do not invent a pause error code
// or erase a code recorded by an earlier URI attempt.
tracing::info!(gid = self.gid.value(), "Marked download as paused");
self.notify_lifecycle_changed();
}
/// Transition the group back to `Waiting` status (interior mutability).
///
/// Used when a group's commands all ended without a terminal transition
/// (e.g. a pause was requested and then undone before the task fully
/// exited). The group is re-queued so promotion can re-spawn it.
pub fn mark_waiting(&self) {
*self.status.recover_mut() = DownloadStatus::Waiting;
*self.end_time.recover_mut() = None;
tracing::debug!(gid = self.gid.value(), "Marked download as waiting");
self.notify_lifecycle_changed();
}
// ── Status Queries ───────────────────────────────────────────────────
/// Return the current download status.
pub fn status(&self) -> DownloadStatus {
self.status.recover().clone()
}
/// Non-blocking check whether this group has been marked as `Removed`.
///
/// Uses `try_read` on the inner status lock so it is safe to call from
/// hot download loops without risking lock contention or deadlock. When
/// the lock is contended the method returns `false` (treats the task as
/// still running); the caller will re-check on the next iteration.
///
/// This is the primary signal used by `DownloadCommand` and the
/// underlying downloaders to detect that `aria2.remove` /
/// `aria2.forceRemove` has been invoked.
pub fn is_removed(&self) -> bool {
match self.status.try_read() {
Ok(guard) => matches!(*guard, DownloadStatus::Removed),
Err(_) => false,
}
}
/// Check whether this group has been paused (non-blocking).
/// Used by downloaders to detect `aria2.pause` / `aria2.forcePause`.
pub fn is_paused_flag(&self) -> bool {
match self.status.try_read() {
Ok(guard) => matches!(*guard, DownloadStatus::Paused),
Err(_) => false,
}
}
/// Per-command I/O inactivity timeout. Returns `None` for no timeout.
///
/// Mirrors C++ `RequestGroup::timeout_`. The engine refreshes this clock
/// only when the protocol receives non-empty payload bytes.
pub fn timeout(&self) -> Option<std::time::Duration> {
self.options.timeout.map(std::time::Duration::from_secs)
}
/// Drop piece storage and segment data.
///
/// Called during promotion (reserved → active) to release resources
/// held by a previously paused download. Paused downloads hold
/// references to PieceStorage via their segment list; releasing
/// them before the download restarts prevents stale state.
///
/// Mirrors C++ `RequestGroup::dropPieceStorage()` which resets
/// `segmentMan_` and `pieceStorage_`.
pub fn drop_piece_storage(&self) {
self.segments.recover_mut().clear();
debug!(
gid = self.gid.value(),
"Dropped piece storage and segment data"
);
}
/// BT info hash as hex string. Returns `None` for non-BT downloads.
/// Mirrors C++ `RequestGroup::getDownloadContext()->getInfoHash()`.
pub fn info_hash_hex(&self) -> Option<String> {
self.download_context
.recover()
.as_ref()
.and_then(|ctx| ctx.info_hash_hex())
}
}