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
//! Periodic choke-round command — Rust equivalent of C++ `PeerChokeCommand`.
//!
//! In the C++ codebase, `PeerChokeCommand` is a long-lived `Command` that
//! re-adds itself to the engine's command queue on every execution. It checks
//! whether the choke-round interval has elapsed and, if so, executes a choke
//! round on the peer storage.
//!
//! In the Rust async architecture, we expose `PeerChokeDriver` which can be
//! called periodically (e.g. from a timer tick or a download command's execute
//! loop). It encapsulates the same interval-check + execute logic.
//!
//! # C++ Equivalence
//!
//! | Rust | C++ |
//! |---|---|
//! | `PeerChokeDriver` | `PeerChokeCommand` |
//! | `PeerChokeDriver::tick()` | `PeerChokeCommand::execute()` |
//! | `should_execute()` | `chokeRoundIntervalElapsed()` |
use std::time::Duration;
use crate::engine::bt_choke_manager::{BtLeecherStateChoke, BtSeederStateChoke};
use crate::engine::peer_stats::PeerStats;
/// Default choke round interval in seconds.
/// Mirrors C++ `10_s` used in `DefaultPeerStorage`.
pub const DEFAULT_CHOKE_ROUND_INTERVAL_SECS: u64 = 10;
// ===========================================================================
// PeerChokeDriver
// ===========================================================================
/// Periodic choke-round driver, equivalent to C++ `PeerChokeCommand`.
///
/// Encapsulates the seeder/leecher choke algorithms and the interval check.
/// Call [`tick`](Self::tick) periodically; it will execute a choke round
/// only when the interval has elapsed.
///
/// # Usage
///
/// ```ignore
/// let mut driver = PeerChokeDriver::new(choke_interval);
/// // Call on every timer tick (~1s):
/// driver.tick(halt, download_finished, &mut peer_refs);
/// ```
#[derive(Debug, Clone)]
pub struct PeerChokeDriver {
/// Choke round interval.
interval: Duration,
/// Seeder-state choking algorithm.
seeder_choke: BtSeederStateChoke,
/// Leecher-state choking algorithm.
leecher_choke: BtLeecherStateChoke,
/// Whether the download has finished (determines seeder vs leecher mode).
download_finished: bool,
}
impl PeerChokeDriver {
/// Create a new `PeerChokeDriver` with the given choke round interval.
pub fn new(interval: Duration) -> Self {
Self {
interval,
seeder_choke: BtSeederStateChoke::new(),
leecher_choke: BtLeecherStateChoke::new(),
download_finished: false,
}
}
/// Create a `PeerChokeDriver` with the default 10-second interval.
pub fn with_default_interval() -> Self {
Self::new(Duration::from_secs(DEFAULT_CHOKE_ROUND_INTERVAL_SECS))
}
/// Create a `PeerChokeDriver` with a custom number of seeder unchoke slots.
///
/// Useful for testing or configuration override.
pub fn with_seeder_slots(slots: usize) -> Self {
let mut driver = Self::with_default_interval();
driver.seeder_choke = BtSeederStateChoke::with_slots(slots);
driver
}
/// Set whether the download has finished (affects seeder vs leecher mode).
pub fn set_download_finished(&mut self, finished: bool) {
self.download_finished = finished;
}
/// Get whether the download has finished.
pub fn download_finished(&self) -> bool {
self.download_finished
}
/// Check whether a choke round should be executed based on the interval.
///
/// Mirrors C++ `PeerChokeCommand::execute()` checking
/// `peerStorage_->chokeRoundIntervalElapsed()`.
pub fn should_execute(&self) -> bool {
if self.download_finished {
self.seeder_choke.should_execute(self.interval)
} else {
self.leecher_choke.should_execute(self.interval)
}
}
/// Execute a choke round if the interval has elapsed.
///
/// Mirrors C++ `PeerChokeCommand::execute()`:
/// 1. If the runtime is halted, do nothing (return `false`).
/// 2. If the interval has elapsed, execute the appropriate choke algorithm.
/// 3. Returns `true` if a choke round was executed.
///
/// # Arguments
///
/// * `halt` - Whether the BT runtime is halted (stop downloading/seeding).
/// * `peers` - Mutable slice of peer statistics to update.
///
/// # Returns
///
/// `true` if a choke round was executed this tick, `false` otherwise.
pub fn tick(&mut self, halt: bool, peers: &mut [&mut PeerStats]) -> bool {
if halt {
return false;
}
if !self.should_execute() {
return false;
}
self.execute_choke(peers);
true
}
/// Force-execute a choke round regardless of the interval.
///
/// Useful for testing or immediate choke adjustment after a peer state
/// change (e.g. peer disconnect).
pub fn execute_choke_by_identity(&mut self, peers: &mut [&mut PeerStats]) {
if self.download_finished {
self.seeder_choke.execute_choke_by_identity(peers);
} else {
self.leecher_choke.execute_choke_by_identity(peers);
}
}
pub fn execute_choke(&mut self, peers: &mut [&mut PeerStats]) {
self.execute_choke_by_identity(peers);
}
// ------------------------------------------------------------------
// Accessors for testing / diagnostics
// ------------------------------------------------------------------
/// Get a reference to the seeder-state choke algorithm.
pub fn seeder_choke(&self) -> &BtSeederStateChoke {
&self.seeder_choke
}
/// Get a reference to the leecher-state choke algorithm.
pub fn leecher_choke(&self) -> &BtLeecherStateChoke {
&self.leecher_choke
}
/// Get the current round of the active choke algorithm.
pub fn round(&self) -> u32 {
if self.download_finished {
self.seeder_choke.round()
} else {
self.leecher_choke.round()
}
}
/// Get the choke round interval.
pub fn interval(&self) -> Duration {
self.interval
}
}
impl Default for PeerChokeDriver {
fn default() -> Self {
Self::with_default_interval()
}
}
// ===========================================================================
// Tests
// ===========================================================================
#[cfg(test)]
mod tests {
use super::*;
use crate::engine::peer_stats::PeerStats;
fn make_peer() -> PeerStats {
PeerStats::new([0u8; 20], "127.0.0.1:6881".parse().unwrap())
}
/// Convert a mutable slice of PeerStats into the `Vec<&mut PeerStats>`
/// format required by `execute_choke` / `tick`.
fn to_refs(peers: &mut [PeerStats]) -> Vec<&mut PeerStats> {
peers.iter_mut().collect()
}
#[test]
fn test_driver_default_interval() {
let driver = PeerChokeDriver::default();
assert_eq!(driver.interval(), Duration::from_secs(10));
}
#[test]
fn test_driver_should_execute_initially() {
// No rounds have been executed — interval should be considered elapsed.
let driver = PeerChokeDriver::with_default_interval();
assert!(driver.should_execute());
}
#[test]
fn test_driver_tick_executes_choke_round() {
let mut driver = PeerChokeDriver::with_default_interval();
let mut peers = [make_peer()];
let mut refs = to_refs(&mut peers);
let executed = driver.tick(false, &mut refs[..]);
assert!(executed, "First tick should execute a choke round");
// After execution, interval has not elapsed — next tick should not execute.
let mut refs = to_refs(&mut peers);
let executed2 = driver.tick(false, &mut refs[..]);
assert!(
!executed2,
"Immediate second tick should not execute (interval not elapsed)"
);
}
#[test]
fn test_driver_tick_halting_does_not_execute() {
let mut driver = PeerChokeDriver::with_default_interval();
let mut peers = [make_peer()];
let mut refs = to_refs(&mut peers);
let executed = driver.tick(true, &mut refs[..]);
assert!(!executed, "Should not execute when halted");
}
#[test]
fn test_driver_seeder_mode() {
let mut driver = PeerChokeDriver::with_default_interval();
driver.set_download_finished(true);
assert!(driver.download_finished());
let mut peers = {
let mut p = make_peer();
p.peer_interested = true;
[p]
};
let mut refs = to_refs(&mut peers);
let executed = driver.tick(false, &mut refs[..]);
assert!(executed);
// Peer should be unchoked (seeder unchokes interested peers)
assert!(!peers[0].am_choking);
}
#[test]
fn test_driver_leecher_mode() {
let mut driver = PeerChokeDriver::with_default_interval();
assert!(!driver.download_finished());
let mut peers = {
let mut p = make_peer();
p.peer_interested = true;
[p]
};
let mut refs = to_refs(&mut peers);
let executed = driver.tick(false, &mut refs[..]);
assert!(executed);
// In leecher mode with only one interested peer, it should be unchoked
assert!(!peers[0].am_choking);
}
#[test]
fn test_driver_round_advances() {
let mut driver = PeerChokeDriver::with_default_interval();
let mut peers = {
let mut p = make_peer();
p.peer_interested = true;
[p]
};
assert_eq!(driver.round(), 0);
let mut refs = to_refs(&mut peers);
driver.execute_choke(&mut refs[..]);
assert_eq!(driver.round(), 1);
let mut refs = to_refs(&mut peers);
driver.execute_choke(&mut refs[..]);
assert_eq!(driver.round(), 2);
let mut refs = to_refs(&mut peers);
driver.execute_choke(&mut refs[..]);
assert_eq!(driver.round(), 0); // wraps
}
#[test]
fn test_driver_force_execute() {
let mut driver = PeerChokeDriver::with_default_interval();
let mut peers = {
let mut p = make_peer();
p.peer_interested = true;
[p]
};
// Execute first round
let mut refs = to_refs(&mut peers);
driver.execute_choke(&mut refs[..]);
// Force-execute second round even though interval hasn't elapsed
let mut refs = to_refs(&mut peers);
driver.execute_choke(&mut refs[..]);
assert_eq!(driver.round(), 2);
}
#[test]
fn test_driver_with_seeder_slots() {
let driver = PeerChokeDriver::with_seeder_slots(2);
// Should create a driver with 2 seeder unchoke slots
assert_eq!(driver.interval(), Duration::from_secs(10));
}
}