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) Stats() SessionStats
• type SessionStats
• type Stats
• type Status
• type Torrent
  • 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,
	MaxOpenFiles:                    1000000,
	PEXEnabled:                      true,
	BitfieldWriteInterval:           30 * time.Second,
	StatsWriteInterval:              30 * time.Second,
	PeerIDPrefix:                    "-RN" + Version + "-",
	ExtensionHandshakeClientVersion: "Rain " + Version,
	BlocklistUpdateInterval:         24 * time.Hour,

	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,
}

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
	// At start, client will set max open files limit to this number. (like "ulimit -n" command)
	MaxOpenFiles uint64
	// 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

	// 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
	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

	// 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 charachters.

type Peer

type Peer struct {
	ID                 [20]byte
	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) Stats

func (s *Session) Stats() SessionStats

type SessionStats

type SessionStats struct {
	Torrents                      int
	AvailablePorts                int
	BlockListRules                int
	BlockListLastSuccessfulUpdate time.Time
	PieceCacheItems               int
	PieceCacheSize                int64
	PieceCacheUtilization         int
	ActivePieceBytes              int64
	TorrentsPendingRAM            int
}

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) 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
)