Initial commit: tracker and DHT protocol library

README.md

@@ -0,0 +1,79 @@
+# 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 |