aria2-core 0.3.5

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
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
//! BitTorrent Message Dispatcher — outgoing message queue and request slot tracking
//!
//! This module implements the per-peer outgoing message queue and request
//! slot management, mirroring C++ `DefaultBtMessageDispatcher`.
//!
//! # Architecture
//!
//! - [`BtMessageDispatcher`] — Per-peer dispatcher holding the outgoing message
//!   queue and outstanding request slots. Mirrors C++ `DefaultBtMessageDispatcher`.
//! - [`RequestSlot`] — Tracks a single outstanding piece-block request.
//!   Mirrors C++ `RequestSlot`.
//! - [`InactiveReason`] — Reason a peer became inactive and should be dropped.
//! - [`FloodingStat`] — Anti-flooding counters (choke/unchoke + keepalive).
//! - [`ActiveInteractionChecker`] — Timer-based inactivity detection.
//! - [`SlotCheckResult`] — Result of periodic request-slot validation.
//!
//! # C++ Equivalence
//!
//! | Rust | C++ |
//! |---|---|
//! | `BtMessageDispatcher` | `DefaultBtMessageDispatcher` |
//! | `RequestSlot` | `RequestSlot` |
//! | `FloodingStat` | `FloodingStat` (inline in DefaultBtInteractive) |

use std::time::{Duration, Instant};

// ===========================================================================
// RequestSlot — outstanding piece-block request tracker
// ===========================================================================

/// Tracks a single outstanding Request message sent to a peer.
///
/// When we send a Request {index, begin, length} to a peer, a `RequestSlot`
/// is created to track it until the corresponding Piece message arrives
/// or the slot times out.
///
/// Mirrors C++ `RequestSlot` (defined in `RequestSlot.h`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestSlot {
    /// Piece index
    pub index: u32,
    /// Byte offset within the piece
    pub begin: u32,
    /// Block length in bytes
    pub length: u32,
    /// Block index (= begin / block_length)
    pub block_index: u32,
    /// Command ID that created this request
    pub cuid: u64,
    /// When this request was dispatched
    pub dispatched_at: Instant,
}

impl RequestSlot {
    /// Create a new request slot.
    ///
    /// `block_size` is used to compute `block_index = begin / block_size`.
    pub fn new(index: u32, begin: u32, length: u32, block_size: u32) -> Self {
        let block_index = begin.checked_div(block_size).unwrap_or(0);
        Self {
            index,
            begin,
            length,
            block_index,
            cuid: 0,
            dispatched_at: Instant::now(),
        }
    }

    /// Create a request slot with a specific command ID.
    pub fn with_cuid(index: u32, begin: u32, length: u32, block_size: u32, cuid: u64) -> Self {
        let mut slot = Self::new(index, begin, length, block_size);
        slot.cuid = cuid;
        slot
    }

    /// Check whether this slot has timed out.
    pub fn is_timed_out(&self, timeout: Duration) -> bool {
        self.dispatched_at.elapsed() > timeout
    }

    /// Check whether this slot matches the given piece/block coordinates.
    pub fn matches(&self, index: u32, begin: u32, length: u32) -> bool {
        self.index == index && self.begin == begin && self.length == length
    }
}

// ===========================================================================
// InactiveReason — why a peer is being dropped
// ===========================================================================

/// Reason a peer became inactive and should be disconnected.
///
/// Used by `checkActiveInteraction()` in the interaction loop to decide
/// why a peer should be dropped after a timeout.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum InactiveReason {
    /// Both sides uninterested for too long (30s in C++)
    MutualUninterested,
    /// No data exchanged for too long (60s total inactivity in C++)
    NoDataExchange,
    /// Both sides are seeders — no useful exchange possible
    SeederToSeeder,
}

impl std::fmt::Display for InactiveReason {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            InactiveReason::MutualUninterested => write!(f, "mutual_uninterested"),
            InactiveReason::NoDataExchange => write!(f, "no_data_exchange"),
            InactiveReason::SeederToSeeder => write!(f, "seeder_to_seeder"),
        }
    }
}

// ===========================================================================
// FloodingStat — anti-flooding counters
// ===========================================================================

/// Anti-flooding statistics for a single peer connection.
///
/// Tracks counts of choke/unchoke transitions and keepalive messages
/// within a rolling window to detect misbehaving peers that flood
/// with control messages.
///
/// Mirrors C++ `FloodingStat` (inline struct in `DefaultBtInteractive`).
#[derive(Debug, Clone)]
pub struct FloodingStat {
    /// Count of choke/unchoke transitions in the current window
    choke_unchoke_count: u32,
    /// Count of keepalive messages in the current window
    keepalive_count: u32,
    /// Timestamp of the last flooding check/reset.
    /// Named `last_reset` in C++ aria2's FloodingStat.
    pub(crate) last_reset: Instant,
    /// Flooding check interval (default 5 seconds, matching C++)
    check_interval: Duration,
    /// Threshold for choke/unchoke flooding (2 in C++)
    choke_unchoke_threshold: u32,
    /// Threshold for keepalive flooding (2 in C++)
    keepalive_threshold: u32,
}

impl FloodingStat {
    /// Create a new flooding stat tracker with default thresholds.
    pub fn new() -> Self {
        Self {
            choke_unchoke_count: 0,
            keepalive_count: 0,
            last_reset: Instant::now(),
            check_interval: Duration::from_secs(5),
            choke_unchoke_threshold: 2,
            keepalive_threshold: 2,
        }
    }

    /// Increment the choke/unchoke counter.
    pub fn inc_choke_unchoke_count(&mut self) {
        self.choke_unchoke_count += 1;
    }

    /// Increment the keepalive counter.
    pub fn inc_keepalive_count(&mut self) {
        self.keepalive_count += 1;
    }

    /// Check for flooding and reset counters if the interval elapsed.
    ///
    /// Returns `true` if flooding was detected (peer should be disconnected).
    /// Mirrors C++ `DefaultBtInteractive::detectMessageFlooding()`.
    ///
    /// Per C++ behavior, flooding is only detected at interval boundaries.
    /// Within an interval, this always returns `false` — we must observe
    /// the full window before concluding that the peer is flooding.
    pub fn check_and_reset(&mut self) -> bool {
        if self.last_reset.elapsed() >= self.check_interval {
            let flooding = self.choke_unchoke_count >= self.choke_unchoke_threshold
                || self.keepalive_count >= self.keepalive_threshold;
            self.reset();
            flooding
        } else {
            // Within the same interval — cannot determine flooding yet.
            // C++ only checks at interval boundaries.
            false
        }
    }

    /// Reset all counters.
    pub fn reset(&mut self) {
        self.choke_unchoke_count = 0;
        self.keepalive_count = 0;
        self.last_reset = Instant::now();
    }

    /// Get current choke/unchoke count (for testing).
    pub fn choke_unchoke_count(&self) -> u32 {
        self.choke_unchoke_count
    }

    /// Get current keepalive count (for testing).
    pub fn keepalive_count(&self) -> u32 {
        self.keepalive_count
    }
}

impl Default for FloodingStat {
    fn default() -> Self {
        Self::new()
    }
}

// ===========================================================================
// ActiveInteractionChecker — inactivity detection
// ===========================================================================

/// Timer-based checker for detecting inactive peers that should be dropped.
///
/// Mirrors C++ `checkActiveInteraction()` logic in `DefaultBtInteractive`:
/// - 30s mutual-uninterested → drop
/// - 60s total inactivity → drop
/// - seeder-to-seeder → drop
#[derive(Debug, Clone)]
pub struct ActiveInteractionChecker {
    /// When the inactive timer started
    inactive_since: Instant,
    /// Mutual-uninterested timeout (default 30s)
    mutual_uninterested_timeout: Duration,
    /// Total inactivity timeout (default 60s)
    inactivity_timeout: Duration,
    /// Timestamp of the last data exchange (piece/unchoke received).
    /// Reset by `record_data_exchange()`.
    last_data_exchange: Instant,
}

impl ActiveInteractionChecker {
    /// Create a new active interaction checker with default timeouts.
    pub fn new() -> Self {
        Self {
            inactive_since: Instant::now(),
            mutual_uninterested_timeout: Duration::from_secs(30),
            inactivity_timeout: Duration::from_secs(60),
            last_data_exchange: Instant::now(),
        }
    }

    /// Check whether the peer should be dropped due to inactivity.
    ///
    /// Returns `Some(InactiveReason)` if the peer should be disconnected,
    /// or `None` if the peer is still considered active.
    pub fn check(
        &self,
        am_interested: bool,
        peer_interested: bool,
        is_seeder: bool,
        peer_is_seeder: bool,
    ) -> Option<InactiveReason> {
        let elapsed = self.inactive_since.elapsed();

        // Seeder-to-seeder: no possible data exchange
        if is_seeder && peer_is_seeder {
            return Some(InactiveReason::SeederToSeeder);
        }

        // Mutual uninterested timeout
        if !am_interested && !peer_interested && elapsed >= self.mutual_uninterested_timeout {
            return Some(InactiveReason::MutualUninterested);
        }

        // Total inactivity timeout
        if elapsed >= self.inactivity_timeout {
            return Some(InactiveReason::NoDataExchange);
        }

        None
    }

    /// Reset the inactive timer (called when data is exchanged).
    pub fn reset_timer(&mut self) {
        self.inactive_since = Instant::now();
    }

    /// Record that a data exchange occurred (piece/unchoke received).
    /// Resets the inactivity timer.
    pub fn record_data_exchange(&mut self) {
        self.last_data_exchange = Instant::now();
    }
}

impl Default for ActiveInteractionChecker {
    fn default() -> Self {
        Self::new()
    }
}

// ===========================================================================
// SlotCheckResult — result of periodic request-slot validation
// ===========================================================================

/// Result of checking outstanding request slots for timeouts and
/// already-acquired blocks.
///
/// Returned by `BtMessageDispatcher::check_request_slots()`.
#[derive(Debug, Clone, Default)]
pub struct SlotCheckResult {
    /// Whether any request slot timed out (peer may be snubbing)
    pub timed_out: bool,
    /// Blocks that have been acquired from another peer and need Cancel messages.
    /// Each tuple is (piece_index, begin, length).
    pub cancelled_blocks: Vec<(u32, u32, u32)>,
}

// ===========================================================================
// PendingMessage — tagged outgoing message
// ===========================================================================

/// A tagged outgoing message in the per-peer send queue.
///
/// The tag distinguishes upload (Piece) messages from control messages
/// (Choke, Unchoke, Request, Cancel, etc.) so that:
///
/// - `do_choking_action()` can remove all upload messages when we choke the peer.
/// - `do_cancel_sending_piece_action()` can remove a specific upload message.
/// - `drain_sendable_messages()` can defer upload messages when upload speed
///   is limited (mirroring C++ `sendMessagesInternal()` which checks
///   `isUploading()` per message).
///
/// Mirrors C++ `BtMessage::isUploading()` which returns true for Piece messages.
#[derive(Debug)]
enum PendingMessage {
    /// A non-upload control message (Choke, Unchoke, Request, Cancel, etc.)
    Control(Vec<u8>),
    /// A Piece upload message carrying data for the specified block.
    Upload {
        data: Vec<u8>,
        index: u32,
        begin: u32,
        length: u32,
    },
}

// ===========================================================================
// BtMessageDispatcher — per-peer outgoing message queue + request slots
// ===========================================================================

/// Per-peer message dispatcher holding the outgoing message queue and
/// outstanding request slots.
///
/// Mirrors C++ `DefaultBtMessageDispatcher`. Each peer connection has
/// one dispatcher instance that:
/// - Queues outgoing messages (Request, Piece, Choke, Unchoke, etc.)
/// - Tracks outstanding Request slots until Piece responses arrive
/// - Handles choke/unchoke side effects on the request queue
/// - Validates slots for timeouts and already-acquired blocks
#[derive(Debug)]
pub struct BtMessageDispatcher {
    /// Block size for computing block indices
    block_size: u32,
    /// Outstanding request slots (pub(crate) for test access)
    pub(crate) request_slots: Vec<RequestSlot>,
    /// Outgoing message queue with upload/control tagging.
    /// Mirrors C++ `messageQueue_` which holds `unique_ptr<BtMessage>`.
    message_queue: Vec<PendingMessage>,
    /// Whether the global upload speed limit is exceeded
    upload_speed_exceeded: bool,
    /// Whether the per-group upload speed limit is exceeded
    group_upload_speed_exceeded: bool,
    /// Request timeout (default 60s, matching C++ `requestTimeout_`)
    request_timeout: Duration,
}

impl BtMessageDispatcher {
    /// Create a new dispatcher with the given block size.
    pub fn new(block_size: u32) -> Self {
        Self {
            block_size,
            request_slots: Vec::new(),
            message_queue: Vec::new(),
            upload_speed_exceeded: false,
            group_upload_speed_exceeded: false,
            request_timeout: Duration::from_secs(60),
        }
    }

    /// Add a request slot to track an outstanding Request message.
    pub fn add_request_slot(&mut self, index: u32, begin: u32, length: u32) {
        let slot = RequestSlot::new(index, begin, length, self.block_size);
        self.request_slots.push(slot);
    }

    /// Remove a request slot matching the given piece/block coordinates.
    ///
    /// Returns `true` if a matching slot was found and removed.
    pub fn remove_request_slot(&mut self, index: u32, begin: u32, length: u32) -> bool {
        if let Some(pos) = self
            .request_slots
            .iter()
            .position(|s| s.matches(index, begin, length))
        {
            self.request_slots.swap_remove(pos);
            true
        } else {
            false
        }
    }

    /// Add a serialized Request message to the outgoing queue.
    pub fn add_request_message(&mut self, data: Vec<u8>, _index: u32, _begin: u32, _length: u32) {
        self.message_queue.push(PendingMessage::Control(data));
    }

    /// Add a control message (non-upload) to the outgoing queue.
    pub fn add_control_message(&mut self, data: Vec<u8>) {
        self.message_queue.push(PendingMessage::Control(data));
    }

    /// Add a Piece upload message to the outgoing queue.
    ///
    /// Unlike the previous stub that silently dropped messages when upload
    /// was limited, this always queues the message. Upload speed filtering
    /// is applied at drain time, mirroring C++ `sendMessagesInternal()`
    /// which defers upload messages when speed is exceeded.
    pub fn add_upload_message(&mut self, data: Vec<u8>, index: u32, begin: u32, length: u32) {
        self.message_queue.push(PendingMessage::Upload {
            data,
            index,
            begin,
            length,
        });
    }

    /// Handle a Choke message received from the peer.
    ///
    /// Removes outstanding request slots for pieces NOT in the allowed-fast set.
    /// Returns removed slots so the caller can send Cancel messages.
    ///
    /// Mirrors C++ `DefaultBtMessageDispatcher::doChokedAction()`.
    pub fn do_choked_action<F>(&mut self, is_in_allowed_fast: F) -> Vec<RequestSlot>
    where
        F: Fn(u32) -> bool,
    {
        let mut removed = Vec::new();
        self.request_slots.retain(|slot| {
            if is_in_allowed_fast(slot.index) {
                true // Keep: piece is in allowed-fast set
            } else {
                removed.push(slot.clone());
                false
            }
        });
        removed
    }

    /// Handle sending a Choke message to the peer.
    ///
    /// Removes all queued Piece upload messages since we are choking
    /// the peer and should not send them data.
    ///
    /// Mirrors C++ `DefaultBtMessageDispatcher::doChokingAction()` which
    /// calls `onChokingEvent()` on each queued message. For Piece messages,
    /// `onChokingEvent()` invalidates them (marks as not-to-send).
    pub fn do_choking_action(&mut self) {
        self.message_queue
            .retain(|msg| !matches!(msg, PendingMessage::Upload { .. }));
    }

    /// Handle receiving a Cancel message from the peer.
    ///
    /// Removes any queued Piece upload message that matches the specified block.
    ///
    /// Mirrors C++ `DefaultBtMessageDispatcher::doCancelSendingPieceAction()`
    /// which calls `onCancelSendingPieceEvent()` on each queued message.
    /// For a matching Piece message, this invalidates it.
    pub fn do_cancel_sending_piece_action(&mut self, index: u32, begin: u32, length: u32) {
        self.message_queue.retain(|msg| {
            !matches!(msg, PendingMessage::Upload {
                index: idx,
                begin: b,
                length: l,
                ..
            } if *idx == index && *b == begin && *l == length)
        });
    }

    /// Abort all outstanding requests for the given piece index.
    ///
    /// Called when a piece is reassigned to another peer. Returns
    /// removed request slots.
    ///
    /// Mirrors C++ `DefaultBtMessageDispatcher::doAbortOutstandingRequestAction()`.
    pub fn do_abort_outstanding_request_action(&mut self, piece_index: u32) -> Vec<RequestSlot> {
        let mut removed = Vec::new();
        self.request_slots.retain(|slot| {
            if slot.index == piece_index {
                removed.push(slot.clone());
                false
            } else {
                true
            }
        });
        removed
    }

    /// Check request slots for timeouts and already-acquired blocks.
    ///
    /// Should be called approximately once per second. Returns a
    /// [`SlotCheckResult`] indicating timed-out slots and blocks
    /// that need Cancel messages.
    ///
    /// Mirrors C++ `DefaultBtMessageDispatcher::checkRequestSlotAndDoNecessaryThing()`.
    pub fn check_request_slots<F>(&mut self, is_block_acquired: F) -> SlotCheckResult
    where
        F: Fn(u32, u32) -> bool,
    {
        let mut result = SlotCheckResult::default();
        let timeout = self.request_timeout;

        self.request_slots.retain(|slot| {
            // Check for timeout
            if slot.is_timed_out(timeout) {
                result.timed_out = true;
                return false;
            }
            // Check if block was acquired from another peer
            if is_block_acquired(slot.index, slot.block_index) {
                result
                    .cancelled_blocks
                    .push((slot.index, slot.begin, slot.length));
                return false;
            }
            true
        });

        result
    }

    /// Count outstanding request slots.
    pub fn count_request_slots(&self) -> usize {
        self.request_slots.len()
    }

    /// Check if there are any outstanding request slots.
    pub fn has_outstanding_requests(&self) -> bool {
        !self.request_slots.is_empty()
    }

    /// Check if there is an outstanding request for the given piece+block.
    pub fn is_outstanding_request(&self, index: u32, block_index: u32) -> bool {
        self.request_slots
            .iter()
            .any(|s| s.index == index && s.block_index == block_index)
    }

    /// Drain messages that are ready to be sent.
    ///
    /// Upload (Piece) messages are deferred when upload speed limiting is
    /// active; they remain in the queue for a later drain attempt.
    /// Control messages are always drained.
    ///
    /// Mirrors C++ `sendMessagesInternal()` which checks `isUploading()`
    /// per message and moves upload messages to `tempQueue` when speed
    /// limits are exceeded, then re-inserts them at the front of the queue.
    pub fn drain_sendable_messages(&mut self) -> Vec<Vec<u8>> {
        let mut sendable = Vec::new();
        let mut deferred = Vec::new();

        // Cache the upload-limited flag before draining to avoid borrowing `self`
        // while iterating over `self.message_queue`.
        let upload_limited = self.is_upload_limited();

        for msg in self.message_queue.drain(..) {
            match msg {
                PendingMessage::Control(data) => {
                    sendable.push(data);
                }
                PendingMessage::Upload {
                    data,
                    index,
                    begin,
                    length,
                } => {
                    if upload_limited {
                        // Defer: re-queue the upload message
                        deferred.push(PendingMessage::Upload {
                            data,
                            index,
                            begin,
                            length,
                        });
                    } else {
                        sendable.push(data);
                    }
                }
            }
        }

        // Re-insert deferred upload messages (preserving order, matching C++
        // which inserts tempQueue at the front of messageQueue_).
        if !deferred.is_empty() {
            deferred.append(&mut self.message_queue);
            self.message_queue = deferred;
        }

        sendable
    }

    /// Check if there are pending messages in the queue.
    pub fn has_pending_messages(&self) -> bool {
        !self.message_queue.is_empty()
    }

    /// Count messages in the outgoing queue.
    pub fn count_messages(&self) -> usize {
        self.message_queue.len()
    }

    /// Set whether the global upload speed limit is exceeded.
    pub fn set_upload_speed_exceeded(&mut self, exceeded: bool) {
        self.upload_speed_exceeded = exceeded;
    }

    /// Set whether the per-group upload speed limit is exceeded.
    pub fn set_group_upload_speed_exceeded(&mut self, exceeded: bool) {
        self.group_upload_speed_exceeded = exceeded;
    }

    /// Check if upload speed limiting is active (either global or per-group).
    pub fn is_upload_limited(&self) -> bool {
        self.upload_speed_exceeded || self.group_upload_speed_exceeded
    }

    /// Clear all messages and request slots.
    pub fn clear(&mut self) {
        self.request_slots.clear();
        self.message_queue.clear();
        self.upload_speed_exceeded = false;
        self.group_upload_speed_exceeded = false;
    }
}