CHANGELOG.md

Changelog

0.6.6 - 2026-08-27

A swarm-health release. Under CGNAT, where a torrent runs on a handful of peers, three separate mechanisms were removing peers we could not afford to lose or parking them on work they were not allowed to do — torrents sat at 99% for hours with unchoked idle peers and unclaimed blocks side by side.

Fixed

• Peers are no longer banned for correctly answering a request we withdrew. A cancel is not atomic: BEP 6 obliges the peer to answer every request exactly once, so a block cancelled, choked or repinned away still arrives one RTT later. Both the piece and the reject landed in the "not outstanding" branch, which disconnected the peer and blacklisted its ID across every torrent — 46 bans from handle_piece and 29 from handle_reject in five minutes, hitting the Fast clients hardest precisely because they are the ones obliged to reject. Withdrawn blocks are now remembered in a bounded per-block count (one answer per request, so arrival order stops mattering) evicted by generation rather than cleared wholesale. An answer matching neither set is wasteful, not malicious: it ends the connection at 512 blocks without banning.
• Fast-extension messages sent without the extension advertised, and frames that stall half-way, no longer ban the peer. 71 of 98 disconnects in one three-minute window were mainstream qBittorrent and Transmission builds. have_all/have_none now go through the normal bitfield handler — a seeder recorded as having nothing is a peer we can never request from — and the advisory messages are logged and ignored. A truncated frame is a congested path, so the connection still drops, but the ID is not blacklisted.
• Peer bans expire. The blacklist was a MapSet that only grew, so one bad frame excluded a peer for the whole session across every torrent: 352 IDs in ten minutes while eight of nine torrents could not exceed three connections. Bans now last 30 minutes with a cap and a background sweep, and each records the rule that fired.
• The dial layer no longer writes off a candidate pool a CGNAT host cannot refill. A failure row was cleared only by mark_productive/3, which asks whether an endpoint was useful rather than whether it is reachable — a leecher we keep choked never delivers bytes and so carried its failure history forever; registration now clears it, inbound peers included. Retention was also refreshed on every failure, so a row re-dialled once per 30 minutes never aged out and reached fail counts above 100; escalation now counts failures within a 10-minute streak window. Sticky blocks became last-resort under min_count pressure (productive, then soft before sticky, then v6 before v4, then fewest failures) instead of refusing resurrection absolutely — 1151 of 1162 active blocks did, leaving a 50-endpoint request returning 3-8.
• Endgame now applies to pieces that were already in flight when the torrent crossed the threshold. A worker read the mode once at State.download/3, so exactly the pieces endgame exists for ran without redundancy: one 1 MiB piece held a torrent at 99.939% for over an hour with all 27 remaining blocks in flight to a single peer that had logged 297 request timeouts on it, while three unchoked peers holding the piece had nothing they were allowed to ask for. :reconcile_pump upgrades active workers level-triggered; the transition is idempotent and one-way and re-queues in-flight subpieces so endgame adds sources for a block rather than taking it from the peer already fetching it.
• A pin is released from an unchoked peer that delivers nothing. The staleness test required choke_me, but a choked peer holds no requests at all — the harmful case was the one it skipped, an unchoked peer sitting on a full 64-request pipeline nobody else may touch. Two such peers re-requested their 64 blocks 821 and 622 times in five minutes while two pieces with every block unclaimed had no peer. Zero bytes now releases the pin either way, on a longer threshold when unchoked (60 s, more than a block timeout) than when choked.
• A peer is no longer repinned off the piece it is fetching. "Drained" ignored who had claimed the blocks, so a peer that had claimed the rest of its piece made it look finished, was moved away, and the move cancelled the very requests that drained it — oscillating at the 2 s tick, 17 wire requests per block received. Draining now also requires no in-flight requests from that peer. Measured over seven minutes live: requests per block 17:1 → 1.1:1, re-request factor 5.66× → 1.08×, swarm 28 → 73 peers, 1.79 → 2.47 MB/s.
• Two endgame defects that parked torrents just short of completion: the drained-pin probe branched on the torrent's mode rather than the worker's, holding a pin for work that worker could never hand out, and endgame_preferred_index/2 destructured the peer key backwards ({_hash, peer_id} against Peer.make_key/2's {id, hash}), hashing the torrent hash and so funnelling the entire swarm onto one index.
• Outside endgame, a peer may leave a piece whose blocks are all claimed. piece_has_waiting?/2 counts blocks in flight to other peers, which a normal-mode worker can never hand out — 27 of 37 peers were pinned to 4 claimed pieces while 8 pieces with 49-64 free blocks had no peer at all.
• A piece worker whose holders have all disconnected is released. The abort check also required the swarm to be empty, so on any torrent with peers such a worker held one of the @max_parallel_pieces slots forever — 7 of 12 slots live, capping a torrent with 26 unchoked peers at 5 pieces in flight.
• A piece failing its SHA-1 check now blames the peer that supplied it. The worker previously just re-requested every block and could pick the same peer again; one torrent sat at 99.84% for hours re-downloading one index. Blocks now remember their source, a peer stops being asked for an index it has corrupted, and is dropped after @max_hash_failures distinct ruined pieces.
• Writes to a peer that has stopped reading are bounded. A TCP socket defaults to send_timeout: :infinity, so a sender blocked inside :prim_inet.send/4 never returned and its mailbox only grew — one held 20863 messages. Accepted and dialled sockets now take a 30 s send timeout and close on it.
• The upload delivery task no longer crashes when a peer cannot take a block. Only :noproc was tolerated, so a peer shutting down mid-call produced one crash report per in-flight block — 333 in fifteen minutes. BEP 3 permits simply not answering a request, so this is now a cancellation with one debug line; any other exit still crashes.
• One pending pump wake per torrent. Every trigger — the 2 s reconcile tick, each peer handoff, every requests_are_dealt closure — started its own self-rescheduling {:next_piece} chain, and they accumulated: 99 → ~2600 discovery dial cycles per minute over twelve minutes with no change in swarm size, until the tracker answered 403.
• A peer disconnect logs why it ended. Peer.Endpoints monitors a supervisor with auto_shutdown: :any_significant, which exits with a bare :shutdown whatever the child's reason was, so every disconnect read reason=:shutdown — useless for the one question worth asking, whether the peer left or we dropped it. A protocol error now also logs the rejected wire message, and the piece-bounds check logs the block alongside the torrent's geometry.
• The background DHT metadata-lookup dedup table has a permanent owner. It was created by whichever Magnet.Fetcher ran first and died with that torrent, so every later background task crashed with ArgumentError on insert; a supervised GenServer now owns it.

Performance

• Dial batches overlap instead of serialising on their slowest endpoint. One endpoint can hold a slot for the whole connect + handshake budget (measured successes at 16 s, 42 s and 42 s, worst case near 55 s), and until it resolved the manager would start nothing new for that torrent. That hurt worst where it mattered most: a starved torrent with an all-IPv4 queue is capped to a four-endpoint probe batch, so it made four attempts per minute against a ~1% CGNAT success rate. Batches are now bounded by endpoints in flight (40) and concurrent batches (3), with in-flight endpoints excluded from selection so two batches cannot dial the same peer.

0.6.5 - 2026-08-18

Added

• A built-in RC4 stream cipher (Peer.MSE.RC4), selected automatically when the linked libcrypto does not expose RC4. OpenSSL 3 moved RC4 into the optional legacy provider and the Windows ERTS ships no legacy module, so :crypto omits :rc4 there — and because the whole MSE handshake is RC4-encrypted, including the exchange that selects a plaintext stream, such a node could not speak MSE at all and every peer dial failed. config :elixir_torrent, :mse_rc4 accepts :auto (default), :crypto, :pure or :disabled.

Fixed

• Tracker announces now choose their source address by asking the kernel which local address routes to the destination, instead of taking one from Acceptor.all_global_ips/0. Windows enforces the strong host model and refuses a bind whose address does not belong to the routing interface, so with a VPN, a second NIC or tethering every announce failed with :eaddrnotavail. BEP 7 is unchanged where a routable global address exists; an announce refused for the bind is retried once unbound.
• Magnet.Fetcher.finalize_piece_attempt/1 no longer raises FunctionClauseError on a non-retryable piece attempt, which previously took down the entire magnet fetch instead of that one attempt. :econnreset and :econnaborted — how a departing peer is reported on Windows — are now treated as retryable.
• The DHT IPv4 socket logged bind=<primary ip> while actually being bound to 0.0.0.0.

Changed

• The test suite now runs on Windows. It previously failed before the first test on a /dev/null path, and then on localhost resolution: the suite forbids DNS on the wire, Unix answers localhost from /etc/hosts, and Windows ships that line commented out. Three platform assumptions in tests and three TOCTOU races were fixed alongside.

0.6.4 - 2026-08-12

Added

• Test coverage for paths that previously only ran against a live network or a hostile peer: address classification and the NAT-PMP codec, the Peer.Controller.State wire state machine including BEP 16 super-seed bookkeeping, the BEP 3 choke algorithm and swarm teardown, DHT (BEP 5) degraded-mode callbacks, ut_pex (BEP 11/40) ordering, tracker announce edge cases, BEP 9 metadata fetch, STUN parsing, dial backoff sweeps, and BEP 52 v2 padding-gap reads/writes.

Changed

• Acceptor.compute_all_global_ips/1 is now a public arity-1 function taking the :inet.getifaddrs() result, so the rules deciding which addresses may be advertised to trackers, DHT and PEX can be evaluated against a supplied interface list rather than the host's own.
• Magnet.Fetcher's BEP 5 retry windows (dht_retry_delays_ms/0, dht_deep_retry_delay_ms/0) are read through the existing fetcher config override instead of compile-time attributes, so the propagation waits are adjustable without changing the retry shape. Defaults unchanged.

0.6.3 - 2026-08-11

Fixed

• Release pipeline: cosign sign-blob now writes a --bundle file instead of the deprecated --output-signature/--output-certificate flags, which current cosign silently ignores in favor of its new Sigstore bundle format (0.6.2's release signing failed with create bundle file: open : no such file or directory as a result). The bundle is named *.tar.sigstore.json so OpenSSF Scorecard's Signed-Releases check recognizes it. No runtime/library changes.

0.6.2 - 2026-08-11

Fixed

• Release pipeline: publishing to Hex.pm is now idempotent (skips cleanly if the tag's version is already on Hex.pm instead of failing), and cosign's release-signing step retries on transient OIDC-token fetch failures instead of falling through to an interactive device-code flow that stalls CI. No runtime/library changes.

0.6.1 - 2026-08-11

Changed

• Runtime pin moved to Elixir 1.20.3 + OTP 29.0.5 (ERTS 17.0.5)
• Hackney 4.7.2, H2 0.11.0, QUIC 1.8.0, WebTransport 0.4.4 (HTTP stack behind HTTPoison, used by HTTP trackers, scrape, and BEP 19 web seeds)

0.6.0 - 2026-08-04

Added

• BEP 14 (LSD): Local Service Discovery via UDP multicast (BT-SEARCH)
• BEP 19 (WebSeed): HTTP Range seeding from url-list via Torrent.WebSeed
• BEP 48: periodic tracker scrape; skip confirmed dead-swarm announce URLs
• BEP 52 (phases 1–2/6): detect v1/hybrid/v2, parse peers' v2 handshake capability; accept hybrid torrents/magnets; reject pure-v2 cleanly
• Lazy piece storage: on-demand piece read/write/verify workers with idle terminate
• Peer.ConnectionManager: outbound dial orchestration with per-family throttle
• Mid-download session checkpoint (bitfield + counters every 30s)
• Magnet x.pe peers kept as live dial candidates after metadata fetch
• Developer quality gate: warnings-as-errors compile, Dialyzer, and all enabled Credo checks at every priority via mix quality

Changed

• Magnet.Connection sources its BEP 3 choke/unchoke/interested wire ids from Peer.Const instead of a local copy
• CI publish workflow renamed to build-and-publish, gated to run mix hex.publish on semver tag pushes

Fixed

• NAT-PMP and UPnP passive UDP receive handling now decodes the datagram payload instead of the source-address tuple
• Global 2 MiB recv-buffer ceiling now bounds every wire frame's declared length, not only the six previously-capped ids
• Per-connection stall watchdog disconnects peers that trickle a declared frame length in forever instead of completing it
• Declared bitfield/piece frame lengths capped ahead of buffering, closing a memory-amplification gap alongside the existing LTEP/BEP 52 caps
• Tracker started is now resent on the first announce of every session (e.g. after a cold restart), not only once per info hash ever

0.5.1 - 2026-07-22

Changed

• README: single-row shields.io badges at the top for release, Hex, HexDocs, changelog, source, Web UI, and macOS downloads

0.5.0 - 2026-07-22

Added

• BEP 9/10 (magnet + ut_metadata): magnet URI parsing, download_magnet/1, LTEP extension protocol, metadata fetch/serve, magnet bootstrap and fetcher supervisors
• BEP 11 (ut_pex): peer exchange encode/decode, ingest, and broadcast over LTEP
• BEP 32 (IPv6 DHT): separate IPv4/IPv6 routing tables, compact node/peer codecs, dual-stack KRPC and lookup
• BEP 42: secure DHT node ID generation from the local IPv4 address
• BEP 55 (ut_holepunch): rendezvous/connect/forward hole-punch messages over LTEP; Peer.Holepunch.Store for punch state
• DHT (BEP 5): routing-table persistence across restarts, dual-stack socket wiring, runtime node-id path fix
• NAT traversal: NAT-PMP and UPnP IGD port-mapping clients, STUN mapping-behaviour detection, NAT.PortMapper orchestrator
• MSE/PE: Message Stream Encryption handshake and RC4 transport layer over Peer.Transport
• uTP (BEP 29): zombie-connection hardening and BEP 29 off-spec bug fixes
• Peer discovery/dial: Peer.Endpoints, sticky dial backoff with churn and hard-fail escalation, Peer.DialStats per address-family outcomes
• Acceptor: global IPv4/IPv6 address helpers, IpCache periodic getifaddrs snapshot via :persistent_term, dual-stack listen logging; LTEP handshakes advertise listen port and global addresses
• README: BEP 9, 10, 11, 32, 42, and 55 rows in Supported BEPs table; download_magnet/1 in public API table

Changed

• Peer I/O: MSE/PE encryption integrated into the peer transport and sender receive path
• Peer dial: immediate-drop churn backoff, endpoint PID lookup via Peer.Endpoints.get_pid/3

Fixed

• DHT node ID persistence file path resolved at runtime instead of compile time

Notes

• Started at runtime (via ElixirTorrentApplication): TCP acceptor (with IpCache), PeerDiscovery, magnet fetcher/bootstrap, and Peer.Holepunch.Store
• Implemented and compiled, not started in supervision: mainline DHT server, uTP dispatcher, NAT.PortMapper, Peer.Endpoints, Peer.DialBackoff, and Peer.DialStats — wiring deferred to a future release
• Default peer acquisition remains TCP + tracker (plus magnet metadata bootstrap); DHT announce, uTP fallback dials, NAT mapping, and full hole-punch initiation require the dormant services above

0.4.0 - 2026-07-08

Added

• BEP 29 (uTP): Peer.Transport over TCP and uTP; uTP packet stack with LEDBAT; connection lifecycle and dispatcher; dial backoff and endpoint registry; outbound TCP-first dial with uTP fallback; inbound uTP handshake entry
• BEP 5 (DHT): Mainline DHT KRPC node (ping, find_node, get_peers, announce_peer); k-bucket routing table with bootstrap routers; iterative lookup and announce token workflow; DHT and uTP share one UDP socket via DHT.send_udp/3
• README: BEP 5 (Mainline DHT) row in Supported BEPs table

Changed

• Peer I/O: Peer.Sender is the sole socket owner over Peer.Transport; Peer.Receiver removed; post-handshake socket handoff uses Sender.activate/1

Fixed

• Torrent progress and downloaded/left counters reconciled with the on-disk bitfield
• Piece pipeline: idempotent piece statistics init, stale :processing cleanup, exclude-aware picker
• In-flight piece download recovery when subpiece requests stall (waiting: [] no longer finishes early)
• Incoming piece block bounds validation; Peer.log_id/1 for safe timeout logging
• Download scheduler: parallel piece picking with availability checks, resume handoff before controller scheduling, per-piece interested peer assignment

Notes

• uTP (BEP 29) and DHT (BEP 5) are implemented and compiled in, but runtime activation (supervision wiring) is deferred to a future release; the default peer-acquisition/download path remains TCP + tracker-based.

0.3.0 - 2026-06-28

Download location

• ElixirTorrent.download/2 accepts an optional :download_dir keyword — base directory for downloaded files (defaults to File.cwd!/0)
• Session snapshots remain under {File.cwd!()}/.elixir_torrent/state/ regardless of :download_dir
• remove/2 with delete_data: true removes files from the torrent's download directory

File layout

• Multi-file torrents whose files share no common top-level folder are written under a directory named after the torrent (sanitized info.name)
• Multi-file torrents that already use a shared root folder (e.g. dir/a.bin, dir/b.bin) keep their original paths
• Single-file torrents are written directly into the download root

Docs

• README About section with project background

0.2.0 - 2026-06-11

Session persistence

• Saved session state under .elixir_torrent/state/{info_hash}.term (relative to File.cwd!/0)
• On download/1, an existing session is loaded and the bitfield is verified against disk before resuming
• remove/2 deletes the session file; delete_data: true also removes downloaded files

Graceful shutdown API

• stop_and_serialize/1 — stop piece downloads, disconnect peers (BEP 3), send tracker event=stopped, persist session, then stop the torrent process
• stop_all_and_serialize/0 — same for every active torrent
• list/0 — returns info hashes for all running torrent processes

Peer disconnect

• Peers receive BEP 3 cancel / not interested / choke before TCP connections close
• Used during shutdown so peers are notified cleanly

0.1.2 - 2026-06-09

• ElixirTorrent.list_files/1 — file list with per-file download progress
• ElixirTorrent.remove/2 — stop a torrent; optional delete_data: true removes files from disk
• Requires Elixir ~> 1.20

0.1.1 - 2026-02-22

• Published HexDocs for the public API (ElixirTorrent, Torrents)
• ElixirTorrent.stats/2 documented as the preferred way to read runtime stats

0.1.0 - 2026-02-22

First public release — BitTorrent client engine publishable as a Hex dependency.

Public API

• ElixirTorrent.download/1 — start a download from a .torrent file on disk
• ElixirTorrent.stats/2 — poll name, speeds, and progress for a running torrent
• Escript entrypoint for CLI usage

Protocol & networking

• Peer wire protocol (BEP 3) with choking, rarest-first piece selection, and endgame mode
• Fast Extension (BEP 6) — allowed_fast, reject on choked requests
• IPv6 tracker peers (peers6) and dual-stack listen sockets
• Multi-homed HTTP announce (BEP 7) over IPv4 and IPv6
• HTTP and UDP trackers (BEP 15), compact peer lists (BEP 23)

Reliability

• Improved choke recovery, piece availability tracking, and tracker announce handling