If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/anacrolix/torrent shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 1w ago
• 5 active contributors
• MPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 95% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live anacrolix/torrent repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/anacrolix/torrent.

What it runs against: a local clone of anacrolix/torrent — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in anacrolix/torrent | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of anacrolix/torrent. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/anacrolix/torrent.git
#   cd torrent
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of anacrolix/torrent and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "anacrolix/torrent(\\.git)?\\b" \\
  && ok "origin remote is anacrolix/torrent" \\
  || miss "origin remote is not anacrolix/torrent (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "client.go" \\
  && ok "client.go" \\
  || miss "missing critical file: client.go"
test -f "torrent.go" \\
  && ok "torrent.go" \\
  || miss "missing critical file: torrent.go"
test -f "peer.go" \\
  && ok "peer.go" \\
  || miss "missing critical file: peer.go"
test -f "piece.go" \\
  && ok "piece.go" \\
  || miss "missing critical file: piece.go"
test -f "bencode/encode.go" \\
  && ok "bencode/encode.go" \\
  || miss "missing critical file: bencode/encode.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/anacrolix/torrent"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A production-grade BitTorrent client library written in Go that enables streaming, seeking, and direct playback of torrent content over the network. It implements full BEP (BitTorrent Enhancement Proposal) support including DHT, PEX, uTP, protocol encryption, BitTorrent v2, WebTorrent, and holepunching—with pluggable storage backends (file, mmap, sqlite, bolt, S3-capable) and idiomatic Go io package interfaces for seamless integration. Monorepo structure: root package implements core client (client.go, torrent.go), bencode/ is self-contained encoding library, storage/ abstracts backends, cmd/ contains CLIs (torrent, torrentfs), tracker/ handles announce, dht/ and related packages in dependencies. Package-level organization by concern (peer management, piece verification, protocol extensions) rather than layered architecture.

Go developers building distributed applications, streaming services, or P2P tools who need a reliable BitTorrent client library; maintainers of projects like Gopeed (22.8k★), bitmagnet, Confluence, and Erigon who embed this for torrent protocol support; infrastructure engineers needing custom storage backends (e.g., S3, databases).

Highly mature and production-ready: in continuous production use since late 2014 by downstream services, comprehensive test coverage (bencode, BEP implementations, storage backends all tested), active CI/CD setup (.circleci, GitHub Actions for Go/lint/Windows), Go 1.24 support. The broad downstream adoption (Gopeed 22.8k★, Erigon blockchain) confirms stability despite ongoing development.

Low to moderate risk: ~50+ direct dependencies (anacrolix modules, pion webrtc, roaring bitmaps, sql drivers) create a large supply chain surface, but most are well-maintained anacrolix or popular packages. Single maintainer (@anacrolix) is a potential bottleneck. The codebase is large (1.1M+ lines Go) with non-trivial concurrency primitives and network handling, requiring careful testing before production use of custom modifications.

Actively maintained: recent dependency updates (go-libutp v1.3.2, anacrolix/sync v0.5.5, possum/go v0.4.1), Go 1.24 support, WebRTC datachannel support via pion, OpenTelemetry tracing integration, and ongoing BEP refinements visible in bep14.go, bep40.go and test additions. CI running on Linux, macOS (implicitly via workflows), and Windows.

git clone https://github.com/anacrolix/torrent.git
cd torrent
go mod download
go build ./cmd/torrent  # builds the CLI tool
go test ./...           # runs the full test suite

Daily commands: No single 'dev server'—library is imported into applications. For CLI tool: go run ./cmd/torrent -- <magnet-or-torrent>. For library usage, see examples in pkg.go.dev documentation. For integration testing: go test ./... (use -v for verbose, -race for concurrency issues).

• client.go — Core Client struct and lifecycle management—every integration begins here as the main entry point for the BitTorrent client.
• torrent.go — Torrent struct representing a single torrent—essential for understanding how individual torrents are managed and how pieces are coordinated.
• peer.go — Peer connection management and protocol handling—critical for understanding data exchange and the network I/O layer.
• piece.go — Piece-level state and chunk management—key for understanding how data is downloaded, verified, and assembled.
• bencode/encode.go — Bencode serialization format used throughout BitTorrent protocol—load-bearing for metainfo parsing and protocol messages.
• storage/interface.go — Storage abstraction layer defining how downloaded data is persisted—critical for swapping storage backends.
• cmd/torrent/main.go — CLI entry point demonstrating typical client usage patterns and command flows.

Add support for a new BEP (BitTorrent Enhancement Proposal)

1. Create a new file named bepXX.go in the repository root with the BEP implementation (bepXX.go)
2. Add corresponding test file bepXX_test.go following patterns in bep40_test.go (bepXX_test.go)
3. If the BEP affects peer protocol messages, integrate into peer.go or create message handlers (peer.go)
4. Add configuration flags to config.go if the feature should be user-configurable (config.go)
5. Update README.md to document the new BEP support (README.md)

Add a new storage backend

1. Implement the storage.ClientImpl interface defined in storage/interface.go (storage/interface.go)
2. Create your backend file (e.g., storage/mybackend.go) with New() constructor (storage/mybackend.go)
3. Write tests in storage/mybackend_test.go covering Capacity, Close, and piece I/O (storage/mybackend_test.go)
4. Expose the backend in a factory function and document usage in storage README (storage/README.md)
5. Add example in CLI if appropriate (e.g., flag to select backend in cmd/torrent/main.go) (cmd/torrent/main.go)

Add a new command-line subcommand

1. Create a new file cmd/torrent/mycommand.go with a Run() function following patterns in download.go (cmd/torrent/mycommand.go)
2. Define argument struct with github.com/alexflint/go-arg tags for flag parsing (cmd/torrent/mycommand.go)
3. Register the subcommand in cmd/torrent/main.go switch statement (cmd/torrent/main.go)
4. Add tests in cmd/torrent/mycommand_test.go if complex logic is involved (cmd/torrent/mycommand_test.go)

Extend Client with a new feature or callback hook

1. Add new fields or callback types to the ClientConfig struct in config.go (config.go)
2. Implement the feature logic in client.go or create a new client-myfeature.go file (client.go)
3. If feature requires Torrent-level hooks, extend torrent.go with callback fields (torrent.go)
4. Add example usage in example_test.go or create client-myfeature_test.go (example_test.go)

• Go concurrency (goroutines, channels) — Repository was explicitly created to explore Go's concurrency model; enables handling thousands of peer connections and I/O multiplexing efficiently without thread overhead.
• Bencode serialization — Native BitTorrent protocol encoding format; required for parsing metainfo files and peer protocol messages.
• DHT (Distributed Hash Table) — Decentralized peer discovery via anacrolix/dht/v2 dependency; enables operation without centralized trackers.
• Multiple storage backends (file, mmap, bolt, sqlite) — Pluggable storage abstraction allows users to choose persistence strategy based on use case (streaming, caching, full download).
• uTP (Micro Transport Protocol) — Included via anacrolix/go-libutp to support high peer connection counts without NAT/firewall issues on limited bandwidth.

• Library-first design (not a standalone daemon)

  • Why: Easier integration into existing Go applications; used in production since 2014 by downstream services.
  • Consequence: No built-in process management, web UI, or out-of-the-box standalone executable—users must write wrapper code or use provided CLI utilities.

• Streaming support with seeking and readahead

  • Why: Enables real-time playback of video/audio without full pre-download via Reader interface.
  • Consequence: Added complexity in piece scheduling and buffer management; increased memory footprint for readahead buffers.

• Protocol encryption and BitTorrent v2 support

  • Why: Future-proofing and privacy; v2 enables stronger hash verification and larger file support.
  • Consequence: Larger codebase; must maintain backward compatibility with v1 clients.

• Interface-driven storage abstraction

  • Why: Allows swapping backends (file ↔ mmap ↔ sqlite) without core client changes.
  • Consequence: Storage interface is relatively low-level; users implementing custom backends must handle piece I/O correctness carefully.

• Real-time streaming with guaranteed latency (best-effort streaming only)
• Windows native support (untested on Windows, though effort exists per workflows/windows.yml)
• Built-in authentication or authorization

No required env vars or services to run tests locally. Beware: platform-specific issues possible with edsrf/mmap-go (memory mapping) and go-libutp (native UDP transport)—test on target OS. Network tests may need loopback/localhost available. Storage backends have optional dependencies (sqlite requires go-llsqlite, bolt requires bbolt)—import selectively. Concurrency model uses heavy goroutine spawning; tests with -race flag to catch subtle bugs. Magnet URI and torrent file parsing is lenient by design to handle malformed data—validate output, don't assume correctness of untrusted metainfo.

• Bencode — Standard encoding format for all BitTorrent metainfo, tracker responses, and DHT messages—you'll encounter it constantly in protocol handling and must understand its quirks (e.g., dictionary key ordering)
• Distributed Hash Table (DHT) — Decentralized peer discovery mechanism (Kademlia-based) that replaces centralized trackers—critical for modern torrent bootstrapping without tracker dependency
• BitTorrent Enhancement Proposals (BEPs) — Standardized extensions to BitTorrent protocol (BEP 3=core, BEP 9=metadata, BEP 40=v2 hashing)—this repo implements dozens of them; understanding BEP numbering is essential for feature navigation
• uTP (Micro Transport Protocol) — UDP-based congestion-controlled transport replacing TCP for peer connections in modern torrents—reduces ISP complaints and enables hole-punching; this repo integrates it via go-libutp
• Memory-mapped I/O (mmap) — Storage backend optimization allowing OS to page torrent files on-disk directly into process memory space—critical for large-file streaming without copy overhead; see storage/mmap-go
• Piece Verification (SHA1/SHA256) — Cryptographic hash validation of downloaded pieces against torrent metainfo (BEP 3 = SHA1, BEP 40 = SHA256)—essential for integrity and preventing malicious data injection
• Streaming / Random Access on P2P — Ability to read torrent data out-of-order (seeking) and in real-time before full download via Go's io.Reader/Seeker—enables media playback without waiting for completion, a key differentiation of this client

• anacrolix/dht — Distributed Hash Table implementation used for peer discovery in this torrent client—required dependency for DHT bootstrap
• anacrolix/go-libutp — Go bindings for libutp (uTP protocol) providing alternative transport to TCP for torrent connections—integrated as peer protocol option
• transmission/transmission — Alternative reference BitTorrent client (C) providing protocol specifications and implementation patterns for comparison
• GopeedLab/gopeed — High-profile downstream project (22.8k★) using this torrent package as core for cross-platform download accelerator
• bitmagnet-io/bitmagnet — Modern BitTorrent indexer and search engine built on this library for DHT crawling and torrent metadata extraction

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for bencode package edge cases and fuzzing integration

The bencode package has fuzz test infrastructure (bencode/testdata/fuzz/) but lacks corresponding unit tests that validate the actual behavior against these fuzz corpus cases. Currently bencode/fuzz_test.go exists but there's no systematic test file that covers round-trip encoding/decoding for all fuzz test cases. This would improve stability of a critical encoding component used throughout the torrent library.

• [ ] Review bencode/testdata/fuzz/ directory contents and existing fuzz_test.go
• [ ] Create bencode/fuzz_corpus_test.go that programmatically loads and validates each fuzz test case
• [ ] Add tests validating that decoding followed by encoding produces equivalent output
• [ ] Ensure tests cover both FuzzInterfaceRoundTrip and Fuzz subdirectories

Add Windows-specific protocol tests in ci for WebRTC/uTP transport layers

The repo has .github/workflows/windows.yml but it likely only runs basic Go tests. Given the complexity of uTP (github.com/anacrolix/utp v0.1.0) and WebRTC (github.com/pion/webrtc/v4) support, Windows-specific transport edge cases may not be validated. Adding platform-specific transport protocol tests would catch Windows socket/network behavior differences.

• [ ] Review .github/workflows/windows.yml to see current test scope
• [ ] Identify uTP and WebRTC related tests in *_test.go files
• [ ] Add Windows-specific test step that runs -tags=webrtc tests
• [ ] Add validation for mmap-go behavior (edsrzf/mmap-go) on Windows which differs from Linux

Create integration tests for BEP implementations (BEP14, BEP40) with real torrent metadata

bep14.go and bep40.go exist with corresponding test files (bep14_test.go, bep40_test.go) but bencode/testdata/ contains real torrent files (archlinux-2011.08.19-netinstall-i686.iso.torrent, continuum.torrent) that aren't being used. Adding tests that parse these real torrent files and validate BEP14/BEP40 compliance would ensure compatibility with actual BitTorrent ecosystem metadata.

• [ ] Review bep14_test.go and bep40_test.go to identify current test coverage
• [ ] Create testdata/bep14_test.go or testdata/bep40_integration_test.go
• [ ] Write tests that load bencode/testdata/*.torrent files and validate BEP14 (private flag) parsing
• [ ] Add tests validating BEP40 (IPv6 support) metadata extraction from real torrent files

• Add integration tests for the cmd/torrent CLI tool that verify downloading a small public torrent (e.g., Archlinux ISO in bencode/testdata/) to a temp directory and checking file completeness—currently missing end-to-end CLI validation
• Extend bencode/decode_test.go with property-based fuzz tests covering edge cases in string/int encoding (e.g., leading zeros in integers, negative lengths)—testdata/fuzz/ shows structure but coverage could be expanded
• Document the storage backend interface with worked example in storage/impl.go showing how to implement a custom S3-backed backend—currently lacks concrete walkthrough and users must reverse-engineer from file/ example

The anacrolix/torrent codebase demonstrates reasonable security practices with automated testing and linting workflows. However, several outdated dependencies present medium-risk vulnerabilities that should be addressed through timely updates. The project's security policy is transparent and responsive. Main concerns are: (1) outdated Prometheus and fsnotify libraries lacking recent security patches, (2) unversioned Docker base image, and (3) lack of integrated security scanning in CI/CD. No hardcoded secrets, injection vulnerabilities, or critical misconfigurations were identified. The project is suitable for production use with recommended dependency updates.

• Medium · Outdated Prometheus Client Library — go.mod - github.com/prometheus/client_golang v1.12.2. The dependency github.com/prometheus/client_golang v1.12.2 is significantly outdated (released in 2022). This version may contain known security vulnerabilities and lacks security patches available in newer versions (v1.17+). Fix: Update prometheus/client_golang to the latest stable version (v1.17 or newer) to receive security patches and bug fixes.
• Medium · Outdated fsnotify Dependency — go.mod - github.com/fsnotify/fsnotify v1.5.4. The dependency github.com/fsnotify/fsnotify v1.5.4 is outdated (released in 2022). Newer versions contain security and stability improvements. Current version may have known issues. Fix: Update fsnotify to v1.7+ to get security patches and improved reliability.
• Low · Permissive Dockerfile Base Image — Dockerfile - line 3. The Dockerfile uses 'FROM alpine' without specifying a specific version tag. This can lead to inconsistent builds and potential security issues if a new Alpine image version introduces breaking changes or security regressions. Fix: Pin the Alpine version to a specific stable release, e.g., 'FROM alpine:3.19' or latest LTS version.
• Low · Unrestricted Cargo/Go Build Caches — Dockerfile - RUN --mount=type=cache directives. The Dockerfile mounts build caches without restrictions. While this improves build performance, it could potentially allow cache poisoning attacks in multi-tenant environments. Fix: Consider implementing cache validation, using read-only mounts where appropriate, or documenting cache security assumptions for your deployment environment.
• Low · Missing Security Headers and SBOM — .github/workflows - missing security scanning workflows. No evidence of security scanning tools (like Trivy, Snyk) integrated into the CI/CD pipeline. The repository includes golangci-lint but lacks complementary security scanning. Fix: Add security scanning workflows using tools like Trivy for container images, Snyk for dependencies, or OWASP Dependency-Check.
• Low · Git Submodules Without Pinned Versions — Dockerfile - line 12. The Dockerfile runs 'git submodule update --init --recursive' without verification of submodule integrity or pinned versions, which could introduce supply chain risks. Fix: Use 'git config --global credential.helper store' and verify submodule checksums, or consider using vendoring for critical dependencies.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.