Jack Tricker, 21 March 2025 (updated 2 September 2026)
btjt is a small command-line BitTorrent downloader written in Go. You give it a .torrent file and it downloads what the file describes:
./btjt -o ~/Downloads test_torrents/http.torrent
It uses nothing outside Go's standard library, so the file parser, the tracker requests and the peer protocol are all in its 1,700 lines. I started it on 14 February 2025.
A .torrent file is bencoded, a format with four types: integers, byte strings, lists and dictionaries. The decoder is about 170 lines. Larger torrent files broke it at first, because Go's buffered reader holds 4 KB unless you ask for more. It now gets a buffer the size of the file.
Every torrent is identified by its info hash, which is the SHA-1 of one section of the file, the info dictionary, exactly as the bytes appear. The decoder therefore has to note where that section starts and ends as it reads. My first version ended the section early whenever info contained another dictionary, which every multi-file torrent does. The fix for that ran past the end of the section whenever another key followed it. The third version records the end as soon as the value has been read.
A tracker is a web server that hands out the addresses of other people downloading the same torrent. The request carries the info hash as a URL parameter, and since the hash is 20 raw bytes it has to be percent-encoded. I wrote an encoder for that and the requests didn't work. I routed the client through Burp to read what it was sending, and the URL had this in it:
info_hash=c%2520%2590%25228c%25eb...
%25 is a percent sign, encoded. My encoder had produced %20, %90 and so on, and then Go's url.Values encoded the percent signs a second time. I deleted my encoder and passed the raw bytes to the library.
The tracker replies with a list of peers packed into six bytes each: four for the IPv4 address and two for the port.
Peers speak a binary protocol over TCP. It opens with a 68-byte handshake: a length byte, the string "BitTorrent protocol", eight reserved bytes, the info hash and a peer ID. By 20 February the client could send one and get one back.
The piece count was wrong for a while too. I had it as the total length divided by the piece length, plus one, which is one too many when the length is an exact multiple of the piece length.
On 19 March the client received the first block of the first piece. I stopped two days later. It could find peers and fetch a block, but it couldn't download a file.
I came back to it on 2 September 2026 and finished it that afternoon.
Each connected peer now gets its own goroutine and keeps five block requests in flight. A block that hasn't arrived after 15 seconds can be claimed by another peer. When a piece is complete, its SHA-1 is checked against the hash in the torrent file, and a piece that fails is thrown away and fetched again. Verified pieces are written to the right offset on disk, including pieces that span two files in a multi-file torrent. UDP trackers work as well as HTTP ones.
It still only downloads. There is no seeding, no resuming, no DHT and no magnet links, and it asks for pieces in order, where most clients ask for the rarest first.
[ Return to top ] [ All writing ]