# 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 |