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
//! RequestGroup struct definition and constructor.
//!
//! Each `RequestGroup` represents one download task, tracking its URIs,
//! status, progress, segments, and lifecycle control flags. Methods are
//! split across sub-modules for cohesion and to respect the 600-line
//! file size limit.
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::OnceLock;
use std::sync::atomic::{AtomicBool, AtomicU32, AtomicU64, AtomicUsize};
use tokio::sync::Notify;
use tracing::info;
use crate::download::DownloadContext;
use crate::rate_limiter::RateLimiter;
use crate::segment::Segment;
use super::activity::ActivitySignal;
use super::bt_peer_snapshot::BtPeerSnapshot;
use super::connection_state::ConnectionState;
use super::group_id::GroupId;
use super::halt_reason::{DownloadControlFlags, HaltReason};
use super::options::DownloadOptions;
use super::progress::AtomicProgress;
use super::result_code::DownloadResultCode;
/// A single download task managed by the engine.
///
/// Each `RequestGroup` owns:
/// - The initial URI list (transferred to `FileEntry` when `DownloadContext` is set)
/// - The current download status and control flags
/// - Lock-free progress counters for hot-path updates
/// - An optional `DownloadContext` with `FileEntry` objects that manage
/// the URI lifecycle (remaining → spent → results)
///
/// # Thread Safety
///
/// `RequestGroup` is `Send + Sync` — it uses `RwLock` and atomics for
/// interior mutability. It is typically shared via `Arc<RwLock<RequestGroup>>`
/// between the engine loop and RPC handlers.
///
/// # URI Lifecycle
///
/// URIs follow a 3-tier state machine (matching C++ `FileEntry`):
///
/// ```text
/// RequestGroup.uris (initial) → FileEntry.remaining_uris → FileEntry.spent_uris → FileEntry.uri_results
/// ```
///
/// When `set_download_context()` is called, the initial URIs are transferred
/// to the first `FileEntry`'s `remaining_uris`. After that, all URI lifecycle
/// operations delegate to `FileEntry` via `DownloadContext`.
pub struct RequestGroup {
/// Group identifier — unique across the engine session.
pub(super) gid: GroupId,
/// Identity of the request manager that owns lifecycle events for this group.
event_scope_id: u64,
/// Initial URI list provided at construction time.
///
/// These URIs are transferred to the first `FileEntry`'s `remaining_uris`
/// when `set_download_context()` is called. After transfer, this field
/// is still available for RPC queries that need the original URI list,
/// but URI lifecycle operations should go through `DownloadContext`.
pub(super) uris: Vec<Box<str>>,
/// Metalink file name override, independent of the global `out` option.
pub(super) output_name: std::sync::RwLock<Option<String>>,
/// Effective local output path selected by the download command.
///
/// This is updated after response metadata and collision resolution so
/// RPC and UI consumers report the path that the writer actually uses.
pub(super) resolved_output_path: std::sync::RwLock<Option<String>>,
/// Download options — shared via `Arc` for cheap cloning.
pub(super) options: Arc<DownloadOptions>,
/// Live peer limit shared with the BT runtime and incoming listener.
/// Runtime option changes publish here before returning to their caller.
pub(crate) bt_max_peers_limit: Arc<AtomicUsize>,
/// Live peer-exchange option observed by long-lived BitTorrent actors.
pub(crate) bt_peer_exchange_enabled: Arc<AtomicBool>,
/// Canonical option values captured when this task was created.
///
/// The task owns this immutable snapshot so external adapters can report
/// the same per-group options after later global configuration changes.
/// Runtime changes stay separate in `runtime_options` and are overlaid
/// only when they have actually taken effect.
pub(super) option_snapshot: Option<HashMap<String, serde_json::Value>>,
/// Successfully applied task-level runtime overrides.
///
/// The typed fields in [`DownloadOptions`] remain the execution source for
/// implemented options. This map preserves canonical options that are
/// validated at the runtime seam but do not yet have a dedicated execution
/// field, so adapters never report success and silently lose the value.
pub(super) runtime_options: std::sync::RwLock<HashMap<String, serde_json::Value>>,
/// Options deferred until the current command generation is restarted.
pub pending_options: std::sync::RwLock<HashMap<String, serde_json::Value>>,
/// Current download status.
pub(super) status: std::sync::RwLock<super::status::DownloadStatus>,
/// Allocated download segments.
pub(super) segments: std::sync::RwLock<Vec<Segment>>,
/// Timestamp when the download started.
pub(super) start_time: std::sync::RwLock<Option<std::time::Instant>>,
/// Timestamp when the download ended (completed, errored, or removed).
pub(super) end_time: std::sync::RwLock<Option<std::time::Instant>>,
/// Lock-free progress counters shared via `Arc` so the hot-path download
/// code can update progress without acquiring the outer `RwLock`.
pub progress: Arc<AtomicProgress>,
/// BT piece bitfield.
pub bt_bitfield: std::sync::RwLock<Option<Arc<std::sync::RwLock<Vec<u8>>>>>,
/// Current active BT peer snapshots for read-only consumers.
pub(crate) bt_peer_snapshots: Arc<std::sync::RwLock<Vec<BtPeerSnapshot>>>,
/// Number of currently active protocol connections.
///
/// This is deliberately separate from `num_commands` and from option
/// limits such as HTTP `split` or BT `bt_max_peers`. It is the value
/// exposed through the shared status snapshot and is updated by the
/// protocol schedulers while their real connections are active.
pub(crate) connection_state: Arc<ConnectionState>,
/// Changes when the group's URI sources are edited at runtime.
pub(crate) uri_generation: Arc<AtomicU64>,
/// Dedicated wake-up for schedulers waiting for source URI changes.
pub(crate) uri_notify: Arc<Notify>,
/// Download context — central metadata (file entries, piece hashes, attributes).
/// In C++ aria2, `RequestGroup` owns `shared_ptr<DownloadContext> dctx_`.
/// `None` until the download engine populates it.
pub download_context: std::sync::RwLock<Option<Arc<DownloadContext>>>,
// BT metadata fields (for session persistence enhancement)
/// Number of pieces in the torrent (0 for non-BT downloads).
pub bt_num_pieces: AtomicU32,
/// Size of each piece in bytes (0 for non-BT downloads).
pub bt_piece_length: AtomicU32,
/// Info hash hex string for torrent identification (None for non-BT).
pub bt_info_hash_hex: std::sync::RwLock<Option<String>>,
/// Owned BT metadata retained when the live download context is released.
/// Handle to the download's `RateLimiter` for dynamic rate adjustment.
/// `None` until the download engine wires up a `ThrottledWriter`.
pub rate_limiter: std::sync::RwLock<Option<RateLimiter>>,
/// Shared session transfer counters injected by `RequestGroupMan`.
pub(super) global_net_stat:
std::sync::RwLock<Option<Arc<crate::request::global_net_stat::GlobalNetStat>>>,
// ── Lifecycle control flags (C++ haltRequested_/forceHaltRequested_/pauseRequested_) ──
/// Number of in-flight command tasks for this group.
/// When this reaches 0, the group can be demoted from active to stopped.
pub num_commands: AtomicU32,
/// Atomic control flags for halt/pause/force-halt/restart signals.
/// Checked by hot download loops without acquiring the `RwLock` on status.
pub control_flags: DownloadControlFlags,
/// Notifies download tasks when a lifecycle control or status changes.
///
/// This is deliberately separate from the atomic flags: the flags remain
/// the source of truth, while the notification only wakes an async waiter
/// so it can re-check those flags when a lifecycle event occurs.
pub lifecycle_notify: Arc<Notify>,
/// Manager-wide signal used by snapshot observers such as the console UI.
/// It is injected when the group enters a `RequestGroupMan`.
pub(super) activity_signal: OnceLock<Arc<ActivitySignal>>,
/// Reason why the download was halted.
pub halt_reason: std::sync::RwLock<HaltReason>,
/// Last error code recorded for this download.
pub last_error_code: std::sync::RwLock<DownloadResultCode>,
/// Last error message recorded for this download.
pub last_error_message: std::sync::RwLock<String>,
/// Last real peer connection observed by an HTTP/FTP command.
/// This is a snapshot only; protocol tasks remain the owners of sockets.
pub connection_contexts: std::sync::RwLock<Vec<crate::network::ConnectionContext>>,
/// Whether any command in the current command generation failed.
pub command_failure: AtomicBool,
/// Number of URI attempts that failed because the remote did not support
/// resuming. Mirrors C++ `RequestGroup::resumeFailureCount_`.
pub resume_failure_count: AtomicU32,
/// Number of HTTP/FTP not-found responses observed for this group.
/// Mirrors C++ `RequestGroup::fileNotFoundCount_`.
pub file_not_found_count: AtomicU32,
/// Whether saving the .aria2 control file is currently enabled.
/// Disabled during hash checking to prevent corrupt state.
pub save_control_file_enabled: std::sync::RwLock<std::sync::atomic::AtomicBool>,
/// Whether the BitTorrent payload has completed and this group is now
/// seed-only. Seed-only groups remain available for seeding but do not
/// consume the normal active-download concurrency budget.
pub seed_only: AtomicBool,
/// Output path whose sidecar `.aria2` file belongs to this group.
pub control_file_path: std::sync::RwLock<Option<std::path::PathBuf>>,
/// Optional dependency that must be resolved before this group
/// can be promoted from reserved to active.
pub dependency: std::sync::RwLock<Option<Arc<dyn super::dependency::Dependency>>>,
/// GID of the parent download that spawned this one.
///
/// Mirrors C++ `RequestGroup::following_`. Set when a post-download
/// handler creates child groups (e.g. Metalink → child downloads,
/// torrent → magnet). Used by RPC `following` field and for
/// parent-child relationship tracking.
pub following_gid: std::sync::RwLock<Option<GroupId>>,
/// GIDs of downloads spawned by this one.
///
/// Mirrors C++ `RequestGroup::followedBy_`. Populated when a
/// post-download handler creates child groups from this download.
/// Used by RPC `followedBy` field.
pub followed_by_gids: std::sync::RwLock<Vec<GroupId>>,
/// GID of the download this group belongs to.
///
/// Mirrors C++ `RequestGroup::belongsToGID_`, used for child downloads
/// such as Metalink/torrent follow-up groups.
pub belongs_to_gid: std::sync::RwLock<Option<GroupId>>,
/// Provenance of the metadata that created this group.
///
/// Mirrors C++ `RequestGroup::metadataInfo_`. It is intentionally kept
/// separate from parent/child GIDs because metadata provenance can be
/// data-only and does not itself imply a generated child.
pub metadata_info: std::sync::RwLock<Option<super::metadata_info::MetadataInfo>>,
/// In-memory torrent metadata supplied by a CLI/RPC caller.
#[cfg(feature = "bittorrent")]
pub bt_metadata_data: std::sync::RwLock<Option<Vec<u8>>>,
/// Whether this group uses the C++ `MemoryPreDownloadHandler` semantics.
///
/// This is separate from protocol-specific metadata slots because the
/// flag describes the source download lifecycle, not the type of bytes
/// eventually parsed by a post-download handler.
pub in_memory_download: AtomicBool,
/// Bytes collected by an in-memory source download.
pub in_memory_data: std::sync::RwLock<Option<Vec<u8>>>,
/// Content-Type observed for the source response.
pub content_type: std::sync::RwLock<Option<String>>,
/// Raw Metalink document and selected file index for manager-owned fallback execution.
#[cfg(feature = "metalink")]
pub metalink_data: std::sync::RwLock<Option<Vec<u8>>>,
#[cfg(feature = "metalink")]
pub metalink_file_index: std::sync::RwLock<Option<usize>>,
/// Parsed, normalized Metalink file for the current in-memory generation.
/// Restored groups leave this empty and reconstruct the file from the
/// persisted source document and index.
#[cfg(feature = "metalink")]
pub(crate) parsed_metalink_file:
std::sync::RwLock<Option<Arc<aria2_protocol::metalink::parser::MetalinkFile>>>,
/// Base URI used when the Metalink source was parsed.
#[cfg(feature = "metalink")]
pub metalink_base_uri: std::sync::RwLock<Option<String>>,
}
impl RequestGroup {
/// Create a new `RequestGroup` with the given GID, URIs, and options.
///
/// The group starts in `Waiting` status with no in-flight commands.
/// URIs are stored in the `uris` field and will be transferred to the
/// first `FileEntry` when `set_download_context()` is called.
pub fn new(gid: GroupId, uris: Vec<String>, options: DownloadOptions) -> Self {
info!("Creating request group #{}", gid.value());
let bt_max_peers_limit = Arc::new(AtomicUsize::new(options.bt_max_peers));
let bt_peer_exchange_enabled = Arc::new(AtomicBool::new(options.enable_peer_exchange));
RequestGroup {
gid,
event_scope_id: 0,
uris: uris.into_iter().map(String::into_boxed_str).collect(),
output_name: std::sync::RwLock::new(None),
resolved_output_path: std::sync::RwLock::new(None),
options: Arc::new(options),
bt_max_peers_limit,
bt_peer_exchange_enabled,
option_snapshot: None,
runtime_options: std::sync::RwLock::new(HashMap::new()),
pending_options: std::sync::RwLock::new(HashMap::new()),
status: std::sync::RwLock::new(super::status::DownloadStatus::Waiting),
segments: std::sync::RwLock::new(Vec::new()),
start_time: std::sync::RwLock::new(None),
end_time: std::sync::RwLock::new(None),
progress: Arc::new(AtomicProgress::new()),
bt_bitfield: std::sync::RwLock::new(None),
bt_peer_snapshots: Arc::new(std::sync::RwLock::new(Vec::new())),
connection_state: Arc::new(ConnectionState::new()),
uri_generation: Arc::new(AtomicU64::new(0)),
uri_notify: Arc::new(Notify::new()),
download_context: std::sync::RwLock::new(None),
bt_num_pieces: AtomicU32::new(0),
bt_piece_length: AtomicU32::new(0),
bt_info_hash_hex: std::sync::RwLock::new(None),
rate_limiter: std::sync::RwLock::new(None),
global_net_stat: std::sync::RwLock::new(None),
num_commands: AtomicU32::new(0),
control_flags: DownloadControlFlags::new(),
lifecycle_notify: Arc::new(Notify::new()),
activity_signal: OnceLock::new(),
halt_reason: std::sync::RwLock::new(HaltReason::None),
last_error_code: std::sync::RwLock::new(DownloadResultCode::UnknownError),
last_error_message: std::sync::RwLock::new(String::new()),
connection_contexts: std::sync::RwLock::new(Vec::new()),
command_failure: AtomicBool::new(false),
resume_failure_count: AtomicU32::new(0),
file_not_found_count: AtomicU32::new(0),
save_control_file_enabled: std::sync::RwLock::new(std::sync::atomic::AtomicBool::new(
true,
)),
seed_only: AtomicBool::new(false),
control_file_path: std::sync::RwLock::new(None),
dependency: std::sync::RwLock::new(None),
following_gid: std::sync::RwLock::new(None),
followed_by_gids: std::sync::RwLock::new(Vec::new()),
belongs_to_gid: std::sync::RwLock::new(None),
metadata_info: std::sync::RwLock::new(None),
#[cfg(feature = "bittorrent")]
bt_metadata_data: std::sync::RwLock::new(None),
in_memory_download: AtomicBool::new(false),
in_memory_data: std::sync::RwLock::new(None),
content_type: std::sync::RwLock::new(None),
#[cfg(feature = "metalink")]
metalink_data: std::sync::RwLock::new(None),
#[cfg(feature = "metalink")]
metalink_file_index: std::sync::RwLock::new(None),
#[cfg(feature = "metalink")]
parsed_metalink_file: std::sync::RwLock::new(None),
#[cfg(feature = "metalink")]
metalink_base_uri: std::sync::RwLock::new(None),
}
}
pub(crate) fn event_scope_id(&self) -> u64 {
self.event_scope_id
}
pub(crate) fn set_event_scope_id(&mut self, scope_id: u64) {
self.event_scope_id = scope_id;
}
}