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
//! BT Request Factory — generates Request messages for missing blocks
//!
//! This module implements the C++ `DefaultBtRequestFactory` architecture,
//! managing a per-peer target piece list and generating Request messages
//! for blocks that need to be downloaded.
//!
//! # C++ Architecture Reference
//!
//! - `src/DefaultBtRequestFactory.h/.cc` — Request message factory
//! - `src/BtRequestFactory.h` — Abstract interface
//!
//! # Key Differences from C++
//!
//! - C++ stores `shared_ptr<Piece>` and interacts with `BtMessageDispatcher`
//! and `BtMessageFactory` via raw pointers. Rust uses `Piece` by value
//! (with `PartialEq` by index) and returns `PieceBlockRequest` data
//! structures instead of serialized messages.
//! - C++ `doChokedAction()` uses `Peer::isInPeerAllowedIndexSet()`.
//! Rust passes a closure `is_in_allowed_fast(index) -> bool`.
//! - C++ `createRequestMessagesOnEndGame()` uses `Piece::getAllMissingBlockIndexes()`
//! + `BtMessageDispatcher::isOutstandingRequest()`. Rust uses
//! `Piece::missing_block_bitfield_bytes()` + a closure for outstanding checks.
//! - C++ relies on `BtMessageDispatcher::doAbortOutstandingRequestAction()`.
//! Rust returns piece indices so the caller can perform the abort.
// Sub-modules define `impl BtRequestFactory` blocks; no new public items to re-export.
use VecDeque;
use cratePiece;
/// Lightweight request descriptor returned by the factory.
///
/// Contains the three fields of a BT Request message payload:
/// `index` (piece index), `begin` (byte offset within piece), `length` (block length).
// ======================================================================
// PieceStorageProvider trait — abstraction for piece_storage dependency
// ======================================================================
/// Trait abstracting the piece storage operations needed by BtRequestFactory.
///
/// In C++ `DefaultBtRequestFactory`, `pieceStorage_` is a raw pointer to
/// `PieceStorage`, used only for `cancelPiece()`. This trait exposes just
/// that one operation so the factory remains decoupled from the full
/// `PieceStorage` trait.
// ======================================================================
// BtRequestFactory
// ======================================================================
/// BitTorrent request factory, matching C++ `DefaultBtRequestFactory`.
///
/// Manages a per-peer target piece list and generates Request messages
/// for missing blocks. Two modes of operation:
///
/// 1. **Normal mode** — requests missing+unused blocks (not in-use by
/// another peer), marking them as in-use before returning.
/// 2. **Endgame mode** — requests all missing blocks regardless of in-use
/// status, skipping blocks that already have an outstanding request.
/// Block order is shuffled to distribute load across peers.
///
/// # Cancellation Protocol
///
/// When a piece is removed (via `remove_target_piece()`, `remove_all_target_pieces()`,
/// or `do_choked_action()`), the factory returns the affected piece indices so
/// the caller can:
/// 1. Call `BtMessageDispatcher::do_abort_outstanding_request_action()` to
/// remove matching request slots and invalidate queued Request messages.
/// 2. The factory itself calls `PieceStorageProvider::cancel_piece()` to
/// release the piece back to the pool.