Skip to content

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb-rust/issues/27. This local document is retained as the durable engineering spec and evidence record.

RUST-FEAT-038 - Add current-aMule-style endgame source takeover

Summary

Allow healthy sources to take over outstanding blocks near download completion instead of holding an exclusive lease on an entire part until its original source finishes or fails. Current aMule explicitly redistributes final work across sources; Rust's whole-part claim can leave the transfer waiting behind a single slow source even when other useful peers are idle.

Current State

  • crates/emulebb-ed2k/src/ed2k_transfer/block_lease.rs owns block-granular leases, a bounded endgame trigger, stale-lease takeover, and cooldown rules.
  • Runtime tests prove two peers can lease distinct blocks from the same part, dropping a lease preserves verified partial progress, and takeover requires endgame plus bounded stale/no-progress conditions.
  • TCP integration coverage exercises late duplicates, out-of-order ranges, reconnect/resume, cancellation, and stale packets without corrupting piece state or creating ordinary duplicate traffic.
  • Current aMule's DownloadClient.cpp contains endgame redistribution/takeover behavior and the 3.1 release notes call out requesting final blocks from several sources.

Why This Matters

Long-tail completion is user-visible and affects whether a nearly complete file finishes at all when a source stalls. Block-granular ownership also provides a clean foundation for cancelling stale work without discarding valid blocks already received from another source.

Representative Sites

  • EMULEBB_WORKSPACE_ROOT\repos\emulebb-rust\crates\emulebb-ed2k\src\ed2k_transfer\piece_store.rs
  • EMULEBB_WORKSPACE_ROOT\repos\amule\src\DownloadClient.cpp

Intended Shape

  • Represent requested/outstanding ownership at block granularity within a part.
  • Enter an explicit bounded endgame mode when only a small amount of work remains or a lease becomes stale.
  • Permit safe takeover/requeue to another eligible source and cancel obsolete requests when the first verified copy arrives.
  • Preserve source attribution for invalid, duplicate, late, and accepted data.
  • Make deliberate duplicate requests optional and tightly bounded; takeover should not imply uncontrolled redundant traffic.

Scope Constraints

  • First verified block wins; a late valid duplicate must not overwrite data or corrupt counters.
  • Invalid data remains attributable to the sender that supplied it.
  • Respect per-peer request limits, bans, disconnect cleanup, and final completion integrity checks.
  • Do not increase duplicate traffic outside the explicit endgame policy.

Acceptance Criteria

  • [x] A stalled block lease can be reassigned without releasing unrelated valid blocks from the same part.
  • [x] The final blocks can use multiple healthy sources under a documented, bounded endgame trigger.
  • [x] Late, duplicate, cancelled, invalid, and out-of-order responses leave piece state and peer attribution correct.
  • [x] Disconnect/reconnect and process-recovery paths cannot strand a block in an owned-but-unrequestable state.
  • [x] Normal non-endgame transfers do not create duplicate block traffic.
  • [ ] Completion latency improves in a deterministic slow-final-source fixture.

Validation

  • Deterministic scheduler tests with fast, slow, stalled, disconnecting, and malicious peers.
  • Property/state-machine tests for claim, takeover, cancel, receive, verify, and restart transitions.
  • Local current-aMule interop witness demonstrating bounded final-block redistribution and correct completion.

Evidence

  • The 2026-10-18 beta.3 scope audit traced the active scheduler to block_lease.rs, the piece-state tests, and the TCP duplicate, stale, out-of-order, and reconnect fixtures.
  • The complete emulebb-ed2k suite passed 1,161 tests at the filename-scope PR head, including the block-lease and TCP fixtures above.
  • The deterministic slow-final-source latency comparison and retained local current-aMule interoperability witness remain outstanding, so this item stays open.

Notes

This is a current-aMule behavior improvement rather than a strict stock-wire requirement. It should compose with, not substitute for, RUST-BUG-102's final whole-file rehash.