aria2-core 0.3.10

aria2-rust core download engine: multi-protocol segmented downloads, rate limiting, configuration, session persistence, and BitTorrent seeding
Documentation
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
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
//! Demotion logic: active → stopped group transition.
//!
//! Mirrors C++ `RequestGroupMan::removeStoppedGroup()`. When a group's
//! `num_commands` drops to 0 and its status is terminal (Complete, Error,
//! Removed), the engine removes it from the active DashMap and stores
//! the result for RPC `tellStopped` queries.

use std::sync::Arc;
use tracing::{debug, info, warn};

use super::RequestGroup;
use crate::engine::download_event_hooks::{
    DownloadEvent, DownloadEventContext, DownloadEventHooks, MetadataResolvedEvent,
    determine_stop_event,
};
use crate::engine::post_download_handler::{
    build_handler_chain, extract_download_info, run_post_download_processing_with_allocator,
};
use crate::request::request_group::DownloadStatus;
use crate::request::request_group::GroupId;
use crate::util::rwlock_ext::RwLockRecover;

/// Result of a demotion check: groups that should be removed from active.
pub struct DemotedGroup {
    pub group: Arc<std::sync::RwLock<RequestGroup>>,
    pub result: crate::request::request_group::DownloadResult,
}

impl super::RequestGroupMan {
    /// Scan the active DashMap for groups that have no more in-flight commands
    /// and are in a terminal state. Returns the list of demoted groups.
    ///
    /// The engine calls this after an event-processing pass and then:
    /// 1. Remove each group from the active DashMap
    /// 2. Add each `DownloadResult` to the stopped storage
    /// 3. Fire any on_download_complete events
    ///
    /// Mirrors C++ `ProcessStoppedRequestGroup` functor logic.
    pub fn find_stopped_groups(&self) -> Vec<DemotedGroup> {
        let mut demoted = Vec::new();

        for entry in self.active.iter() {
            let g = entry.recover();
            let gid = g.gid();
            let num_cmd = g.num_commands();
            let status = g.status();

            // C++ processes every zero-command group. A shutdown-halted
            // non-terminal group becomes an IN_PROGRESS result, while normal
            // terminal states become their corresponding stopped result.
            let is_terminal = matches!(
                status,
                DownloadStatus::Complete | DownloadStatus::Error(_) | DownloadStatus::Removed
            );
            let is_halted = g.is_halt_requested();

            if num_cmd == 0 && (is_terminal || is_halted) {
                debug!(
                    gid = gid.value(),
                    ?status,
                    "Found stopped group (num_commands=0, terminal status)"
                );
                let result = g.create_download_result();
                demoted.push(DemotedGroup {
                    group: Arc::clone(entry.value()),
                    result,
                });
            }
        }

        demoted
    }

    /// Remove a demoted group from the active DashMap and add its result
    /// to stopped storage. Returns `true` if the group was removed.
    pub fn demote_group(
        &self,
        gid: crate::request::request_group::GroupId,
        result: crate::request::request_group::DownloadResult,
    ) -> bool {
        let _lifecycle = self.lifecycle_guard();
        if let Some((_, group)) = self.active.remove(&gid) {
            self.unregister_group(gid);
            // Release runtime resources (C++ `releaseRuntimeResource()`).
            // In Rust, this means clearing the download context and
            // releasing the rate limiter handle.
            {
                let g = group.recover();
                *g.download_context.recover_mut() = None;
                g.rate_limiter.recover_mut().take(); // Drop rate limiter
            }

            self.record_stopped_result(result);

            info!(gid = gid.value(), "Demoted group from active to stopped");
            true
        } else {
            warn!(
                gid = gid.value(),
                "Tried to demote group not found in active"
            );
            false
        }
    }

    /// Move groups that have no in-flight commands and are not in a terminal
    /// state (Complete / Error / Removed) out of the active DashMap and back
    /// into the reserved queue.
    ///
    /// This closes the pause loop: when `aria2.pause` / `aria2.forcePause`
    /// is issued, the group is marked `Paused` and its download command
    /// terminates. The group must then return to the reserved queue — not to
    /// the stopped results — so it can be unpaused and re-promoted.
    ///
    /// Mirrors C++ `ProcessStoppedRequestGroup` which re-queues groups with
    /// `isPauseRequested()`. Also recovers "orphan" groups whose commands all
    /// ended without a terminal status transition (e.g. a pause that was
    /// undone before the task fully exited), re-queuing them as `Waiting` so
    /// promotion re-spawns them.
    ///
    /// Returns the number of groups re-queued.
    pub fn requeue_non_terminal_groups(&self, event_hooks: Option<&DownloadEventHooks>) -> usize {
        let _lifecycle = self.lifecycle_guard();
        let mut to_move: Vec<(GroupId, Arc<std::sync::RwLock<RequestGroup>>)> = Vec::new();

        for entry in self.active.iter() {
            let g = entry.recover();
            if g.num_commands() != 0 {
                continue;
            }
            let status = g.status();
            if matches!(
                status,
                DownloadStatus::Complete | DownloadStatus::Error(_) | DownloadStatus::Removed
            ) || (g.is_halt_requested() && !g.is_pause_requested())
            {
                continue;
            }
            to_move.push((*entry.key(), entry.value().clone()));
        }

        let mut requeued = 0;
        for (gid, group) in to_move {
            let was_pause_requested = group.recover().is_pause_requested();
            let was_restart_requested = group.recover().is_restart_requested();
            let was_halt_requested = group.recover().is_halt_requested();

            if self.active.remove(&gid).is_none() {
                continue;
            }

            // Release runtime resources (C++ `releaseRuntimeResource()`):
            // drop the rate limiter handle and piece/segment storage so the
            // download can be re-promoted cleanly. Unlike the terminal
            // `demote_group` path, the `download_context` (file entries,
            // piece hashes, BT info) is preserved because a paused download
            // may resume and still needs that metadata.
            {
                let g = group.recover();
                g.drop_piece_storage();
                g.rate_limiter.recover_mut().take(); // Drop rate limiter
            }

            {
                let mut g = group.recover_mut();
                if was_restart_requested {
                    g.apply_pending_options();
                }
                if matches!(g.status(), DownloadStatus::Paused) {
                    if g.is_restart_requested() {
                        // C++ `releaseRuntimeResource()` clears the pause
                        // request for restart-requested groups (paused by
                        // `reduceActiveDownloadsToLimit`) so they auto-resume
                        // once a slot is available. `resume()` also clears the
                        // restart flag.
                        g.resume().ok();
                    }
                } else {
                    // Orphan: no terminal status and no commands left.
                    // Re-queue as Waiting so promotion re-spawns it.
                    g.mark_waiting();
                }
            }

            // Fire on-download-pause hook for groups that are actually
            // pausing (not the reduce-to-limit auto-restart case).
            if let (Some(hooks), true, false, false) = (
                event_hooks,
                was_pause_requested,
                was_restart_requested,
                was_halt_requested,
            ) {
                hooks.fire_event(DownloadEvent::Pause, &group.recover());
            }

            self.reserved.push_front(group);

            requeued += 1;
            debug!(
                gid = gid.value(),
                "Re-queued non-terminal group back to reserved queue"
            );
        }

        if requeued > 0 {
            info!(requeued, "Re-queued non-terminal groups to reserved");
        }
        requeued
    }

    /// Process all stopped groups: find them, demote them, and return
    /// the list of demoted GIDs for event notification.
    ///
    /// This is the main entry point for an event-processing pass.
    /// Groups that are paused (or otherwise have no terminal status) are
    /// first re-queued to the reserved queue; only genuinely terminal groups
    /// are demoted to stopped results. After demoting each group, if the
    /// group completed successfully:
    /// 1. Runs post-download processing (Metalink/BT child group creation)
    /// 2. Resolves any `CompletionDependency` waiting on that GID
    /// 3. Fires the appropriate download event hook (complete/error/pause/stop)
    ///
    /// Mirrors C++ `ProcessStoppedRequestGroup` which calls
    /// `postDownloadProcessing()` on completed groups and
    /// `executeStopHook()` for lifecycle events.
    pub fn remove_stopped_groups(
        &self,
        event_hooks: Option<&DownloadEventHooks>,
    ) -> Vec<crate::request::request_group::GroupId> {
        // Re-queue paused / orphan groups before the stopped scan so the
        // demotion below only sees genuinely terminal groups.
        self.requeue_non_terminal_groups(event_hooks);

        let demoted = self.find_stopped_groups();
        let mut gids = Vec::with_capacity(demoted.len());

        for dg in demoted {
            let gid = dg.group.recover().gid();
            let status = dg.group.recover().status();
            let is_pause_requested = dg.group.recover().is_pause_requested();

            // ── Extract event context BEFORE demoting ──────────────────
            // Must extract while download context is still available.
            // C++ fires hooks while the group is still alive.
            let event_ctx =
                event_hooks.map(|_| DownloadEventContext::from_group(&dg.group.recover()));

            // ── Post-download processing (BEFORE demoting) ──────────────
            // C++: `group->postDownloadProcessing(nextGroups)` is called
            // before the group is removed from the active list, so the
            // disk adaptor and download context are still available.
            let child_groups = if matches!(status, DownloadStatus::Complete) {
                self.run_post_download_processing(&dg.group)
            } else {
                Vec::new()
            };
            let metadata_event = if child_groups.is_empty() {
                None
            } else {
                Some(MetadataResolvedEvent::new(
                    gid,
                    child_groups
                        .iter()
                        .map(|child| child.recover().gid())
                        .collect(),
                ))
            };

            // Post-download processing may add followed-by child GIDs to a
            // completed parent. Refresh the result after that mutation so
            // stopped/RPC consumers see the complete relationship graph.
            let result = if matches!(status, DownloadStatus::Complete) {
                dg.group.recover().create_download_result()
            } else {
                dg.result
            };

            // Now demote the group (releases download context, etc.)
            self.demote_group(gid, result);

            // ── Insert child groups into reserved queue ─────────────────
            // C++: `insertReservedGroup(0, nextGroups)` inserts at front
            // so child groups are promoted before other waiting downloads.
            if !child_groups.is_empty() {
                let child_count = child_groups.len();
                self.insert_reserved_at_front(child_groups);
                info!(
                    parent_gid = gid.value(),
                    children = child_count,
                    "Inserted child groups at front of reserved queue"
                );
            }

            // Notify after insertion so observers can immediately resolve the
            // child GIDs through the request manager. This is a library event,
            // not a standard aria2 lifecycle/RPC notification.
            if let (Some(hooks), Some(event)) = (event_hooks, metadata_event) {
                hooks.notify_metadata_resolved(event);
            }

            // ── Resolve dependencies ────────────────────────────────────
            // When a download completes successfully, resolve any
            // CompletionDependency waiting on this GID.
            if matches!(
                status,
                DownloadStatus::Complete | DownloadStatus::Error(_) | DownloadStatus::Removed
            ) {
                self.resolve_dependencies_for_status_with_events(gid, status.clone(), event_hooks);
            }

            // ── Fire download event hooks ───────────────────────────────
            // C++: `executeStopHook()` is called in ProcessStoppedRequestGroup.
            // If paused → on-download-pause. If complete → on-download-complete.
            // If error → on-download-error. Otherwise → on-download-stop.
            if let (Some(hooks), Some(ctx)) = (event_hooks, event_ctx) {
                let is_complete = matches!(status, DownloadStatus::Complete);
                let is_error = matches!(status, DownloadStatus::Error(_));

                if let Some(event) = determine_stop_event(is_complete, is_error, is_pause_requested)
                {
                    // Resolve the hook command from per-group options
                    // (already extracted in event_ctx) or global hooks.
                    let command = match event {
                        DownloadEvent::Pause => ctx.on_download_pause.as_deref(),
                        DownloadEvent::Complete => ctx.on_download_complete.as_deref(),
                        DownloadEvent::Error => ctx.on_download_error.as_deref(),
                        DownloadEvent::Stop => ctx.on_download_stop.as_deref(),
                        _ => None,
                    };

                    // NOTE: every branch below reaches the hook bus, because
                    // the bus also drives the RPC WebSocket notifications
                    // (aria2.onDownloadComplete / onDownloadError). Skipping
                    // the call when no per-group command is configured — as an
                    // earlier revision did for `Some("")` — silently dropped
                    // those notifications.
                    match command {
                        Some(cmd) if !cmd.is_empty() => {
                            hooks.fire_event_with_params(
                                event,
                                &ctx.gid_hex,
                                ctx.num_files,
                                &ctx.first_file_path,
                                cmd,
                            );
                        }
                        // No per-group command: fall back to global hooks
                        // (and still notify observers unconditionally).
                        _ => hooks.fire_event(event, &dg.group.recover()),
                    }
                }
            }

            gids.push(gid);
        }

        gids
    }

    /// Run post-download processing on a completed group.
    ///
    /// Mirrors C++ `RequestGroup::postDownloadProcessing()`. Extracts
    /// download metadata, builds the handler chain, and creates child
    /// groups if a handler matches. Also sets `followed_by_gids` on
    /// the parent group before it's demoted.
    fn run_post_download_processing(
        &self,
        group: &Arc<std::sync::RwLock<RequestGroup>>,
    ) -> Vec<Arc<std::sync::RwLock<RequestGroup>>> {
        let g = group.recover();

        // Extract download info while context is still available.
        let info = extract_download_info(&g);

        // Build handler chain based on download options.
        let handlers = build_handler_chain(&info.options);

        // Run the processing chain.
        // Can't use `&[&dyn]` directly from Vec<Box>, need to create refs.
        let handler_refs: Vec<&dyn crate::engine::post_download_handler::PostDownloadHandler> =
            handlers.iter().map(|h| h.as_ref()).collect();

        let mut allocate_gid = || self.generate_gid();
        let child_groups =
            run_post_download_processing_with_allocator(&info, &handler_refs, &mut allocate_gid);

        // Set followed_by_gids on the parent group.
        // C++: `requestGroup->followedBy(std::begin(newRgs), std::end(newRgs))`.
        if !child_groups.is_empty() {
            for child in &child_groups {
                g.add_followed_by_gid(child.recover().gid());
            }
        }

        child_groups
    }

    /// Resolve any `CompletionDependency` waiting on the given GID.
    ///
    /// When a group completes and is demoted to stopped, we need to
    /// find any reserved groups that were waiting for this GID and
    /// mark their dependency as resolved. This enables them to be
    /// promoted when the scheduler next processes an event.
    ///
    /// Mirrors C++ `RequestGroupMan` dependency resolution that happens
    /// inside `fillRequestGroupFromReserver` when it encounters a
    /// dependency whose prerequisite has finished.
    pub fn resolve_dependencies_for(&self, completed_gid: crate::request::request_group::GroupId) {
        self.resolve_dependencies_for_status_with_events(
            completed_gid,
            DownloadStatus::Complete,
            None,
        );
    }

    /// Resolve dependencies after a prerequisite reaches any terminal state
    /// and optionally notify observers when BitTorrent metadata is injected
    /// into a payload group.
    pub fn resolve_dependencies_for_status_with_events(
        &self,
        completed_gid: crate::request::request_group::GroupId,
        prerequisite_status: DownloadStatus,
        event_hooks: Option<&DownloadEventHooks>,
    ) {
        let mut failed_dependencies: Vec<(GroupId, String)> = Vec::new();
        #[cfg(feature = "bittorrent")]
        let mut failed_payloads: Vec<(crate::request::request_group::GroupId, String)> = Vec::new();
        #[cfg(feature = "bittorrent")]
        let mut resolved_metadata: Vec<MetadataResolvedEvent> = Vec::new();

        for group in self.reserved.iter_snapshot() {
            let (payload_gid, dependency) = {
                let g = group.recover();
                (g.gid(), g.dependency.recover().as_ref().cloned())
            };
            if let Some(dep) = dependency {
                // Resolve generic completion dependencies when the
                // prerequisite group reaches stopped/completed state.
                if let Some(completion_dep) =
                    dep.as_any()
                        .downcast_ref::<crate::request::request_group::CompletionDependency>()
                    && completion_dep.depends_on_gid == completed_gid
                    && matches!(prerequisite_status, DownloadStatus::Complete)
                {
                    completion_dep.mark_resolved();
                    debug!(
                        gid = payload_gid.value(),
                        depends_on = completed_gid.value(),
                        "Resolved completion dependency"
                    );
                } else if let Some(completion_dep) =
                    dep.as_any()
                        .downcast_ref::<crate::request::request_group::CompletionDependency>()
                    && completion_dep.depends_on_gid == completed_gid
                    && matches!(
                        prerequisite_status,
                        DownloadStatus::Error(_) | DownloadStatus::Removed
                    )
                {
                    let reason = match &prerequisite_status {
                        DownloadStatus::Error(message) => {
                            format!("completion dependency failed: {message}")
                        }
                        DownloadStatus::Removed => "completion dependency was removed".to_string(),
                        _ => unreachable!("status was checked above"),
                    };
                    failed_dependencies.push((payload_gid, reason));
                }

                #[cfg(feature = "bittorrent")]
                if let Some(bt_dep) = dep
                    .as_any()
                    .downcast_ref::<crate::request::request_group::BtDependency>()
                    && bt_dep.depends_on_gid() == completed_gid
                {
                    match bt_dep.resolve_after_prerequisite(&prerequisite_status) {
                        crate::request::request_group::BtDependencyResolution::Resolved => {
                            resolved_metadata
                                .push(MetadataResolvedEvent::new(completed_gid, vec![payload_gid]));
                            debug!(
                                gid = payload_gid.value(),
                                depends_on = completed_gid.value(),
                                "Resolved BitTorrent metadata dependency"
                            );
                        }
                        crate::request::request_group::BtDependencyResolution::Failed(error) => {
                            failed_payloads.push((payload_gid, error));
                        }
                        crate::request::request_group::BtDependencyResolution::Waiting => {}
                    }
                }
            }
        }

        for (gid, error) in failed_dependencies {
            self.fail_reserved_group_with_code(
                gid,
                crate::request::request_group::DownloadResultCode::UnknownError,
                error,
            );
        }

        #[cfg(feature = "bittorrent")]
        for (gid, error) in failed_payloads {
            self.fail_reserved_group(
                gid,
                &format!("BitTorrent metadata dependency failed: {error}"),
            );
        }

        #[cfg(feature = "bittorrent")]
        if let Some(hooks) = event_hooks {
            for event in resolved_metadata {
                hooks.notify_metadata_resolved(event);
            }
        }

        #[cfg(not(feature = "bittorrent"))]
        let _ = event_hooks;
    }
}