feat: Implement BEP 3-compatible choking algorithm

[artrixdotdev]

Closes #206

Summary by CodeRabbit

• New Features
  • Added periodic torrent choking/unchoking with regular slot selection plus an optimistic unchoke that rotates over time.
  • Torrent scheduling now re-evaluates peers during download/seeding and applies choke changes based on recent transfer performance.
• Bug Fixes
  • Prevented choked peers from issuing piece requests.
  • Improved upload/download accounting so transfer rates and statistics stay accurate.
• Documentation
  • Added architecture notes for the choking scheduler and decision flow.
• Tests
  • Updated timing/persistence assertions for piece-progress validation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 68b9fe0e-c17b-4473-9401-5265caf9515f

📥 Commits

Reviewing files that changed from the base of the PR and between cd099dc and f9e8d69.

📒 Files selected for processing (4)

• crates/libtortillas/src/peer/actor.rs
• crates/libtortillas/src/torrent/actor.rs
• crates/libtortillas/src/torrent/choking_flow.rs
• crates/libtortillas/src/torrent/piece_flow.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• crates/libtortillas/src/torrent/choking_flow.rs
• crates/libtortillas/src/peer/actor.rs

---

Walkthrough

Implements BEP 3 choking behavior across peer stats sampling, peer selection, periodic rechoke scheduling, and architecture documentation.

Changes

BEP 3 Choking Algorithm

Layer / File(s)	Summary
PeerActor rate sampling and choke enforcement crates/libtortillas/src/peer/actor.rs	Adds PeerStats, RateSample, snapshot_stats(), last_rate_sample, choke-aware request handling, upload byte accounting, and updated choke-state transitions.
ChokingScheduler and select_unchoked_peers crates/libtortillas/src/torrent/choking.rs	Adds the scheduler state, decision type, peer selection logic, rate mapping, and unit tests for filtering, slot limits, rate ordering, and optimistic rotation.
TorrentActor rechoke flow and scheduling crates/libtortillas/src/torrent/choking_flow.rs, crates/libtortillas/src/torrent/messages.rs, crates/libtortillas/src/torrent/actor.rs, crates/libtortillas/src/torrent/mod.rs, crates/libtortillas/src/torrent/piece_flow.rs	Adds peer-stat collection, wires the rechoke message, extends TorrentActor with choking scheduler state and timeout handling, updates seeding transitions to trigger rechoke scheduling, and adjusts related tests.
Architecture documentation crates/libtortillas/src/ARCHITECTURE.md	Adds a Choking section describing rechoke timing, upload slot limits, optimistic unchoke rotation, and PeerActor responsibilities.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• artrixdotdev/tortillas#94: Modifies the same PeerActor/TorrentActor area that this PR extends with peer stats and choking flow.
• artrixdotdev/tortillas#193: Touches PeerActor choke/request handling paths that this PR builds on.
• artrixdotdev/tortillas#134: Overlaps with the pending block-request gating changes in PeerActor::Piece handling.

Suggested labels

enhancement, high prio

Suggested reviewers

• kurealnum

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: adding a BEP 3 choking algorithm.
Linked Issues check	✅ Passed	The changes implement periodic rechoke decisions, slot limits, rate-based selection, and optimistic unchoke rotation required by issue #206.
Out of Scope Changes check	✅ Passed	The added documentation, scheduler wiring, and test updates all support the choking algorithm and do not appear out of scope.
Docstring Coverage	✅ Passed	Docstring coverage is 86.49% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/choking-algorithm

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/libtortillas/src/peer/actor.rs`:
- Around line 339-372: The sampled download rate is being based on all received
bytes, including unsolicited pieces. Update the `PeerMessages::Piece` handling
in `PeerActor` so `bytes_downloaded` is only incremented after the block is
confirmed against `pending_block_requests`, and keep `snapshot_stats()` /
`download_rate` ranking driven only by those validated transfers. Ensure the
request-removal and byte accounting stay in the fulfilled-request branch so
`set_download_rate` and rechoke ranking cannot be inflated by unrequested data.

In `@crates/libtortillas/src/torrent/actor.rs`:
- Around line 248-271: The rechoke scheduling path in schedule_next_rechoke is
treating a temporary scheduler failure as terminal, which leaves next_rechoke
unset and stops future rechoke cycles. Update the schedule_next_rechoke flow so
that when scheduler.ask(SetTimeout::new(...)) returns an error, it immediately
retries or falls back to re-arming a new timeout instead of only logging and
exiting. Keep the fix localized to schedule_next_rechoke and the next_rechoke
handling so rechoke() continues to have a valid path to schedule the next round.
- Around line 244-246: The initial rechoke is only being scheduled in the
torrent actor flow, so choking/unchoking decisions do not happen until the timer
fires. Update the `TorrentActor` rechoke path to apply the first rechoke
immediately when entering `Downloading` or `Seeding`, then keep using
`schedule_next_rechoke()` for subsequent intervals. Use the existing
rechoke-related methods in `actor.rs` (especially `schedule_next_rechoke` and
the code that transitions into those states) to place the immediate rechoke call
without changing the recurring timer behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5ec4e1f1-5b8f-4409-b5e5-16628fbd3a0e

📥 Commits

Reviewing files that changed from the base of the PR and between f4a613d and cd099dc.

📒 Files selected for processing (7)

• crates/libtortillas/src/ARCHITECTURE.md
• crates/libtortillas/src/peer/actor.rs
• crates/libtortillas/src/torrent/actor.rs
• crates/libtortillas/src/torrent/choking.rs
• crates/libtortillas/src/torrent/choking_flow.rs
• crates/libtortillas/src/torrent/messages.rs
• crates/libtortillas/src/torrent/mod.rs