Cieric/Naut-Tracker
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Naut-Tracker/PLAN.md

4.4 KiB
Raw Permalink Blame History

torrent-tracker Protocol Plan

Goal: build a tracker-side library that can serve the tracker protocols and extensions seen in real torrents, with protocol parsing separated from swarm storage and serving policy.

Implemented Foundation

  • BEP-3 HTTP announce parameters: info_hash, peer_id, port, uploaded, downloaded, left, compact, no_peer_id, event, numwant, key, ip, and trackerid.
  • BEP-23 compact peer responses: IPv4 peers and BEP-7-style IPv6 peers6.
  • BEP-48 HTTP scrape parsing and bencoded scrape responses.
  • BEP-15 UDP connect, announce, scrape, and error packet handling.
  • BEP-41 UDP announce extension parser, including concatenated URLData chunks.
  • Client-side HTTP announce/scrape query builders and bencoded tracker response parsers.
  • Client-side UDP connect/announce/scrape packet builders and response parsers with transaction-id validation.
  • BEP-5 DHT/KRPC message builders and parser for ping, find_node, get_peers, announce_peer, response, and error packets.
  • BEP-32 IPv6 DHT compact node support through nodes6 plus want flags.
  • In-memory swarm table keyed by 20-byte tracker infohash.
  • Announce handling for insert/update/stop, source-address-derived endpoints, seed/leecher counts, completed-download scrape counts, no-self filtering, randomized peer selection, numwant clamping, and stale peer pruning.

Tracker-Side Roadmap

Client-Side Roadmap

  1. DHT node/session manager: Add a UDP event loop, node ID generation, transaction table, timeout/retry logic, bootstrap nodes, and request dispatch for KRPC packets.

  2. DHT routing table: Implement BEP-5 k-buckets, XOR distance sorting, good/questionable/bad node state, bucket refresh, and persistence of known nodes between runs.

  3. DHT peer discovery: Implement iterative get_peers lookup, token storage, announce_peer, and integration with the tracker client result format so callers can consume central tracker and DHT peers through one path.

  4. Tracker session manager: Add a small client state machine that stores UDP connection IDs until expiry, schedules announces at interval, handles started/completed/stopped events, retries UDP with exponential backoff, and rotates across announce-list tiers.

  5. Transport adapters: Wrap the protocol helpers with optional HTTP(S) and UDP socket code. Keep TLS outside the core ABI, but provide a CLI/harness path that exercises real network announces through the C helpers.

  6. Magnet and v2 metadata: Keep accepting 20-byte tracker hashes: v1 SHA-1 infohash and BEP-52 truncated SHA-256 for v2/hybrid torrents. Add metadata utilities or bindings so callers can compute the right tracker hash from metainfo without duplicating logic.

  7. Client interop tests: Compare C helper output against libtorrent/tracker_probe behavior for HTTP, UDP, compact IPv4, peers6, scrape, failure responses, BEP-41 URLData, and DHT KRPC packets observed from real nodes.

Tracker-Side Roadmap

  1. Network daemons: Add HTTP/HTTPS and UDP listeners around the protocol core. HTTPS should live behind a TLS terminator initially; the library API should not require a TLS dependency.

  2. IPv6 and multi-homed behavior: The store accepts IPv4 and IPv6 endpoints and prefers source addresses over user-supplied ip. Add daemon-level tests for announcing the same peer over multiple listen interfaces and returning family-appropriate UDP responses.

  3. Tracker policy: Add hooks for private torrents, whitelist/auth tokens in HTTP query strings and BEP-41 UDP URLData, per-swarm limits, rate limits, and abuse controls.

  4. Response selection: Add stronger selection policy controls: per-family caps, seed/leecher mix, deterministic test hooks for sampling, and configurable tracker id generation/validation.

  5. Persistence and admin: Add optional durable storage or snapshot/restore for long-running trackers, metrics export, registered-torrent management, and scrape-cache policy.

  6. Compatibility matrix: Build interop tests against libtorrent, Transmission, qBittorrent, aria2, rtorrent, and opentracker for HTTP, UDP, compact, IPv6, scrape, and private torrent behavior.

  7. Optional adjacent discovery: DHT, PEX, and local peer discovery are peer-discovery mechanisms rather than central tracker protocols. Keep them as separate modules if this project grows into a full discovery stack.