torrent

package module
v0.0.0-...-1d901b0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 6, 2026 License: MPL-2.0 Imports: 77 Imported by: 2

README

torrent

GoDoc

This repository is a refactor of anacrolix's, to simplify the API of the library, use more idiomatic code, improve horizontal scalability, remove extraneous dependencies, and to add in some extended functionality.

improvements implemented by library

  • smaller API surface. simplifying use, while still maintaining almost full functionality provided (some read ahead logic is broken, which is risky anyways due to the data being unvalidated).
  • refactored the single lock used for all torrents out. this means the torrents do not contend with each other for the singe lock.
  • removed a number of panic making the code safer to use (more to do here).
  • ability to use arbitrary socket implementations, as long as they are IP/Port based.

improvements planned

  • performance enhancements.

Installation

Install the library package with go get -u github.com/james-lawrence/torrent, or the provided cmds with go get -u github.com/james-lawrence/torrent/cmd/....

Library examples

There are some small examples in the package documentation.

Help

Communication about the project is through the issue tracker.

torrent

Downloads torrents from the command-line. This first example does not use godo.

$ go get github.com/james-lawrence/torrent/cmd/torrent
# Now 'torrent' should be in $GOPATH/bin, which should be in $PATH.
$ torrent 'magnet:?xt=urn:btih:KRWPCX3SJUM4IMM4YF5RPHL6ANPYTQPU'
ubuntu-14.04.2-desktop-amd64.iso [===================================================================>]  99% downloading (1.0 GB/1.0 GB)
2015/04/01 02:08:20 main.go:137: downloaded ALL the torrents
$ md5sum ubuntu-14.04.2-desktop-amd64.iso
1b305d585b1918f297164add46784116  ubuntu-14.04.2-desktop-amd64.iso
$ echo such amaze
wow
torrentfs

torrentfs mounts a FUSE filesystem at -mountDir. The contents are the torrents described by the torrent files and magnet links at -metainfoDir. Data for read requests is fetched only as required from the torrent network, and stored at -downloadDir.

$ mkdir mnt torrents
$ godo github.com/james-lawrence/torrent/cmd/torrentfs -mountDir=mnt -metainfoDir=torrents &
$ cd torrents
$ wget http://releases.ubuntu.com/14.04.2/ubuntu-14.04.2-desktop-amd64.iso.torrent
$ cd ..
$ ls mnt
ubuntu-14.04.2-desktop-amd64.iso
$ pv mnt/ubuntu-14.04.2-desktop-amd64.iso | md5sum
996MB 0:04:40 [3.55MB/s] [========================================>] 100%
1b305d585b1918f297164add46784116  -
torrent-magnet

Creates a magnet link from a torrent file. Note the extracted trackers, display name, and info hash.

$ godo github.com/james-lawrence/torrent/cmd/torrent-magnet < ubuntu-14.04.2-desktop-amd64.iso.torrent
magnet:?xt=urn:btih:546cf15f724d19c4319cc17b179d7e035f89c1f4&dn=ubuntu-14.04.2-desktop-amd64.iso&tr=http%3A%2F%2Ftorrent.ubuntu.com%3A6969%2Fannounce&tr=http%3A%2F%2Fipv6.torrent.ubuntu.com%3A6969%2Fannounce

Documentation

Overview

Package torrent implements a torrent client

  • simple api.
  • performant.

BitTorrent features implemented include:

  • Protocol obfuscation
  • DHT
  • uTP
  • PEX
  • Magnet links
  • IP Blocklists
  • Some IPv6
  • HTTP and UDP tracker clients
  • BEPs:
  • 3: Basic BitTorrent protocol
  • 5: DHT
  • 6: Fast Extension (have all/none only)
  • 7: IPv6 Tracker Extension
  • 9: ut_metadata
  • 10: Extension protocol
  • 11: PEX
  • 12: Multitracker metadata extension
  • 15: UDP Tracker Protocol
  • 20: Peer ID convention ("-GTnnnn-")
  • 23: Tracker Returns Compact Peer Lists
  • 27: Private torrents
  • 29: uTorrent transport protocol
  • 41: UDP Tracker Protocol Extensions
  • 42: DHT Security extension
  • 43: Read-only DHT Nodes
Example (CustomNetworkProtocols) 
package main

import (
	"context"
	"io"
	"log"
	"net"
	"os"

	"github.com/james-lawrence/torrent"
	"github.com/james-lawrence/torrent/sockets"
	"github.com/james-lawrence/torrent/storage"
)

func main() {
	var (
		err      error
		metadata torrent.Metadata
	)

	l, err := net.Listen("unix", "")
	if err != nil {
		log.Fatalln(err)
		return
	}
	defer l.Close()

	s := sockets.New(l, &net.Dialer{LocalAddr: l.Addr()})
	c, _ := torrent.NewSocketsBind(s).Bind(torrent.NewClient(torrent.NewDefaultClientConfig(
		torrent.NewMetadataCache(os.TempDir()),
		storage.NewFile(os.TempDir()),
		// torrent.ClientConfigBootstrapGlobal,
	)))
	defer c.Close()

	if metadata, err = torrent.NewFromMagnet("magnet:?xt=urn:btih:ZOCMZQIPFFW7OLLMIC5HUB6BPCSDEOQU"); err != nil {
		log.Fatalln(err)
		return
	}

	dl, _, err := c.Start(metadata)
	if err != nil {
		log.Fatalln(err)
		return
	}

	if _, err = torrent.DownloadInto(context.Background(), io.Discard, dl); err != nil {
		log.Fatalln(err)
		return
	}

	log.Print("torrent downloaded")
}
Example (Download) 
package main

import (
	"context"
	"io"
	"log"

	"github.com/james-lawrence/torrent"
	"github.com/james-lawrence/torrent/autobind"
)

func main() {
	var (
		err      error
		metadata torrent.Metadata
	)

	c, _ := autobind.NewDefaultClient()
	defer c.Close()

	if metadata, err = torrent.NewFromMagnet("magnet:?xt=urn:btih:ZOCMZQIPFFW7OLLMIC5HUB6BPCSDEOQU"); err != nil {
		log.Fatalln(err)
		return
	}
	dl, _, err := c.Start(metadata)
	if err != nil {
		log.Fatalln(err)
		return
	}

	if _, err = torrent.DownloadInto(context.Background(), io.Discard, dl); err != nil {
		// if _, err = c.DownloadInto(context.Background(), metadata, io.Discard); err != nil {
		log.Fatalln(err)
		return
	}

	log.Print("torrent downloaded")
}
Example (FileReader) 
package main

import (
	"github.com/james-lawrence/torrent"
)

func main() {
	var f torrent.File
	// Accesses the parts of the torrent pertaining to f. Data will be
	// downloaded as required, per the configuration of the torrent.Reader.
	r := f.NewReader()
	defer r.Close()
}

Index

Examples

Constants

View Source 
const (
	ErrTorrentNotActive                     = errorsx.String("torrent not active")
	ErrTorrentAttemptedToPersistNilMetadata = errorsx.String("cannot persist torrent metadata when missing info")
)
View Source 
const DefaultHTTPUserAgent = "Ghost-Torrent/1.0"

DefaultHTTPUserAgent ...

View Source 
const ErrNoPeers = errorsx.String("failed to locate any peers for torrent")

Variables

This section is empty.

Functions

func ClientConfigEnableEncryption 

func ClientConfigEnableEncryption(cc *ClientConfig)

func ClientConfigNoop 

func ClientConfigNoop(c *ClientConfig)

useful for default noop configurations.

func ConnExtensions 

func ConnExtensions(ctx context.Context, ws *writerstate) error

See the order given in Transmission's tr_peerMsgsNew.

func DHTAnnounce 

func DHTAnnounce(ctx context.Context, d *dht.Server, id int160.T) (iterx.Seq[dht.PeersValues], error)

func DHTAnnounceOnce 

func DHTAnnounceOnce(ctx context.Context, d *dht.Server, id int160.T) (err error)

func DownloadInto 

func DownloadInto(ctx context.Context, dst io.Writer, m Torrent, options ...Tuner) (n int64, err error)

Download a torrent into a writer blocking until completion.

func DownloadRange 

func DownloadRange(ctx context.Context, m Torrent, off int64, length int64, options ...Tuner) (_ io.ReadSeekCloser)

Return a ReadSeeker for the given range

func DownloadedSnapshotRestore 

func DownloadedSnapshotRestore(unverified *roaring.Bitmap) chunkopt

DownloadedSnapshotRestore initializes the chunks from a snapshot created by DownloadedSnapshotSave. the snapshot is every chunk that had been downloaded. none of it has been verified since the restore, so every chunk in the snapshot is restored as unverified (including the chunks of pieces that were completed when the snapshot was saved) and every other chunk is missing. nothing is completed. unverified chunks are verified as they are read (see blockingreader), or by a verification tuner. chunks outside of the torrent are ignored. inflight and failed are left untouched. the chunks are not locked, apply it with Mut.

func DownloadedSnapshotSave 

func DownloadedSnapshotSave(c *chunks) *roaring.Bitmap

func Downloader 

func Downloader(ctx context.Context, m Torrent, options ...Tuner) io.ReadSeekCloser

Downloader returns a ReadSeekCloser for the torrent. blocks until the metadata has been retrieved, if that fails (ctx done, tune failure) the returned reader yields the cause as its error.

func ErrTorrentClosed 

func ErrTorrentClosed() error

func LogDiscard 

func LogDiscard() discard

func NewBitmapCache 

func NewBitmapCache(root string) bitmapfilestore

func NewCache 

func NewCache(s MetadataStore, b BitmapStore) *memoryseeding

func NewMagnet 

func NewMagnet(md Metadata) metainfo.Magnet

func NewMetadataCache 

func NewMetadataCache(root string) metadatafilestore

func NewSocketsBind 

func NewSocketsBind(s ...sockets.Socket) binder

NewSocketsBind binds a set of sockets to the client. it bypasses any disable checks (tcp,udp, ip4/6) from the configuration.

func OptionNoop 

func OptionNoop(t *Metadata)

OptionNoop does nothing, stand in during configurations.

func RunHandshookConn 

func RunHandshookConn(c *connection, t *torrent) error

func TrackerAnnounceUntil 

func TrackerAnnounceUntil(ctx context.Context, t *torrent, donefn func() bool, options ...tracker.AnnounceOption)

func TrackerEvent 

func TrackerEvent(ctx context.Context, l Torrent, announceuri string, options ...tracker.AnnounceOption) (ret *tracker.AnnounceResponse, err error)

func TuneAnnounceUntilComplete 

func TuneAnnounceUntilComplete(t *torrent) error

func TuneAutoDownload 

func TuneAutoDownload(t *torrent) error

used after info has been received to mark all chunks missing. will only happen if missing and completed are zero.

func TuneComplete 

func TuneComplete(t *torrent) error

func TuneDisableTrackers 

func TuneDisableTrackers(t *torrent) error

func TuneIdleAutoUnload 

func TuneIdleAutoUnload(t *torrent) error

TuneIdleAutoUnload unloads the torrent from memory once it has been idle for the torrent's idle timeout. see TuneIdleBehavior.

func TuneNewConns 

func TuneNewConns(t *torrent) error

force new connections to be found

func TuneNoop 

func TuneNoop(t *torrent) error

func TuneRecordMetadata 

func TuneRecordMetadata(t *torrent) error

func TuneResetBitmaps 

func TuneResetBitmaps(t *torrent) error

reset all the bitmaps

func TuneSeeding 

func TuneSeeding(t *torrent) error

func TuneVerifyAsync 

func TuneVerifyAsync(t *torrent) error

Verify the contents asynchronously

func TuneVerifyFull 

func TuneVerifyFull(t *torrent) error

Verify the entirety of the torrent. will block

func Verify 

func Verify(ctx context.Context, t Torrent) error

func VerifyStored 

func VerifyStored(ctx context.Context, md *metainfo.MetaInfo, t io.ReaderAt) (missing *roaring.Bitmap, readable *roaring.Bitmap, _ error)

returns a bitmap of the verified data within the storage implementation.

Types

type Binder 

type Binder interface {
	// Bind to the given client if err is nil.
	Bind(cl *Client, err error) (*Client, error)
	Close() error
}

Binder binds network sockets to the client.

type BinderOption 

type BinderOption func(v *binder)

func BinderOptionDHT 

func BinderOptionDHT(d *dht.Server) BinderOption

BinderOptionDHT serves the dht server on the packet sockets, replacing the socketless dht server clients start with.

type BitmapStore 

type BitmapStore interface {
	Delete(id int160.T) error
	Read(id int160.T) (*roaring.Bitmap, error)
	Write(id int160.T, bm *roaring.Bitmap) error
}

type ChunkOp 

type ChunkOp[T any] func(*chunks) T

ChunkOp is a read-only operation against chunks' internal state, run while chunks' lock is held - lets a call site read multiple related fields (e.g. several bitmaps, or a bitmap plus the outstanding map) as one consistent, safely-locked snapshot instead of chaining separate locked accessor calls, or reading a field directly with no lock at all.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client contain zero or more Torrents. A Client manages a blocklist, the TCP/UDP protocol ports, and DHT as desired.

func NewClient 

func NewClient(cfg *ClientConfig) (_ *Client, err error)

NewClient create a new client from the provided config. nil is acceptable.

func (*Client) AddDHTNodes 

func (cl *Client) AddDHTNodes(nodes []string)

AddDHTNodes adds nodes to the DHT servers.

func (*Client) Bind 

func (cl *Client) Bind(s sockets.Socket) (err error)

Bind the socket to this client. packet sockets are also served by the dht server of the client.

func (*Client) BindDHT 

func (cl *Client) BindDHT(d *dht.Server)

BindDHT replaces the dht server of the client, nil is ignored. do this before binding sockets (see Bind), the client identifies itself to peers with the id of its dht server and packet sockets are served by it.

func (*Client) Close 

func (cl *Client) Close() error

Close stops the client. All connections to peers are closed and all activity will come to a halt.

func (*Client) Closed 

func (cl *Client) Closed() <-chan struct{}

Closed returns a channel to detect when the client is closed.

func (*Client) Config 

func (cl *Client) Config() *ClientConfig

Config underlying configuration for the client.

func (*Client) Info 

func (cl *Client) Info(ctx context.Context, m Metadata, options ...Tuner) (i *metainfo.Info, err error)

Query torrent info from the dht

func (*Client) ListenAddrs 

func (cl *Client) ListenAddrs() (ret []net.Addr)

ListenAddrs addresses currently being listened to.

func (*Client) LocalPort16 

func (cl *Client) LocalPort16() (port uint16)

LocalPort16 returns the local port being listened on. this is method is odd given a client can be attached to multiple ports on different listeners.

func (*Client) MaybeStart 

func (cl *Client) MaybeStart(t Metadata, failed error, options ...Tuner) (dl Torrent, added bool, err error)

MaybeStart is a convience method that consumes the return types of the torrent creation methods: New, NewFromFile, etc. it is all respects identical to the Start method.

func (*Client) Modify 

func (cl *Client) Modify(ctx context.Context, md Metadata, options ...Tuner) (err error)

Modify an already running torrent, returns an error if torrent isnt already running. if you want to start OR modify just use the standard Start function.

func (*Client) Start 

func (cl *Client) Start(t Metadata, options ...Tuner) (dl Torrent, added bool, err error)

Start the specified torrent. Start adds starts up the torrent within the client downloading the missing pieces as needed. if you want to wait until the torrent is completed use Download.

func (*Client) Stop 

func (cl *Client) Stop(t Metadata) (err error)

Stop the specified torrent, this halts all network activity around the torrent for this client.

func (*Client) String 

func (cl *Client) String() string

func (*Client) Tune 

func (cl *Client) Tune(ops ...ClientOperation) error

type ClientConfig 

type ClientConfig struct {
	UpnpID string

	// Upload even after there's nothing in it for us.
	Seed bool `long:"seed"`

	// Only applies to chunks uploaded to peers, to maintain responsiveness
	// communicating local Client state to peers. Each limiter token
	// represents one byte. The Limiter's burst must be large enough to fit a
	// whole chunk, which is usually 16 KiB (see TorrentSpec.ChunkSize).
	UploadRateLimiter *rate.Limiter
	// Rate limits all reads from connections to peers. Each limiter token
	// represents one byte. The Limiter's burst must be bigger than the
	// largest Read performed on a the underlying rate-limiting io.Reader
	// minus one. This is likely to be the larger of the main read loop buffer
	// (~4096), and the requested chunk size (~16KiB, see
	// TorrentSpec.ChunkSize).
	DownloadRateLimiter *rate.Limiter

	HeaderObfuscationPolicy HeaderObfuscationPolicy

	// The crypto methods to offer when initiating connections with header obfuscation.
	CryptoProvides mse.CryptoMethod
	// Chooses the crypto method to use when receiving connections with header obfuscation.
	CryptoSelector mse.CryptoSelector

	Error  logging // standard logging for errors, defaults to stderr
	Warn   logging // warn logging
	Logger logging // informational logging
	Debug  logging // debug logging, defaults to discard

	// HTTPProxy defines proxy for HTTP requests.
	// Format: func(*Request) (*url.URL, error),
	// or result of http.ProxyURL(HTTPProxy).
	// By default, it is composed from ClientConfig.ProxyURL,
	// if not set explicitly in ClientConfig struct
	HTTPProxy func(*http.Request) (*url.URL, error)
	// HTTPUserAgent changes default UserAgent for HTTP requests
	HTTPUserAgent string

	// Peer dial timeout to use when there are limited peers.
	NominalDialTimeout time.Duration
	// Minimum peer dial timeout to use (even if we have lots of peers).
	MinDialTimeout time.Duration

	// Maximum number of peer addresses in reserve.
	TorrentPeersHighWater int
	// Minumum number of peers before effort is made to obtain more peers.
	TorrentPeersLowWater int
	// Failed connection attempts after which a torrent discards a peer. see ClientConfigPeerMaxAttempts.
	PeerMaxAttempts uint64

	Handshaker connections.Handshaker

	ConnectionClosed func(ih int160.T, stats ConnStats, remaining int)
	// contains filtered or unexported fields
}

ClientConfig not safe to modify this after it's given to a Client.

func NewDefaultClientConfig 

func NewDefaultClientConfig(mdstore MetadataStore, store storage.ClientImpl, options ...ClientConfigOption) *ClientConfig

NewDefaultClientConfig default client configuration.

func (*ClientConfig) AnnounceRequest 

func (cfg *ClientConfig) AnnounceRequest(s *Client) tracker.Announce

func (*ClientConfig) Storage 

func (cfg *ClientConfig) Storage() storage.ClientImpl

type ClientConfigOption 

type ClientConfigOption func(*ClientConfig)

ClientConfigOption options for the client configuration

func ClientConfigAcceptLimit 

func ClientConfigAcceptLimit(l *rate.Limiter) ClientConfigOption

specify the global capacity for accepting inbound connections

func ClientConfigCacheDirectory 

func ClientConfigCacheDirectory(s string) ClientConfigOption

func ClientConfigCompose 

func ClientConfigCompose(options ...ClientConfigOption) ClientConfigOption

func ClientConfigConnectionClosed 

func ClientConfigConnectionClosed(fn func(ih int160.T, stats ConnStats, remaining int)) ClientConfigOption

func ClientConfigDebugLogger 

func ClientConfigDebugLogger(l logging) ClientConfigOption

func ClientConfigDialPoolSize 

func ClientConfigDialPoolSize[T constraints.Integer](n T) ClientConfigOption

specify the number of routines for dialing peers

func ClientConfigDialRateLimit 

func ClientConfigDialRateLimit(l *rate.Limiter) ClientConfigOption

func ClientConfigDialTimeouts 

func ClientConfigDialTimeouts(healthy, starving time.Duration) ClientConfigOption

specify dialing timeouts healthy timeout for when the the torrent has sufficient peers connected. and starving when it lacks peers. defaults are 4 and 16 respectively. generally, when starving you'll want to be more forgiving and set a larger timeout.

func ClientConfigDialer 

func ClientConfigDialer(d netx.Dialer) ClientConfigOption

func ClientConfigDownloadLimit 

func ClientConfigDownloadLimit(l *rate.Limiter) ClientConfigOption

specify the global capacity for downloading pieces from peers.

func ClientConfigExtension 

func ClientConfigExtension(name pp.ExtensionName) ClientConfigOption

func ClientConfigExtensionBits 

func ClientConfigExtensionBits(bits ...uint) ClientConfigOption

change what extension bits are set.

func ClientConfigFirewall 

func ClientConfigFirewall(fw connections.FirewallStateful) ClientConfigOption

func ClientConfigHTTPUserAgent 

func ClientConfigHTTPUserAgent(s string) ClientConfigOption

func ClientConfigHandshakeTimeout 

func ClientConfigHandshakeTimeout(d time.Duration) ClientConfigOption

how long we should wait for handshakes

func ClientConfigIDPrefix 

func ClientConfigIDPrefix(prefix string) ClientConfigOption

peer id prefix for BEP20 implementation.

func ClientConfigIdleTimeout 

func ClientConfigIdleTimeout(d time.Duration) ClientConfigOption

ClientConfigIdleTimeout unload torrents from memory once they have had no activity for the given duration. a seeding torrent with connections is never idle. the torrent remains on disk and is reloaded when a peer connects. zero disables idle unloading.

func ClientConfigInfoLogger 

func ClientConfigInfoLogger(l logging) ClientConfigOption

ClientConfigInfoLogger set the info logger

func ClientConfigKeepAlive 

func ClientConfigKeepAlive(d time.Duration) ClientConfigOption

ClientConfigKeepAlive how often connections send keepalives, a connection that has sent nothing for two intervals is considered dead and dropped. peers should be configured to match, a peer with a longer interval is dropped while quiet. defaults to 10 seconds.

func ClientConfigMaxConnecting 

func ClientConfigMaxConnecting[T constraints.Integer](connecting T) ClientConfigOption

specify the limit to the number of peers a torrent will attempt to connect to concurrently.

func ClientConfigMaxOutstandingRequests 

func ClientConfigMaxOutstandingRequests(n int) ClientConfigOption

func ClientConfigMetadata 

func ClientConfigMetadata(b bool) ClientConfigOption

func ClientConfigPEX 

func ClientConfigPEX(b bool) ClientConfigOption

func ClientConfigPeerLimits 

func ClientConfigPeerLimits[T constraints.Integer](low, high T) ClientConfigOption

specify the low and high watermarks for torrent peering

func ClientConfigPeerMaxAttempts 

func ClientConfigPeerMaxAttempts[T constraints.Integer](n T) ClientConfigOption

specify the number of failed connection attempts after which a torrent discards a peer. a discarded peer is only used again if it is added again, see TunePeersPeriodic.

func ClientConfigSeed 

func ClientConfigSeed(b bool) ClientConfigOption

ClientConfigSeed enable/disable seeding

func ClientConfigStorage 

func ClientConfigStorage(s storage.ClientImpl) ClientConfigOption

func ClientConfigStorageDir 

func ClientConfigStorageDir(dir string) ClientConfigOption

func ClientConfigUploadLimit 

func ClientConfigUploadLimit(l *rate.Limiter) ClientConfigOption

specify the global capacity for uploading pieces to peers.

type ClientOperation 

type ClientOperation func(*Client) error

func ClientOperationClearIdleTorrents 

func ClientOperationClearIdleTorrents(idle func(Stats) bool) ClientOperation

type ConnStats 

type ConnStats struct {
	// Total bytes on the wire. Includes handshakes and encryption.
	BytesWritten     count
	BytesWrittenData count

	BytesRead           count
	BytesReadData       count
	BytesReadUsefulData count

	// Bytes confirmed via successful piece hash verification. Unlike
	// BytesReadUsefulData (credited optimistically on receipt, before
	// verification), this only increases once a piece's SHA1 matches - it is
	// the value reported to trackers as BEP3 "downloaded".
	BytesValidated count

	ChunksWritten count

	ChunksRead       count
	ChunksReadUseful count
	ChunksReadWasted count

	MetadataChunksRead count

	// Number of pieces data was written to, that subsequently passed verification.
	PiecesDirtiedGood count
	// Number of pieces data was written to, that subsequently failed
	// verification. Note that a connection may not have been the sole dirtier
	// of a piece.
	PiecesDirtiedBad count

	DHTAnnounce count
}

ConnStats various connection-level metrics. At the Torrent level these are aggregates. Chunks are messages with data payloads. Data is actual torrent content without any overhead. Useful is something we needed locally. Unwanted is something we didn't ask for (but may still be useful). Written is things sent to the peer, and Read is stuff received from them.

func (*ConnStats) Copy 

func (t *ConnStats) Copy() (ret ConnStats)

Copy returns a copy of the connection stats.

func (ConnStats) ResetTransferMetrics 

func (t ConnStats) ResetTransferMetrics() ConnStats

type File 

type File struct {
	// contains filtered or unexported fields
}

File provides access to regions of torrent data that correspond to its files.

func (*File) BytesCompleted 

func (f *File) BytesCompleted() int64

BytesCompleted number of bytes of the entire file we have completed. This is the sum of completed pieces, and dirtied chunks of incomplete pieces.

func (*File) DisplayPath 

func (f *File) DisplayPath() string

DisplayPath the relative file path for a multi-file torrent, and the torrent name for a single-file torrent.

func (File) FileInfo 

func (f File) FileInfo() metainfo.FileInfo

FileInfo from the metainfo.Info to which this file corresponds.

func (*File) Length 

func (f *File) Length() int64

Length the file's length in bytes.

func (*File) NewReader 

func (f *File) NewReader() Reader

NewReader returns a reader for the file.

func (*File) Offset 

func (f *File) Offset() int64

Offset data for this file begins this many bytes into the Torrent.

func (File) Path 

func (f File) Path() string

Path the file's path components joined by '/'.

func (*File) Torrent 

func (f *File) Torrent() Torrent

Torrent returns the associated torrent

type Handle 

type Handle interface {
	io.Reader
	io.Seeker
	io.Closer
	io.ReaderAt
}

Handle a file-like handle to some torrent data resource.

type HeaderObfuscationPolicy 

type HeaderObfuscationPolicy struct {
	Required  bool // Whether the value of Preferred is a strict requirement.
	Preferred bool // Whether header obfuscation is preferred.
}

HeaderObfuscationPolicy ...

type Metadata 

type Metadata struct {
	// The tiered tracker URIs.
	Trackers  []string
	ID        int160.T
	InfoBytes []byte
	// The name to use if the Name field from the Info isn't available.
	DisplayName string
	Webseeds    []string
	DHTNodes    []string
	// The chunk size to use for outbound requests. Defaults to 16KiB if not
	// set.
	ChunkSize uint64
	Storage   storage.ClientImpl
}

Metadata specifies the metadata of a torrent for adding to a client. There are helpers for magnet URIs and torrent metainfo files.

func New 

func New(info metainfo.Hash, options ...Option) (t Metadata, err error)

New create a torrent from just a infohash and any additional options.

func NewFromFile 

func NewFromFile(path string, options ...Option) (t Metadata, err error)

NewFromFile convience method to create a torrent directly from a file.

func NewFromInfo 

func NewFromInfo(i *metainfo.Info, options ...Option) (t Metadata, err error)

NewFromInfo creates a torrent from metainfo.Info

func NewFromInfoFile 

func NewFromInfoFile(path string, options ...Option) (t Metadata, err error)

NewFromMetaInfoFile loads torrent info stored in a file.

func NewFromMagnet 

func NewFromMagnet(uri string, options ...Option) (t Metadata, err error)

NewFromMagnet creates a torrent from a magnet uri.

func NewFromMetaInfo 

func NewFromMetaInfo(mi *metainfo.MetaInfo, options ...Option) (t Metadata, err error)

NewFromMetaInfo create a torrent from metainfo

func NewFromMetaInfoFile 

func NewFromMetaInfoFile(path string, options ...Option) (t Metadata, err error)

NewFromMetaInfoFile loads torrent metadata stored in a file.

func NewFromMetaInfoReader 

func NewFromMetaInfoReader(src io.Reader, options ...Option) (t Metadata, err error)

func (Metadata) Announce 

func (t Metadata) Announce() string

grabs random tracker from available.

func (Metadata) Merge 

func (t Metadata) Merge(options ...Option) Metadata

Merge Metadata options into the current metadata.

func (Metadata) Metainfo 

func (t Metadata) Metainfo() metainfo.MetaInfo

Metainfo generate metainfo from the metadata.

type MetadataStore 

type MetadataStore interface {
	Read(id int160.T) (Metadata, error)
	Write(md Metadata) error
	Each() iter.Seq[int160.T]
}

type Option 

type Option func(*Metadata)

Option for the torrent.

func OptionChunk 

func OptionChunk[T constraints.Integer](s T) Option

OptionChunk sets the size of the chunks to use for outbound requests

func OptionDisplayName 

func OptionDisplayName(dn string) Option

OptionDisplayName set the display name for the torrent.

func OptionInfo 

func OptionInfo(i []byte) Option

OptionInfo set the info bytes for the torrent.

func OptionNodes 

func OptionNodes(nodes ...string) Option

OptionNodes supplimental nodes to add to the dht of the client.

func OptionPublicTrackers 

func OptionPublicTrackers(private bool, trackers ...string) Option

func OptionResetTrackers 

func OptionResetTrackers(trackers ...string) Option

OptionTrackers set the trackers for the torrent.

func OptionStorage 

func OptionStorage(s storage.ClientImpl) Option

OptionStorage set the storage implementation for the torrent.

func OptionTrackers 

func OptionTrackers(trackers ...string) Option

OptionTrackers add the trackers to the torrent.

func OptionWebseeds 

func OptionWebseeds(seeds []string) Option

OptionWebseeds set the webseed hosts for the torrent.

type Peer 

type Peer struct {
	ID int160.T
	netip.AddrPort
	btprotocol.PexPeerFlags
	LastAttempt        time.Time
	Attempts           uint64
	Source             peerSource
	SupportsEncryption bool // Peer is known to support encryption.
	Trusted            bool // Whether we can ignore poor or bad behaviour from the peer.
}

Peer connection info, handed about publicly.

func NewPeer 

func NewPeer(id int160.T, addr netip.AddrPort, options ...PeerOption) Peer

func NewPeerDeprecated 

func NewPeerDeprecated(id int160.T, ip net.IP, port uint16, options ...PeerOption) Peer

func NewPeersFromURI 

func NewPeersFromURI(uris ...url.URL) (peers []Peer)

generate a peer from a uri in the form of: p0000000000000000000000000000000000000000://127.0.0.1:3196 aka: p{nodeID}://ip:port

func (*Peer) FromPex 

func (me *Peer) FromPex(na krpc.NodeAddr, fs btprotocol.PexPeerFlags)

FromPex generate Peer from peer exchange

type PeerOption 

type PeerOption func(*Peer)

func PeerOptionEncrypted 

func PeerOptionEncrypted(b bool) PeerOption

func PeerOptionSource 

func PeerOptionSource(src peerSource) PeerOption

func PeerOptionTrusted 

func PeerOptionTrusted(b bool) PeerOption

type PeerSource 

type PeerSource func() []Peer

PeerSource provides the current set of peers for a torrent, it is called each time the peers are added. the set can change between calls, for example as the membership of a cluster changes.

type Peers 

type Peers []Peer

func TrackerAnnounceOnce 

func TrackerAnnounceOnce(ctx context.Context, l Torrent, uri string, options ...tracker.AnnounceOption) (delay time.Duration, peers Peers, err error)

func (*Peers) AppendFromPex 

func (me *Peers) AppendFromPex(nas []krpc.NodeAddr, fs []btprotocol.PexPeerFlags)

func (Peers) AppendFromTracker 

func (ret Peers) AppendFromTracker(ps []tracker.Peer) Peers

type Reader 

type Reader interface {
	io.Reader
	io.Seeker
	io.Closer
}

Reader for a torrent

func NewReader 

func NewReader(t Torrent) Reader

type Stats 

type Stats struct {
	// Aggregates stats over all connections past and present. Some values may
	// not have much meaning in the aggregate context.
	ConnStats

	// metrics marking the progress of the torrent
	// these are in chunks.
	Missing     int
	Outstanding int
	Unverified  int
	Failed      int
	Completed   int

	// Downloaded number of bytes of the entire torrent we have completed. This is the sum of
	// the pieces that are known to be good: completed pieces, and pieces credited when the
	// torrent was resumed. Chunks of incomplete pieces and unverified chunks are not included.
	// Do not use this for download rate, as it can go down when pieces are lost or fail checks.
	// Sample ConnStats.DataBytesRead for actual file data download rate.
	Downloaded uint64

	// DownloadedOptimistic number of bytes of the entire torrent we have, assuming the unverified
	// chunks are good. This is the sum of completed pieces and unverified chunks, and can
	// overcount when an unverified chunk turns out to be bad or the last chunk is short.
	DownloadedOptimistic uint64

	// Remaining number of bytes of the entire torrent still to be downloaded.
	Remaining uint64

	// Ordered by expected descending quantities (if all is well).
	MaximumAllowedPeers int
	TotalPeers          int
	PendingPeers        int
	ActivePeers         int
	HalfOpenPeers       int
	Seeders             int

	Seeding        bool
	LastConnection time.Time
	// last connection change or validated piece, used for idle unloading.
	LastActivity time.Time
}

Stats high level stats about the torrent.

func (Stats) String 

func (stats Stats) String() string

type Torrent 

type Torrent interface {
	Metadata() Metadata
	Tune(...Tuner) error
	Stats() Stats
	Info() *metainfo.Info         // TODO: remove, this should be pulled from Metadata()
	GotInfo() <-chan struct{}     // TODO: remove, torrents should never be returned if they don't have the meta info.
	Storage() storage.TorrentImpl // temporary replacement for reader.
}

Torrent represents the state of a torrent within a client. interface is currently being used to ease the transition of to a cleaner API. Many methods should not be called before the info is available, see .Info and .GotInfo.

type TorrentComplete 

type TorrentComplete struct{}

TorrentComplete is published to pieceStateChanges when all pieces are verified.

type Tuner 

type Tuner func(*torrent) error

Tuner runtime tuning of an actively running torrent.

func TuneAnnounceOnce 

func TuneAnnounceOnce(options ...tracker.AnnounceOption) Tuner

Announce to trackers looking for at least one successful request that returns peers.

func TuneClientPeer 

func TuneClientPeer(cl *Client) Tuner

TuneClientPeer adds a trusted, pending peer for each of the Client's addresses. used for tests.

func TuneDownloadRange 

func TuneDownloadRange(offset int64, length int64) Tuner

mark missing the provided range of bytes.

func TuneIdleBehavior 

func TuneIdleBehavior(fn func(t *torrent)) Tuner

TuneIdleBehavior spawns a goroutine that calls fn once the torrent has been idle for the torrent's idle timeout, then exits. does nothing when the idle timeout is disabled. the timeout is cloned from the client config, each application spawns its own watcher.

func TuneMaxConnections 

func TuneMaxConnections(max int) Tuner

TuneMaxConnections adjust the maximum connections allowed for a torrent.

func TunePeers 

func TunePeers(peers ...Peer) Tuner

TunePeers add peers to the torrent.

func TunePeersPeriodic 

func TunePeersPeriodic(ctx context.Context, interval time.Duration, source PeerSource) Tuner

TunePeersPeriodic adds the peers from the source to the torrent, and again every interval until the context is cancelled or the torrent closes. peers are discarded after repeated failed connection attempts (see ClientConfigPeerMaxAttempts), adding them again gives the ones that were discarded another chance, and peers that joined the source since are picked up. peers still in play are not duplicated.

each application spawns its own loop, applying it repeatedly to the same torrent is on the caller. a zero interval only adds the peers once.

func TunePublicTrackers 

func TunePublicTrackers(trackers ...string) Tuner

func TuneReadAnnounce 

func TuneReadAnnounce(v *tracker.Announce) Tuner

func TuneReadBytesRemaining 

func TuneReadBytesRemaining(v *int64) Tuner

func TuneReadHashID 

func TuneReadHashID(id *int160.T) Tuner

func TuneReadPeerID 

func TuneReadPeerID(id *int160.T) Tuner

Extract the peer id from the torrent

func TuneReadPeers 

func TuneReadPeers(peers *[]Peer) Tuner

TuneReadPeers reads the torrent's known swarm peers (active, pending, half-open).

func TuneReadPort 

func TuneReadPort(v *uint16) Tuner

func TuneReadUserAgent 

func TuneReadUserAgent(v *string) Tuner

func TuneResetTrackingStats 

func TuneResetTrackingStats(s *Stats) Tuner

Reset tracking data for tracker events

func TuneSubscribe 

func TuneSubscribe(sub *pubsub.Subscription) Tuner

The subscription emits as (int) the index of pieces as their state changes. A state change is when the PieceState for a piece alters in value.

func TuneTrackers 

func TuneTrackers(trackers ...string) Tuner

add trackers to the torrent.

func TuneVerifyBitmap 

func TuneVerifyBitmap(unverified *roaring.Bitmap, n uint64) Tuner

TuneVerifyBitmap initializes the chunks from a snapshot of the downloaded chunks (see DownloadedSnapshotSave) and verifies n of the pieces that the snapshot says were downloaded. the pieces are chosen at random from the pieces that have every chunk downloaded, plus the first and last of them. partially downloaded pieces are never chosen, they stay unverified and are verified once their remaining chunks arrive.

if the sample is verified the bitmap is considered correct, the pieces that were not sampled stay unverified until they are read, they are counted as validated immediately (and not again when they are hashed) so the stats reflect what was downloaded before. if any of the sample fails the bitmap is incorrect and the entire torrent is verified.

an empty snapshot means nothing is known about the data, it may be a new torrent or the data may be on disk without a snapshot (seeding from existing files). everything is assumed to be downloaded and the sample finds out, if the sample fails the entire torrent is verified and whatever is not there is marked missing. will block until complete.

func TuneVerifyRange 

func TuneVerifyRange(offset, length int64) Tuner

Verify the provided byte range (expanding as needed to match piece boundaries). will block.

func TuneVerifySample 

func TuneVerifySample(n uint64) Tuner

Verify a random selection of n pieces. will block until complete blocks. if any of the sampled pieces failed it'll perform a full verify. it always checks the first and last piece regardless of the random set, as a result at most n+2 pieces will be verified. this makes it easy to test certain behaviors live. NOTE: torrents with a low completed rate will almost always perform a full verify. but since there will also be a smaller amount of data on disk this is a fair trade off.

type WebseedStats 

type WebseedStats struct {
	Root          string
	BytesFetched  int64
	ChunksFetched int64
	Errors        int64
	Started       time.Time
	Stopped       time.Time
}

WebseedStats is a snapshot of a single webseed's activity for the lifetime of its worker.

func (WebseedStats) String 

func (s WebseedStats) String() string

Source Files

View all Source files

Directories

Path Synopsis
Package autobind for automically binding on the local server this package is only for convience and it's suggested to use torrent.NewSocketsBind instead.
 Package autobind for automically binding on the local server this package is only for convience and it's suggested to use torrent.NewSocketsBind instead.
Package bep0019 implements BEP19 HTTP/FTP webseeding (the GetRight-style url-list protocol): fetching torrent data via HTTP range requests against mirrors listed in a torrent's url-list / a magnet's ws= parameters, rather than from BitTorrent peers.
 Package bep0019 implements BEP19 HTTP/FTP webseeding (the GetRight-style url-list protocol): fetching torrent data via HTTP range requests against mirrors listed in a torrent's url-list / a magnet's ws= parameters, rather than from BitTorrent peers.
Package bep0051 implements DHT infohash indexing https://www.bittorrent.org/beps/bep_0051.html
 Package bep0051 implements DHT infohash indexing https://www.bittorrent.org/beps/bep_0051.html
Package bep0052 implements the data structures and algorithms defined in BitTorrent Enhancement Proposal 52 (BEP 52): The BitTorrent Protocol Specification v2.
 Package bep0052 implements the data structures and algorithms defined in BitTorrent Enhancement Proposal 52 (BEP 52): The BitTorrent Protocol Specification v2.
dht
Package dht implements a Distributed Hash Table (DHT) part of the BitTorrent protocol, as specified by BEP 5: http://www.bittorrent.org/beps/bep_0005.html
 Package dht implements a Distributed Hash Table (DHT) part of the BitTorrent protocol, as specified by BEP 5: http://www.bittorrent.org/beps/bep_0005.html
bep44
containers
int160
internal/testutil
k-nearest-nodes
krpc
peer-store
transactions
traversal
traversal2
types
internal
asynccompute
atomicx
backoffx
bitmapx
bytesx
chansync
Package chansync is cloned from github.com/anacrolix/chansync to reduce dependency tree.
 Package chansync is cloned from github.com/anacrolix/chansync to reduce dependency tree.
cryptox
debugx
envx
Package envx provides utility functions for extracting information from environment variables
 Package envx provides utility functions for extracting information from environment variables
errorsx
Package errorsx provides simple error handling primitives.
 Package errorsx provides simple error handling primitives.
fnvx
iox
iterx
langx
Package langx provides small utility functions to extend the standard golang language.
 Package langx provides small utility functions to extend the standard golang language.
md5x
multiless
netx
rendezvous
slicesx
slogx
stmutil
stringsx
testutil
Package testutil contains stuff for testing torrent-related behaviour.
 Package testutil contains stuff for testing torrent-related behaviour.
testx
timex
userx
utpx
Package iplist handles the P2P Plaintext Format described by https://en.wikipedia.org/wiki/PeerGuardian#P2P_plaintext_format.
 Package iplist handles the P2P Plaintext Format described by https://en.wikipedia.org/wiki/PeerGuardian#P2P_plaintext_format.
cmd/pack-blocklist command
Takes P2P blocklist text format in stdin, and outputs the packed format from the iplist package.
 Takes P2P blocklist text format in stdin, and outputs the packed format from the iplist package.
Package logonce implements an io.Writer facade that only performs distinct writes.
 Package logonce implements an io.Writer facade that only performs distinct writes.
Package sockets implements examples of how to write sockets for the torrent client.
 Package sockets implements examples of how to write sockets for the torrent client.
Package storage implements storage backends for package torrent.
 Package storage implements storage backends for package torrent.
Package upnp implements UPnP InternetGatewayDevice discovery, querying, and port mapping.
 Package upnp implements UPnP InternetGatewayDevice discovery, querying, and port mapping.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
⌂ 换网址