# `Torrents`
[🔗](https://github.com/daniboybye/ElixirTorrent/blob/0.8.0/lib/elixir_torrent/torrents.ex#L1)

Runtime supervisor and operations layer behind `ElixirTorrent`.

Most callers should use `ElixirTorrent` directly. This module is published in
HexDocs for API completeness — it owns the dynamic supervisor that starts torrent
processes and implements `remove/2`, `stop_and_serialize/1`, and related lifecycle
helpers.

# `child_spec`

```elixir
@spec child_spec(term()) :: Supervisor.child_spec()
```

# `download`

```elixir
@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.

# `download_magnet`

```elixir
@spec download_magnet(String.t(), keyword()) ::
  DynamicSupervisor.on_start_child() | {:error, term()}
```

Starts a download from a magnet URI.

Fetches metadata over BEP 9 (`ut_metadata`) from peers discovered via magnet
`tr=` tracker URLs (BEP 3/7/15/23), writes a `.torrent` file, then starts a
normal torrent session.

Trackerless magnets (no `tr=` and no DHT) return `{:error, :missing_trackers}`.

# `list`

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

Returns info hashes for all active torrent processes.

# `remove`

```elixir
@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.

# `stats`

```elixir
@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]`.

# `stats`

```elixir
@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])

# `stop_all_and_serialize`

```elixir
@spec stop_all_and_serialize() :: :ok
```

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

# `stop_and_serialize`

```elixir
@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).

# `supervisor_pid`

```elixir
@spec supervisor_pid(Torrent.hash()) :: {:ok, pid()} | {:error, :not_found}
```

Returns the torrent supervisor pid for `hash`, if it is running.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
