IronTide

A BitTorrent client has dozens of things happening at once: peers connecting and dropping, pieces being verified, trackers being polled, the UI updating. Mutexes everywhere is the obvious approach and a debugging nightmare. Instead, each peer is its own tokio task, each piece-picker its own task, each tracker session its own task, all communicating through typed channels. tokio's select! macro is the load-bearing primitive. I learned quickly that structured concurrency isn't optional here — without it, the system becomes impossible to reason about within a few days.

Hand-rolling the wire protocol means writing a length-prefixed message framer, a bencode parser that doesn't allocate per-key, peer handshake with extension negotiation (BEP-10), µTP for UDP transport, Mainline DHT for trackerless discovery, and PEX for peer exchange. Bencode taught me to write a streaming parser. µTP taught me that TCP-on-UDP congestion control is harder than it looks — LEDBAT, sequence numbers, selective ACKs. DHT is where you learn what it means to talk to thousands of strangers' implementations of the same RFC, all of which behave slightly differently.

Concurrent code under tokio is non-deterministic by default — the scheduler picks tasks however it wants, so a test passes 99 times and fails on the build server. I swap tokio for a deterministic runtime in tests: same APIs, but every poll is scheduled by a seeded PRNG. A failing test prints its seed, and you replay it byte-for-byte to watch the bug happen again. FoundationDB and TigerBeetle use this approach. Getting a working version running in this project changed how I think about testing async systems.

Bytes come off a TCP socket, get verified against a SHA-1 piece hash, and need to land at the right offset of the right file. Naively that's three or four allocations per chunk. With io_uring and Bytes (refcounted buffer slices) you can do it in one. But zero-copy only works if every actor in the pipeline honours it, and any buffering decision becomes a backpressure decision. When the disk is slow, the network task has to feel it — not by dropping packets, but by yielding upstream until the channel drains. Getting this right is what keeps memory usage flat instead of climbing.

Storage is a trait. Network transport is a trait. The piece picker is a trait. Sounds like over-engineering until you write the first integration test and realise you need to swap the disk for an in-memory implementation and the network for a deterministic one. The abstractions exist because testing demanded them, not because I planned for hypothetical future backends.

Splitting the project into 17 crates wasn't aesthetic — each crate is a compilation boundary, an API surface, and a rebuild horizon. When peer-protocol changes, disk-io doesn't rebuild. When the UI changes, the engine doesn't rebuild. That matters when a full build takes 90 seconds instead of 9. It also forces you to think about layering: what does this crate depend on, and what is it allowed to know about? You end up enforcing those boundaries in the dependency graph instead of in your head.