torrent

Documentation

Overview

Package torrent provides a BitTorrent client implementation.

Index

• Variables
• type Config
• type InfoHash
  • func (h InfoHash) String() string
• type Peer
• type PeerSource
• type Session
  • func New(cfg Config) (*Session, error)
  • func (s *Session) AddTorrent(r io.Reader) (*Torrent, error)
  • func (s *Session) AddURI(uri string) (*Torrent, error)
  • func (s *Session) Close() error
  • func (s *Session) GetTorrent(id string) *Torrent
  • func (s *Session) ListTorrents() []*Torrent
  • func (s *Session) RemoveTorrent(id string) error
  • func (s *Session) StartAll() error
  • func (s *Session) Stats() SessionStats
  • func (s *Session) StopAll() error
• type SessionStats
• type Stats
• type Status
• type Torrent
  • func (t *Torrent) AddPeer(addr *net.TCPAddr)
  • func (t *Torrent) AddTracker(uri string) error
  • func (t *Torrent) AddedAt() time.Time
  • func (t *Torrent) ID() string
  • func (t *Torrent) InfoHash() InfoHash
  • func (t *Torrent) Name() string
  • func (t *Torrent) Peers() []Peer
  • func (t *Torrent) Port() uint16
  • func (t *Torrent) Start() error
  • func (t *Torrent) Stats() Stats
  • func (t *Torrent) Stop() error
  • func (t *Torrent) Trackers() []Tracker
• type Tracker
• type TrackerStatus

Variables

var DefaultConfig = Config{

	Database:                        "~/rain/session.db",
	DataDir:                         "~/rain/data",
	PortBegin:                       50000,
	PortEnd:                         60000,
	PEXEnabled:                      true,
	BitfieldWriteInterval:           30 * time.Second,
	StatsWriteInterval:              30 * time.Second,
	PeerIDPrefix:                    "-RN" + Version + "-",
	ExtensionHandshakeClientVersion: "Rain " + Version,
	BlocklistUpdateInterval:         24 * time.Hour,
	BlocklistUpdateTimeout:          10 * time.Minute,
	TorrentAddHTTPTimeout:           30 * time.Second,

	RPCEnabled:         true,
	RPCHost:            "127.0.0.1",
	RPCPort:            7246,
	RPCShutdownTimeout: 5 * time.Second,

	TrackerNumWant:             100,
	TrackerStopTimeout:         5 * time.Second,
	TrackerMinAnnounceInterval: time.Minute,
	TrackerHTTPTimeout:         10 * time.Second,
	TrackerHTTPUserAgent:       "Rain/" + Version,

	DHTEnabled:             true,
	DHTAddress:             "0.0.0.0",
	DHTPort:                7246,
	DHTAnnounceInterval:    30 * time.Minute,
	DHTMinAnnounceInterval: time.Minute,

	UnchokedPeers:                3,
	OptimisticUnchokedPeers:      1,
	RequestQueueLength:           50,
	RequestTimeout:               20 * time.Second,
	EndgameMaxDuplicateDownloads: 20,
	MaxPeerDial:                  80,
	MaxPeerAccept:                20,
	MaxActivePieceBytes:          1024 * 1024 * 1024,
	ParallelMetadataDownloads:    2,
	PeerConnectTimeout:           5 * time.Second,
	PeerHandshakeTimeout:         10 * time.Second,
	PieceReadTimeout:             30 * time.Second,
	PeerReadBufferSize:           17,
	MaxPeerAddresses:             2000,

	PieceReadSize:  256 * 1024,
	PieceCacheSize: 256 * 1024 * 1024,
	PieceCacheTTL:  5 * time.Minute,
	ParallelReads:  10,
}

var Version = "0.0.0"

Version of client. Set during build. "0.0.0" is the development version.

Types

type Config

type Config struct {
	// Database file to save resume data.
	Database string
	// DataDir is where files are downloaded.
	DataDir string
	// New torrents will be listened at selected port in this range.
	PortBegin, PortEnd uint16
	// Enable peer exchange protocol.
	PEXEnabled bool
	// Bitfield is saved to disk for fast resume without hash checking.
	// There is an interval to keep IO lower.
	BitfieldWriteInterval time.Duration
	// Stats are written at interval to reduce write operations.
	StatsWriteInterval time.Duration
	// Peer id is prefixed with this string. See BEP 20. Remaining bytes of peer id will be randomized.
	PeerIDPrefix string
	// Client version that is sent in BEP 10 handshake message.
	ExtensionHandshakeClientVersion string
	// URL to the blocklist file in CIDR format.
	BlocklistURL string
	// When to refresh blocklist
	BlocklistUpdateInterval time.Duration
	// HTTP timeout for downloading blocklist
	BlocklistUpdateTimeout time.Duration
	// Time to wait when adding torrent with AddURI().
	TorrentAddHTTPTimeout time.Duration

	// Enable RPC server
	RPCEnabled bool
	// Host to listen for RPC server
	RPCHost string
	// Listen port for RPC server
	RPCPort int
	// Time to wait for ongoing requests before shutting down RPC HTTP server.
	RPCShutdownTimeout time.Duration

	// Enable DHT node.
	DHTEnabled bool
	// DHT node will listen on this IP.
	DHTAddress string
	// DHT node will listen on this UDP port.
	DHTPort uint16
	// DHT announce interval
	DHTAnnounceInterval time.Duration
	// Minimum announce interval when announcing to DHT.
	DHTMinAnnounceInterval time.Duration

	// Number of peer addresses to request in announce request.
	TrackerNumWant int
	// Time to wait for announcing stopped event.
	// Stopped event is sent to the tracker when torrent is stopped.
	TrackerStopTimeout time.Duration
	// When the client needs new peer addresses to connect, it ask to the tracker.
	// To prevent spamming the tracker an interval is set to wait before the next announce.
	TrackerMinAnnounceInterval time.Duration
	// Total time to wait for response to be read.
	// This includes ConnectTimeout and TLSHandshakeTimeout.
	TrackerHTTPTimeout time.Duration
	// User agent sent when communicating with HTTP trackers.
	TrackerHTTPUserAgent string

	// Number of unchoked peers.
	UnchokedPeers int
	// Number of optimistic unchoked peers.
	OptimisticUnchokedPeers int
	// Max number of blocks requested from a peer but not received yet
	RequestQueueLength int
	// Time to wait for a requested block to be received before marking peer as snubbed
	RequestTimeout time.Duration
	// Max number of running downloads on piece in endgame mode, snubbed and choed peers don't count
	EndgameMaxDuplicateDownloads int
	// Max number of outgoing connections to dial
	MaxPeerDial int
	// Max number of incoming connections to accept
	MaxPeerAccept int
	// Number of bytes allocated in memory for downloading piece data.
	MaxActivePieceBytes int64
	// Running metadata downloads, snubbed peers don't count
	ParallelMetadataDownloads int
	// Time to wait for TCP connection to open.
	PeerConnectTimeout time.Duration
	// Time to wait for BitTorrent handshake to complete.
	PeerHandshakeTimeout time.Duration
	// When peer has started to send piece block, if it does not send any bytes in PieceReadTimeout, the connection is closed.
	PieceReadTimeout time.Duration
	// Buffer size for messages read from a single peer
	PeerReadBufferSize int
	// Max number of peer addresses to keep in connect queue.
	MaxPeerAddresses int

	// Number of bytes to read when a piece is requested by a peer.
	PieceReadSize int64
	// Number of cached bytes for piece read requests.
	PieceCacheSize int64
	// Read bytes for a piece part expires after duration.
	PieceCacheTTL time.Duration
	// Number of read operations to do in parallel.
	ParallelReads uint

	// When the client want to connect a peer, first it tries to do encrypted handshake.
	// If it does not work, it connects to same peer again and does unencrypted handshake.
	// This behavior can be changed via this variable.
	DisableOutgoingEncryption bool
	// Dial only encrypted connections.
	ForceOutgoingEncryption bool
	// Do not accept unencrypted connections.
	ForceIncomingEncryption bool
}

Config for Session.

type InfoHash

type InfoHash [20]byte

func (InfoHash) String

func (h InfoHash) String() string

String encodes info hash in hex as 40 characters.

type Peer

type Peer struct {
	ID                 [20]byte
	Client             string
	Addr               net.Addr
	Source             PeerSource
	ConnectedAt        time.Time
	Downloading        bool
	ClientInterested   bool
	ClientChoking      bool
	PeerInterested     bool
	PeerChoking        bool
	OptimisticUnchoked bool
	Snubbed            bool
	EncryptedHandshake bool
	EncryptedStream    bool
	DownloadSpeed      uint
	UploadSpeed        uint
}

type PeerSource

type PeerSource int

const (
	SourceTracker PeerSource = iota
	SourceDHT
	SourcePEX
	SourceIncoming
)

type Session

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

func New

func New(cfg Config) (*Session, error)

New returns a pointer to new Rain BitTorrent client.

func (*Session) AddTorrent

func (s *Session) AddTorrent(r io.Reader) (*Torrent, error)

func (*Session) AddURI

func (s *Session) AddURI(uri string) (*Torrent, error)

func (*Session) Close

func (s *Session) Close() error

func (*Session) GetTorrent

func (s *Session) GetTorrent(id string) *Torrent

func (*Session) ListTorrents

func (s *Session) ListTorrents() []*Torrent

func (*Session) RemoveTorrent

func (s *Session) RemoveTorrent(id string) error

func (*Session) StartAll

func (s *Session) StartAll() error

func (*Session) Stats

func (s *Session) Stats() SessionStats

func (*Session) StopAll

func (s *Session) StopAll() error

type SessionStats

type SessionStats struct {
	Torrents                      int
	AvailablePorts                int
	BlockListRules                int
	BlockListLastSuccessfulUpdate time.Time
	PieceCacheItems               int
	PieceCacheSize                int64
	PieceCacheUtilization         int
	ReadsPerSecond                int
	ReadsActive                   int
	ReadsPending                  int
	ReadBytesPerSecond            int
	ActivePieceBytes              int64
	TorrentsPendingRAM            int
	Uptime                        time.Duration
}

type Stats

type Stats struct {
	// Status of the torrent.
	Status Status
	// Contains the error message if torrent is stopped unexpectedly.
	Error  error
	Pieces struct {
		// Number of pieces that are checked when torrent is in "Verifying" state.
		Checked uint32
		// Number of pieces that we are downloaded successfully and verivied by hash check.
		Have uint32
		// Number of pieces that need to be downloaded. Some of them may be being downloaded.
		// Pieces that are being downloaded may counted as missing until they are downloaded and passed hash check.
		Missing uint32
		// Number of unique pieces available on swarm.
		// If this number is less then the number of total pieces, the download may never finish.
		Available uint32
		// Number of total pieces in torrent.
		Total uint32
	}
	Bytes struct {
		// Bytes that are downloaded and passed hash check.
		Completed int64
		// The number of bytes that is needed to complete all missing pieces.
		Incomplete int64
		// The number of total bytes of files in torrent.  Total = Completed + Incomplete
		Total int64
		// Downloaded is the number of bytes downloaded from swarm.
		// Because some pieces may be downloaded more than once, this number may be greater than completed bytes.
		Downloaded int64
		// BytesUploaded is the number of bytes uploaded to the swarm.
		Uploaded int64
		// Bytes downloaded due to duplicate/non-requested pieces.
		Wasted int64
		// Bytes allocated on storage.
		Allocated int64
	}
	Peers struct {
		// Number of peers that are connected, handshaked and ready to send and receive messages.
		Total int
		// Number of peers that have connected to us.
		Incoming int
		// Number of peers that we have connected to.
		Outgoing int
	}
	Handshakes struct {
		// Number of peers that are not handshaked yet.
		Total int
		// Number of incoming peers in handshake state.
		Incoming int
		// Number of outgoing peers in handshake state.
		Outgoing int
	}
	Addresses struct {
		// Total number of peer addresses that are ready to be connected.
		Total int
		// Peers found via trackers.
		Tracker int
		// Peers found via DHT node.
		DHT int
		// Peers found via peer exchange.
		PEX int
	}
	Downloads struct {
		// Number of active piece downloads.
		Total int
		// Number of pieces that are being downloaded normally.
		Running int
		// Number of pieces that are being downloaded too slow.
		Snubbed int
		// Number of piece downloads in choked state.
		Choked int
	}
	MetadataDownloads struct {
		// Number of active metadata downloads.
		Total int
		// Number of peers that uploading too slow.
		Snubbed int
		// Number of peers that are being downloaded normally.
		Running int
	}
	// Name can change after metadata is downloaded.
	Name string
	// Is private torrent?
	Private bool
	// Length of a single piece.
	PieceLength uint32
	// Duration while the torrent is in Seeding status.
	SeededFor time.Duration
	// Speed is calculated as 1-minute moving average.
	Speed struct {
		// Downloaded bytes per second.
		Download uint
		// Uploaded bytes per second.
		Upload uint
	}
	// Time remaining to complete download. nil value means infinity.
	ETA *time.Duration
}

Stats contains statistics about Torrent.

type Status

type Status int

const (
	Stopped Status = iota
	DownloadingMetadata
	Allocating
	Verifying
	Downloading
	Seeding
	Stopping
)

type Torrent

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

func (*Torrent) AddPeer

func (t *Torrent) AddPeer(addr *net.TCPAddr)

func (*Torrent) AddTracker

func (t *Torrent) AddTracker(uri string) error

func (*Torrent) AddedAt

func (t *Torrent) AddedAt() time.Time

func (*Torrent) ID

func (t *Torrent) ID() string

func (*Torrent) InfoHash

func (t *Torrent) InfoHash() InfoHash

func (*Torrent) Name

func (t *Torrent) Name() string

func (*Torrent) Peers

func (t *Torrent) Peers() []Peer

func (*Torrent) Port

func (t *Torrent) Port() uint16

func (*Torrent) Start

func (t *Torrent) Start() error

func (*Torrent) Stats

func (t *Torrent) Stats() Stats

func (*Torrent) Stop

func (t *Torrent) Stop() error

func (*Torrent) Trackers

func (t *Torrent) Trackers() []Tracker

type Tracker

type Tracker struct {
	URL      string
	Status   TrackerStatus
	Leechers int
	Seeders  int
	Error    error
}

type TrackerStatus

type TrackerStatus int

const (
	NotContactedYet TrackerStatus = iota
	Contacting
	Working
	NotWorking
)