ElixirTorrent

BitTorrent client engine for Elixir/OTP — embed downloads in your own app with a small, stable public API.

About

This is a fully functional BitTorrent client that actually downloads torrents — not a stub or protocol sketch. It started as a course project for Functional Programming with Elixir at Sofia University. After the course ended, development continued in spare time until it was ready to publish on Hex.

ElixirTorrent Web (desktop app)

Need a full client, not just the library? ElixirTorrent Web is the official Phoenix LiveView UI for this engine, shipped as a native macOS desktop app.

The sections below cover the engine API for Elixir developers embedding BitTorrent in their own apps.

Installation

Add elixir_torrent to your list of dependencies in mix.exs:

def deps do
  [
    {:elixir_torrent, "~> 0.6.0"}
  ]
end

Then fetch and start the application:

mix deps.get

# In your Application.start/2 or before first use:
Application.ensure_all_started(:elixir_torrent)

Requires Elixir 1.20+.

Development quality checks

Run the project quality gate with:

mix quality

It compiles with warnings as errors, runs Dialyzer, and runs mix credo --strict --all. The same strict Credo gate runs in CI, covering every enabled check at every priority.

Quick start

From a .torrent file

Application.ensure_all_started(:elixir_torrent)

{:ok, pid} = ElixirTorrent.download("/path/to/file.torrent")
[hash] = ElixirTorrent.list()

# Optional: write files under a specific directory (session state still uses File.cwd!/0)
{:ok, pid} = ElixirTorrent.download("/path/to/file.torrent", download_dir: "/Downloads")

{:ok, stats} =
  ElixirTorrent.stats(pid, [:name, :speed, :downloaded, :bytes_size])

# stats.name, stats.speed.download, stats.speed.upload, …

files = ElixirTorrent.list_files(hash)
# Each entry has :path, :progress, :complete?, etc.

Poll stats/2 while the download runs. When you are done monitoring, call stop_and_serialize/1 (see below) or remove/2 to drop the torrent from the active session.

From a magnet link

{:ok, pid} =
  ElixirTorrent.download_magnet(
    "magnet:?xt=urn:btih:…&tr=udp%3A%2F%2Ftracker.example.com%3A1337%2Fannounce"
  )

The magnet flow:

1. Parse the URI (xt=urn:btih:, tr=, optional dn=).
2. Announce to tr= tracker URLs when present, and/or discover peers via BEP 5 DHT when enabled.
3. Fetch the info dictionary from a peer via BEP 9 (ut_metadata), negotiated with BEP 10 (LTEP).
4. Verify SHA1(bencode(info)) matches the magnet hash.
5. Write a temporary .torrent file and start a normal session via download/1.

Requirements: at least one tr= tracker URL or DHT enabled (default on desktop). Trackerless magnets with DHT disabled return {:error, :missing_trackers}.

Common errors: :no_peers, :timeout, :metadata_unavailable, :info_hash_mismatch.

Session persistence

The engine can save and restore download progress across process restarts.

On disk:{File.cwd!()}/.elixir_torrent/state/{hex_info_hash}.term

Each file stores the bitfield, byte counters, and peer status. When you call download/1 with a .torrent that was previously saved, the engine loads the session, verifies pieces against disk, and resumes from the saved bitfield.

Persist before exit:

ElixirTorrent.stop_and_serialize(hash)
# or, for every active torrent:
ElixirTorrent.stop_all_and_serialize()

Remove without keeping progress:

ElixirTorrent.remove(hash)
# also delete downloaded files:
ElixirTorrent.remove(hash, delete_data: true)

remove/2 deletes the session file. stop_and_serialize/1 writes a fresh snapshot and keeps the torrent removable on the next boot via the same .torrent path.

Graceful shutdown

stop_and_serialize/1 runs, in order:

1. Stop active piece downloads
2. Disconnect all peers (BEP 3 cancel / not interested / choke, then TCP close)
3. Send tracker announce with event=stopped
4. Write session state to .elixir_torrent/state/
5. Stop the torrent OTP process

Use this when your application shuts down and you want downloads to resume later. stop_all_and_serialize/0 applies the same steps to every running torrent.

Public API

Full reference: hexdocs.pm/elixir_torrent/ElixirTorrent.html

Protocol support (BEPs)

Status meanings:

Magnet URIs are a de-facto convention (BitTorrent wiki), not a numbered BEP. We parse xt=urn:btih: (hex and base32), multiple tr=, and optional dn=.

De-facto tracker behaviour: before metadata is known, magnet announces use left=16384 (typical client convention, not a BEP requirement) so trackers return peers that support ut_metadata.

MSE/PE (Message Stream Encryption / Protocol Encryption) — the Vuze de-facto spec, not a numbered BEP. Full, bidirectional. 768-bit MODP Diffie–Hellman key exchange, RC4 stream cipher, SHA-1 key derivation (all via OTP :crypto). Inbound connections auto-detect plaintext vs encrypted; outbound prefers the encrypted handshake and falls back to plaintext, honouring the peer's crypto_select (RC4 or plaintext) for the post-handshake stream. Interop-verified against Transmission, qBittorrent, and libtorrent. Provides ISP-throttling resistance and connectivity with encryption-only peers.

Recently completed (2026-07)

• PEX parity hardening (BEP 10/11/27/40) — private torrents no longer negotiate or process PEX; public peers exchange bounded per-connection snapshots with real flags, source-owned drops, recent-peer supplementation, abuse filtering, canonical priority, and magnet-fetch ingestion. Status remains Partial pending live libtorrent/qBittorrent v4+v6 and private zero-traffic verification.
• Superseeding (BEP 16) — a newly completed sole seed hides its full bitfield and assigns one rare piece per peer until the swarm produces another complete seed, reducing redundant initial uploads.
• Web seeds (BEP 19) — HTTP/URL seeding as a third data source alongside peers and DHT, sharing the same piece-verify and write path as a normal download.
• Local Service Discovery (BEP 14) — LAN peer discovery via UDP multicast, no tracker/DHT round-trip needed.
• BitTorrent v2 download + hybrid discovery (BEP 52, phases 1–5/6) — pure-v2 .torrent files download and resume through the truncated SHA-256 swarm and per-file Merkle path; hybrid torrents serve fixture-verified hash proofs and query/announce on DHT under both identities without splitting their v1-keyed local swarm.
• DHT secure node ID (BEP 42) — node IDs are bound to their IPv4/IPv6 address, and non-compliant remote contacts cannot become trusted routing or announce targets (Sybil/routing-poisoning mitigation).
• BEP 48 scrape-driven tracker health — every torrent scrapes its trackers periodically for {seeders, leechers} and skips confirmed dead-swarm URLs at announce time, so a tier of dead trackers falls through to the next tier instead of firing a wasted parallel announce every 30 s while under swarm target.
• Magnet x.pe hand-off — magnet-embedded fallback peers stay live candidates for the whole session instead of being dropped once metadata fetch completes.
• Mid-download session checkpoint — bitfield + counters persisted every 30 s, so a crash resumes with a hash-check of only what's unconfirmed, not a full re-scan.
• MSE/PE encryption (full bidirectional — see the note above).
• Measured per-family dial throttle — de-prioritises the address family with proven-low outbound success (data-driven; under CGNAT+IPv6 that is IPv4 at ~1.3% vs IPv6 ~25%), without starving single-family swarms.
• Lazy piece storage — piece read/write/verify processes start on demand and idle-terminate instead of one persistent process per piece, cutting process count and memory to a fraction (compact-state model like libtorrent/qBittorrent).
• DHT routing-table persistence across restarts for fast rejoin.

Not yet implemented (roadmap)

Work tracked for future releases:

Full internal backlog and design rationale live in .claude/PLAN.md and .claude/ARCHITECTURE.md (kept in sync with this table).

CLI (escript)

The package builds an escript for ad-hoc testing:

mix escript.build
./elixir_torrent
# then type: download /path/to/file.torrent

The escript does not expose download_magnet in the interactive loop yet — use the API from your OTP application for magnet links.

For production use, call the API from your OTP application instead.