spill 0.5.1

Modern torrent client
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

# Web interface and HTTP API

## Enabling it

The web interface is off by default. Set a loopback address in the config and
restart the daemon:

```toml
web_listen = "127.0.0.1:8080"
```

Only loopback addresses (`127.0.0.1`, `::1`) are accepted. To use it from
another machine, tunnel it, for example `ssh -L 8080:127.0.0.1:8080 server`,
then open <http://127.0.0.1:8080> locally.

## The page

- A table of torrents with progress, state, download and upload rates, ratio,
  and the latest error or tracker message.
- Adding a `.torrent` file or a magnet link, with an optional output directory.
- Pause, resume, recheck, reannounce and remove (optionally deleting payload).
- A details view with tracker state (seeders, leechers, messages) and files
  with editable priorities.
- A settings panel for the per-torrent settings.

## Security model

- The server only answers requests whose `Host` is the loopback address and
  port it listens on, which blocks DNS-rebinding attacks.
- Every API request must carry the `X-Spill-Token` header. The page embeds a
  random token generated when the daemon starts.
- Cross-origin requests are rejected.

This protects against other websites in your browser. It is **not**
authentication against other users on the same machine: anyone who can reach
the loopback port can load the page and its token. Don't enable the web
interface on shared machines you don't trust.

## HTTP API

Both endpoints require the `X-Spill-Token` header, and use the same operations
and response format as the [control protocol](cli.md#control-protocol). The
page shows the current token; it changes whenever the daemon restarts.

### `POST /api`

A JSON body with an `op` field, limited to 64 KiB:

```sh
curl -s http://127.0.0.1:8080/api \
  -H "X-Spill-Token: $TOKEN" -H 'Content-Type: application/json' \
  -d '{"op":"set","id":"3f2a","values":{"upload_limit":1048576}}'
```

Operations: `add` (magnets), `get`, `set`, `list`, `status`, `files`, `pause`,
`resume`, `recheck`, `reannounce`, `remove`, `health`, `shutdown`.

The `get` response includes `transfer.peers[].transport`: `"tcp"`, `"utp"`
or `"http"` (web seed), just like the Unix control API. The same diagnostics
include per-peer and owner-total `utp_retransmits`, and `pending_contacts`;
see [Command line](cli.md#commands) for their meaning.

### `POST /api/upload`

Upload a `.torrent` file as the raw request body (at most 16 MiB). The output
directory is an optional, URL-encoded query parameter:

```sh
curl -s "http://127.0.0.1:8080/api/upload?output_dir=%2Fsrv%2Ftorrents" \
  -H "X-Spill-Token: $TOKEN" -H 'Content-Type: application/x-bittorrent' \
  --data-binary @file.torrent
```