ElixirTorrent (elixir_torrent v0.2.0)

Copy Markdown View Source

Public API for the ElixirTorrent BitTorrent engine.

Start the OTP application before calling any function:

Application.ensure_all_started(:elixir_torrent)

Then add torrents with download/1, poll progress with stats/2, and shut down cleanly with stop_and_serialize/1 when you need session state preserved on disk.

Session persistence

Session snapshots are written to .elixir_torrent/state/{hex_info_hash}.term under File.cwd!/0. Calling download/1 for a torrent with an existing session loads the saved bitfield and verifies pieces on disk before resuming.

Use stop_and_serialize/1 (or stop_all_and_serialize/0) before your app exits. Use remove/2 when you want to drop a torrent from the active session; pass delete_data: true to also delete downloaded files.

Public functions

See the README for a full quick-start guide.

Summary

Types

file_entry()

Per-file progress entry returned by list_files/1.

info_hash()

20-byte torrent info hash.

Functions

download(path)

Starts downloading a .torrent file from the given local path.

get(pid, args \\ [])

Low-level getter that reads fields from the internal torrent model.

list()

Returns info hashes for all active torrent processes.

list_files(hash)

Lists files in a torrent with per-file download progress.

main(_)

Starts the CLI loop used by the escript entrypoint.

remove(hash, opts \\ [])

Stops a torrent and removes it from the active session.

stats(pid, fields \\ [:name, :speed, :downloaded, :bytes_size])

Returns selected runtime stats for a running torrent process.

stop_all_and_serialize()

Gracefully stops every active torrent and persists session state for each one.

stop_and_serialize(hash)

Gracefully stops a torrent and persists its session state to disk.

version()

Returns the peer ID prefix advertised to other peers (BEP 20).

Types

file_entry()

@type file_entry() :: %{
  index: non_neg_integer(),
  path: String.t(),
  name: String.t(),
  length: non_neg_integer(),
  downloaded: non_neg_integer(),
  progress: float(),
  complete?: boolean()
}

Per-file progress entry returned by list_files/1.

Keys: :index, :path, :name, :length, :downloaded, :progress, :complete?.

info_hash()

@type info_hash() :: binary()

20-byte torrent info hash.

Functions

download(path)

Starts downloading a .torrent file from the given local path.

If a session file already exists for this torrent's info hash, progress is restored after verifying pieces on disk.

Returns {:ok, pid} on success or {:error, reason} on failure.

Example

{:ok, pid} = ElixirTorrent.download("/tmp/file.torrent")

get(pid, args \\ [])

@spec get(pid(), atom() | [atom()]) :: any()

Low-level getter that reads fields from the internal torrent model.

Prefer stats/2 when you need runtime statistics as a map.

list()

@spec list() :: [info_hash()]

Returns info hashes for all active torrent processes.

list_files(hash)

@spec list_files(info_hash()) :: [file_entry()]

Lists files in a torrent with per-file download progress.

See file_entry/0 for the shape of each returned entry.

main(_)

Starts the CLI loop used by the escript entrypoint.

remove(hash, opts \\ [])

@spec remove(
  info_hash(),
  keyword()
) :: :ok | {:error, term()}

Stops a torrent and removes it from the active session.

Deletes the on-disk session file. Pass delete_data: true to also remove downloaded files from disk.

Example

ElixirTorrent.remove(hash)
ElixirTorrent.remove(hash, delete_data: true)

stats(pid, fields \\ [:name, :speed, :downloaded, :bytes_size])

@spec stats(pid(), [atom()]) :: {:ok, map()} | {:error, :torrent_not_found}

Returns selected runtime stats for a running torrent process.

Default fields: :name, :speed, :downloaded, :bytes_size.

Example

ElixirTorrent.stats(pid, [:name, :speed, :downloaded, :bytes_size])
#=> {:ok, %{name: "ubuntu.iso", speed: %{download: 1200, upload: 80}, ...}}

Returns {:error, :torrent_not_found} if the pid is not a live torrent process.

stop_all_and_serialize()

@spec stop_all_and_serialize() :: :ok

Gracefully stops every active torrent and persists session state for each one.

Same shutdown sequence as stop_and_serialize/1, applied to all running torrents.

stop_and_serialize(hash)

@spec stop_and_serialize(info_hash()) :: :ok | {:error, term()}

Gracefully stops a torrent and persists its session state to disk.

Steps: stop downloads → disconnect peers → tracker event=stopped → write .elixir_torrent/state/{hash}.term → stop the torrent process.

Returns :ok if the torrent is not running (already stopped).

version()

Returns the peer ID prefix advertised to other peers (BEP 20).

The full 20-byte peer ID is this prefix, a hyphen, and random bytes.