anacrolix/torrent

The torrentfs package provides a way to expose a torrent client as a read-only filesystem. The core logic is FUSE-library-agnostic, providing the fundamental types and helpers. To actually mount the filesystem, you must use a concrete FUSE backend implementation.

Available backends:

• anacrolix/og-torrentfs: Uses the anacrolix/fuse library. Supports macFUSE and fuse-t on macOS, and fusermount on Linux.
• anacrolix/hanwen-torrentfs: Uses the hanwen/go-fuse/v2 library. Uses the macFUSE socket protocol on macOS (note: this is incompatible with fuse-t).

You can install the BitTorrent library package for use in your Go projects, or install the provided command-line utilities.

To install the library:

go get github.com/anacrolix/torrent

To install the command-line tools (cmds):

go install github.com/anacrolix/torrent/cmd/...@latest

Note: Installing via import path uses Go's module-aware mode and ignores the repository's go.work file, meaning it works without needing to check out git submodules.

To use the bencode encoding/decoding sub-package in your Go project, install the main torrent repository using go get.

go get github.com/anacrolix/torrent

The repository uses a Go workspace (go.work) that includes the possum storage backend as a git submodule. If you are building from a local clone (e.g., using go build ./...), you must ensure submodules are initialized, otherwise the build will fail because it cannot find the possum module.

To clone the repository with all necessary submodules:

git clone --recurse-submodules https://github.com/anacrolix/torrent

To update submodules in an existing clone:

git submodule update --init --recursive

Alternatively, you can disable the workspace by setting GOWORK=off, but the possum storage backend will not be available.

The torrent positional argument accepts several formats to identify the torrent to be downloaded:

1. Magnet URIs: Prefixed with magnet:
2. HTTP/HTTPS URLs: Direct links to .torrent files (e.g., http://example.com/file.torrent)
3. Infohashes: Prefixed with infohash: followed by the hex string
4. Local Files: A path to a .torrent file on the filesystem

The webseed.Client allows you to fetch data from a webserver (webseed) to satisfy torrent piece requirements. You initialize a client with an http.Client and a base Url, then use StartNewRequest to obtain a Request object that provides an io.Reader for the requested data.

To use the client:

1. Create a webseed.Client.
2. Call SetInfo with the torrent's metainfo.Info and a segments.Index to map files to URLs.
3. Call StartNewRequest with a segments.Extent (RequestSpec) to begin downloading a specific range of data.
4. Read from the returned Request.Body.
5. Call Request.Close() or Request.Cancel() when finished.

To enable BEP-14 Local Service Discovery, provide a LocalServiceDiscoveryConfig to the LocalServiceDiscovery field in ClientConfig:

You can control the bandwidth usage of the client using golang.org/x/time/rate limiters within ClientConfig:

• UploadRateLimiter: Limits bytes sent to peers. If the burst is set to 0, the implementation automatically sets it to MaxAllocPeerRequestDataPerConn to ensure it can fit a full chunk.
• DownloadRateLimiter: Limits bytes read from peer connections. If nil, no rate limiting is applied.

To check the effective download limit, use EffectiveDownloadRateLimit(l *rate.Limiter), which returns rate.Inf if the limiter is nil.