Documentation
¶
Overview ¶
Package torrent implements the BitTorrent protocol. It is designed to be simple and easy to use. A common workflow is to create a Client, add a torrent and then download it.
cl, _ := torrent.NewClient(nil)
t, _ := cl.AddFromFile("example.torrent")
<-t.InfoC
t.StartDataTransfer()
<-t.DownloadedDataC
fmt.Println("torrent downloaded!")
Index ¶
- type Client
- func (cl *Client) AddFromFile(filename string) (*Torrent, error)
- func (cl *Client) AddFromInfoHash(infohash [20]byte) (*Torrent, error)
- func (cl *Client) AddFromMagnet(uri string) (*Torrent, error)
- func (cl *Client) AddFromParser(p metainfo.Parser) (*Torrent, error)
- func (cl *Client) Close()
- func (cl *Client) ID() []byte
- func (cl *Client) ListenPort() int
- func (cl *Client) Torrents() []*Torrent
- type Config
- type DefaultPieceSelector
- type Peer
- type PeerSource
- type Piece
- func (p *Piece) Blocks() int
- func (p *Piece) CompletedBlocks() int
- func (p *Piece) Data() (b []byte, err error)
- func (p *Piece) Index() int
- func (p *Piece) PendingBlocks() int
- func (p *Piece) Rarity() int
- func (p *Piece) Torrent() *Torrent
- func (p *Piece) UnrequestedBlocks() int
- func (p *Piece) Verified() bool
- type PieceSelector
- type Stats
- type Torrent
- func (t *Torrent) AddPeers(peers ...Peer) error
- func (t *Torrent) Close()
- func (t *Torrent) Closed() bool
- func (t *Torrent) DisableDataDownload() error
- func (t *Torrent) EnableDataDownload() error
- func (t *Torrent) HaveAllPieces() bool
- func (t *Torrent) Info() *metainfo.InfoDict
- func (t *Torrent) Metainfo() *metainfo.MetaInfo
- func (t *Torrent) Pieces() []Piece
- func (t *Torrent) Seeding() bool
- func (t *Torrent) StartDataTransfer() error
- func (t *Torrent) Stats() Stats
- func (t *Torrent) Swarm() []Peer
- func (t *Torrent) WriteStatus(w io.Writer)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client manages multiple torrents
func NewClient ¶
NewClient creates a new Client with the provided configuration. Use `NewClient(nil)` for the default configuration.
func (*Client) AddFromFile ¶
AddFromFile creates a torrent based on the contents of filename. The Torrent returned maybe be in seeding mode if all the data is already downloaded.
func (*Client) AddFromInfoHash ¶
AddFromInfoHash creates a torrent based on it's infohash
func (*Client) AddFromMagnet ¶
AddFromMagnet creates a torrent based on the magnet link provided
func (*Client) AddFromParser ¶
AddFromParser creates a torrent from the provided parser. See metainfo package for more.
func (*Client) Close ¶
func (cl *Client) Close()
Close calls torrent.Close for all the torrents managed by the client.
func (*Client) ListenPort ¶
ListenPort returns the port that the client listens for new connections
type Config ¶
type Config struct {
//Returns a new PieceSelector instantiated for each torrent the client manages
SelectorF func() PieceSelector
//Max outstanding requests per connection we allow for a peer to have
MaxOnFlightReqs int
//Max active/established connections per torrent
MaxEstablishedConns int
//This option disables DHT also.
RejectIncomingConnections bool
DisableTrackers bool
DisableDHT bool
//Directory to store the data
BaseDir string
//Function to open the storage.Provide your own for a custom storage implementation
OpenStorage storage.Open
//Dials for new connections will fail after this duration
DialTimeout time.Duration
//BitTorrent handshakes will fail after this duration
HandshakeTiemout time.Duration
}
Config provides configuration for a Client.
func DefaultConfig ¶
DefaultConfig returns the default configuration for a client
type DefaultPieceSelector ¶
type DefaultPieceSelector struct {
// contains filtered or unexported fields
}
func (*DefaultPieceSelector) Less ¶
func (dfs *DefaultPieceSelector) Less(p1, p2 *Piece) bool
Less is the default Less func. Pieces that have more pending and completed blocks have the highest priority. If the two pieces have both all blocks unrequested then: i) If no other piece in the Torrent has been downloaded, then we prioritize randomly. ii) Otherwise, by comparing their rarities. The one that is more rare gets prioritized.
func (*DefaultPieceSelector) OnPieceDownload ¶
func (dfs *DefaultPieceSelector) OnPieceDownload(_ int)
func (*DefaultPieceSelector) SetTorrent ¶
func (dfs *DefaultPieceSelector) SetTorrent(_ *Torrent)
type Peer ¶
type Peer struct {
P tracker.Peer
Source PeerSource
}
Holds basic information about a peer
type PeerSource ¶
type PeerSource byte
Which source informed us about that peer
const ( //The user manually added this peer SourceUser PeerSource = iota //It was an incoming connection SourceIncoming //The peer was given to us by DHT SourceDHT //The peer was given to us by a tracker SourceTracker )
type Piece ¶
type Piece struct {
// contains filtered or unexported fields
}
Piece represents a single bitTorrent piece. A piece is divided in blocks. A piece's block can be at one of the following three states: unrequested,pending or completed. All blocks are initially unrequested.When we request a block, then it becomes pending and when we download it it becomes completed.
func (*Piece) CompletedBlocks ¶
CompletedBlocks returns the number of completed blocks of p.
func (*Piece) Data ¶
Data Returns the data of the piece. Requires that the piece has been downloaded otherwise an error is returned.
func (*Piece) PendingBlocks ¶
PendingBlocks returns the number of pendingBlocks blocks of p.
func (*Piece) Rarity ¶
Rarity returns how many peers in the swarm have been known to own this piece. Note that is only an approximation and we can't know for sure the exact number of peers owning a piece.
func (*Piece) UnrequestedBlocks ¶
UnrequestedBlocks returns the number of unrequested blocks of p.
type PieceSelector ¶
type PieceSelector interface {
// Less reports whether p1 should be prioritized over p2.
// p1 and p2 have both unrequested blocks.
// Less will be executed every time the client wants to request pieces from a
// remote peer so it's important that its execution time is short.
// Moreover, Less should not call any of the torrent's methods because it will
// cause deadlock - it is called with the torrent's internall lock acquired,
// another reason to keep its execution time short-.
Less(p1, p2 *Piece) bool
// This is called when a piece is fully downloaded (and verified).
// i is the index of the downloaded piece.
// Useful if PieceSelector wants to change state after such an event.
OnPieceDownload(i int)
// Called when the PieceSelector is associated with a specific Torrent.
// Maybe useful for some initial setup.
SetTorrent(t *Torrent)
}
PieceSelector is responsible for selecting the order in which the torrent's pieces will be requested. Note that this is not the order in which they will be downloaded.
func NewDefaultPieceSelector ¶
func NewDefaultPieceSelector() PieceSelector
type Stats ¶
type Stats struct {
//Number of blocks/chunks downloaded (not necessarily verified)
BlocksDownloaded int
//Number of blocks/chunks uploaded
BlocksUploaded int
//Remainings bytes to download (bytes that are downloaded but not verified are not included)
BytesLeft int
//Number of verified bytes we have downloaded
BytesDownloaded int
//Number of bytes we have uploaded
BytesUploaded int
}
Stats contains statistics about a Torrent
type Torrent ¶
type Torrent struct {
//closes when the Torrent closes
ClosedC chan struct{}
//closes when all pieces have been downloaded
DownloadedDataC chan struct{}
//closes when we get the info dictionary.
InfoC chan struct{}
// contains filtered or unexported fields
}
Torrent represents a torrent and maintains state about it.Multiple goroutines may invoke methods on a Torrent simultaneously.
func (*Torrent) AddPeers ¶
AddPeers adds peers to the Torrent and (if needed) tries to establish connections with them. Returns error if the torrent is closed.
func (*Torrent) Close ¶
func (t *Torrent) Close()
Close removes the torrent from the Client and closes all connections with peers. Close is safe to be called multiple times on the same torrent.
func (*Torrent) DisableDataDownload ¶
DisableDataDownload pauses the process of downloading the torrent's data. It is an error to call this before calling StartDataTransfer.
func (*Torrent) EnableDataDownload ¶
EnableDataDownload re-enables downloading the torrent's data. To bootstrap the data downloading, one should call TransferData first. It is an error to call this before calling StartDataTransfer. Usually EnableDataDownload is called after a call to DisableDataDownload.
func (*Torrent) HaveAllPieces ¶
HaveAllPieces returns whether all torrent's data has been downloaded
func (*Torrent) Pieces ¶
Pieces returns all pieces of the torrent. If Info is not available or t is closed it returns nil.
func (*Torrent) Seeding ¶
Seeding returns true if `HaveAllPieces` returns true and a call to `Download` has been made for this torrent
func (*Torrent) StartDataTransfer ¶
StartDataTransfer enables downloading/uploading the torrent's data. It should be called once for each Torrent. It requires the info first i.e one should ensure that t.InfoC is closed After the download is complete, the Torrent transits in seeding mode (i.e altruistically upload) until it's closed. If the data are already there, StartDataTransfer returns immediatly and seeds the torrent.
func (*Torrent) WriteStatus ¶
WriteStatus writes to w a human readable message about the status of the Torrent.
Source Files
Directories