IronTide
A BitTorrent engine library in Rust, published on crates.io and reopened for a 2.0 correctness recovery.
In recovery; 1.7.0 on crates.io
Description
BitTorrent looked simple on paper and was hard in code: many peers, untrusted bytes on every connection, an unreliable network, and state shared across all of it. I picked it as my first serious systems project because every layer had to work against real swarms or nothing downloaded. The engine shipped on crates.io as a library other applications embed. In September 2026 I reopened it to repair correctness and measurement before making any claim about speed.
Block diagram
- Your app
- SessionActor
- TorrentActor
- Peer tasks
- Disk storage
Decisions
Actors and channels instead of shared locks
Each concern owns its state and is driven by messages: a SessionActor for session-wide state, one TorrentActor per torrent for piece selection, choking and verification, and a set of tasks per peer. Commands travel over bounded channels, and a slow consumer is disconnected instead of stalling the swarm. The cost is that ordering and cancellation across actors have to be designed explicitly, and most of the recovery's repairs sit in that area.
Test the real actors on a simulated network
irontide-sim replaces sockets with an in-process network and a virtual clock and runs the real session actors over it, with storage decorators that corrupt pieces, inject failures or slow verification. Protocol cores such as the MSE handshake, DHT lookup, uTP congestion control and the codecs are sans-IO state machines, so they run in tests without sockets. Multi-peer swarm tests become repeatable with no network traffic.
Correctness before any speed claim
The old live-swarm benchmarks used counters and completion signals that turned out to be defective, so the recovery keeps them as records only. The 2.0 plan requires independently verified output, pinned reference engines and controlled networks before any comparison, and it repairs the engine through bounded subsystem replacements instead of a rewrite.
Errata
- Open recovery defects include pure-v2 torrent identity, v2-swarm handshakes on hybrid torrents, pad-file accounting and resume.
- Fixes on the recovery branch are unpublished; crates.io still serves 1.7.0.
Revision history
| Version | Changes |
|---|---|
| 1.7.0 | uTP actor isolation, bounded LEDBAT delay history, bounded metadata scheduling, trimmed tokio features. |
| 1.6.0 | Version alignment with the client; no engine code change from 1.5.0. |
| 1.5.0 | Hardening pass; removed dead Settings fields, a breaking change released as a minor. |
| 1.4.0 | TorrentActor structural refactor with no behaviour change. |