@spec download(
  Path.t(),
  keyword()
) :: DynamicSupervisor.on_start_child()

Starts a new torrent download from a local .torrent path.

Options:

• :download_dir — base directory for downloaded files (defaults to File.cwd!/0)

Multi-file torrents with loose top-level files are written under a folder named after the torrent; torrents that already share a root folder keep their original paths.

Returns {:ok, pid} on success.

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

Returns info hashes for all active torrent processes.

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

Stops a running torrent and removes it from the active list.

When :delete_data is true, downloaded files are deleted from disk after the torrent process has been stopped.

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

Returns a default set of runtime stats for a torrent process.

The default fields are: [:name, :speed, :downloaded, :bytes_size].

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

Returns selected runtime fields for a torrent process as a map keyed by field.

Example:

Torrents.stats(pid, [:name, :speed, :downloaded, :bytes_size])

@spec stop_all_and_serialize() :: :ok

Stops every active torrent and persists session state for each one.

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

Gracefully stops a torrent and persists session state.

Order of operations:

1. Stop active piece downloads
2. Disconnect all peers (BEP 3 messages, then TCP close)
3. Tracker announce with event=stopped
4. Write session to .elixir_torrent/state/{hash}.term
5. Stop the torrent OTP process

Returns :ok when the torrent is not found (already stopped).