79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
# torrent-tracker
|
|
|
|
A C tracker-side BitTorrent protocol library, shaped to match the neighboring
|
|
`torrent-peer` project but focused on announce/scrape handling instead of peer
|
|
wire transfer.
|
|
|
|
Current scope:
|
|
|
|
- HTTP(S) announce query parsing for BEP-3 tracker parameters.
|
|
- HTTP scrape query parsing and bencoded scrape responses.
|
|
- Compact HTTP tracker responses for IPv4 `peers` and IPv6 `peers6`.
|
|
- UDP tracker request parsing and response writing for BEP-15.
|
|
- UDP announce URLData extension parsing for BEP-41.
|
|
- Client-side HTTP query builders and bencoded response parsers for announce
|
|
and scrape.
|
|
- Client-side UDP connect/announce/scrape request builders and response parsers.
|
|
- BEP-5 DHT/KRPC message builders and parser for `ping`, `find_node`,
|
|
`get_peers`, `announce_peer`, responses, and errors.
|
|
- BEP-32 IPv6 DHT compact `nodes6` parsing/writing and `want` flags.
|
|
- In-memory swarm storage for announces, peer expiry, seed/leecher accounting,
|
|
completed counts, scrape data, no-self filtering, and randomized peer
|
|
selection with `numwant` clamping.
|
|
- A protocol-neutral announce/scrape model that a tracker storage engine can
|
|
use regardless of wire protocol.
|
|
|
|
This is now the protocol core plus an embeddable in-memory tracker store, not a
|
|
complete daemon yet. The next layer should add connection listeners, request
|
|
routing, rate limiting, and auth hooks around this ABI.
|
|
|
|
## Build
|
|
|
|
```sh
|
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
|
|
cmake --build build
|
|
```
|
|
|
|
Options:
|
|
|
|
- `-DTRACKER_NATIVE=OFF` for portable builds without `-march=native`.
|
|
- `-DTRACKER_ASAN=ON` for AddressSanitizer/UBSan.
|
|
- `-DTRACKER_TESTS=OFF` to skip the test executable.
|
|
|
|
## Test
|
|
|
|
```sh
|
|
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
|
|
cmake --build build
|
|
ctest --test-dir build --output-on-failure
|
|
```
|
|
|
|
## Real Tracker Probe
|
|
|
|
Point the harness at a `.torrent` file to announce to its HTTP(S)/UDP trackers
|
|
and print returned swarm stats and peers:
|
|
|
|
```sh
|
|
python harness/tracker_probe.py file.torrent --max-trackers 8
|
|
```
|
|
|
|
Useful options:
|
|
|
|
- `--tracker URL` probes an explicit tracker instead of the torrent's tracker
|
|
list. Repeat it to test several URLs.
|
|
- `--scrape` also tries HTTP scrape URLs derived from announce URLs.
|
|
- `--timeout SECONDS`, `--numwant N`, and `--port PORT` control announce
|
|
behavior.
|
|
|
|
## Layout
|
|
|
|
| Path | Role |
|
|
|------|------|
|
|
| `include/tracker.h` | public C ABI |
|
|
| `src/tracker_http.c` | HTTP(S) tracker client/server helpers and bencode handling |
|
|
| `src/tracker_udp.c` | UDP tracker client/server packet parser/writers |
|
|
| `src/tracker_store.c` | in-memory swarm table and response selection |
|
|
| `src/dht.c` | DHT/KRPC message parser and writers |
|
|
| `harness/tracker_probe.py` | real-world HTTP/UDP tracker probe for `.torrent` files |
|
|
| `tests/test_tracker.c` | focused protocol tests |
|
|
| `PLAN.md` | protocol/extension roadmap |
|