retracker

Lightweight BitTorrent tracker (HTTP + UDP, BEP 15) in a single Go binary. Everything is in-memory; no database or external web stack required.

This is built with extensive help from different AI agents, as an experiment.

Features (concise)

• HTTP and UDP announce/scrape with shared core logic (BEP 15 compliant)
• Forwarding to external trackers (HTTP/HTTPS/UDP) with peer aggregation
• Adaptive worker pool with rate limiting and throttling for forwarders
• Prometheus metrics endpoint
• IPv4/IPv6 support and secure connection ID handling for UDP

Quick start

go install github.com/fl0v/retracker@latest
retracker -l :6969 -d

Add http://<your ip>:6969/announce to your torrent.

Full installation and deployment options are in INSTALL.md.

Usage highlights

• Enable UDP alongside HTTP:

  retracker -l :6969 -u :6969 -d

• Load forwarders and aggregate peers:

  retracker -l :6969 -d -f forwarders.yml

• Prometheus metrics: GET /metrics (when enabled in config)

HTTP API

• GET /announce - BitTorrent announce endpoint.
• GET /scrape - BitTorrent scrape endpoint.
• GET /stats - text stats (GET /stats?format=json for JSON).
• POST /add-forwarder - add forwarder URLs at runtime (in-memory only, lost on restart).
  • Request body JSON (multiple only): {"urls":["https://t1.example.com/announce","udp://t2.example.com:6969/announce"]}
• GET /add-forwarder - add forwarder URLs from query string.
  • Query format: ?urls=url1,url2, (comma-separated, trailing comma allowed)
  • Responses:
    • 200 when all are added, or when partially added (status: "partial")
    • 400 when all requested URLs fail validation
    • 409 when all requested URLs already exist
  • Response body includes per-URL result list and counters: added, failed, results[]

Example:

curl -X POST http://127.0.0.1:6969/add-forwarder \
  -H 'Content-Type: application/json' \
  -d '{"urls":["udp://tracker.example.com:6969/announce","https://tracker2.example.com/announce"]}'

curl "http://127.0.0.1:6969/add-forwarder?urls=udp://tracker.example.com:6969/announce,https://tracker2.example.com/announce,"

Docker

• Build: cd docker && docker build -t retracker .
• Run: docker run -d -p 6969:6969 retracker
• Compose: cd docker && docker-compose up -d

See INSTALL.md for configuration env vars and examples.

Documentation

• INSTALL.md - Installation and deployment options
• docs/ANNOUNCE_LOGIC.md - Announce handling logic and diagram
• docs/QUEUE_AND_SCHEDULER.md - Queue and scheduler implementation
• docs/BITTORRENT.md - BitTorrent protocol reference

Development

• Format: make fmt (gofumpt)
• Lint: make lint (golangci-lint)
• All checks: make check

License

MIT License - see LICENSE.