dht

Documentation

Overview

Package DHT implements a DHT for use with the BitTorrent protocol, described in BEP 5: http://www.bittorrent.org/beps/bep_0005.html.

Standard use involves creating a NewServer, and calling Announce on it with the details of your local torrent client and infohash of interest.

Index

• Constants
• func NodeIdSecure(id string, ip net.IP) bool
• func SecureNodeId(id []byte, ip net.IP)
• type Announce
  • func (me *Announce) Close()
  • func (me *Announce) NumContacted() int
• type KRPCError
  • func (me KRPCError) Error() string
• type Msg
  • func (m Msg) AnnounceToken() (token string, ok bool)
  • func (m Msg) Args() map[string]interface{}
  • func (m Msg) Error() (ret *KRPCError)
  • func (m Msg) Nodes() (nodes []NodeInfo)
  • func (m Msg) SenderID() string
  • func (m Msg) String() string
  • func (m Msg) T() (t string)
  • func (m Msg) Values() (vs []Peer)
• type NodeInfo
  • func (ni *NodeInfo) PutCompact(b []byte) error
  • func (cni *NodeInfo) UnmarshalCompact(b []byte) error
• type Peer
  • func (me *Peer) String() string
• type PeersValues
• type Server
  • func NewServer(c *ServerConfig) (s *Server, err error)
  • func (s *Server) AddNode(ni NodeInfo)
  • func (s *Server) Addr() net.Addr
  • func (s *Server) Announce(infoHash string, port int, impliedPort bool) (*Announce, error)
  • func (s *Server) Close()
  • func (s *Server) ID() string
  • func (s *Server) IPBlocklist() *iplist.IPList
  • func (s *Server) Nodes() (nis []NodeInfo)
  • func (s *Server) NumNodes() int
  • func (s *Server) Ping(node *net.UDPAddr) (*Transaction, error)
  • func (s *Server) SetIPBlockList(list *iplist.IPList)
  • func (s *Server) Stats() (ss ServerStats)
  • func (s *Server) String() string
• type ServerConfig
• type ServerStats
• type Transaction
  • func (t *Transaction) Close()
  • func (t *Transaction) SetResponseHandler(f func(Msg))

Constants

const CompactNodeInfoLen = 26

The size in bytes of a NodeInfo in its compact binary representation.

Functions

func NodeIdSecure

func NodeIdSecure(id string, ip net.IP) bool

Returns whether the node ID is considered secure. The id is the 20 raw bytes. http://www.libtorrent.org/dht_sec.html

func SecureNodeId

func SecureNodeId(id []byte, ip net.IP)

Makes a node ID secure, in-place. The ID is 20 raw bytes. http://www.libtorrent.org/dht_sec.html

Types

type Announce

type Announce struct {
	Peers chan PeersValues
	// contains filtered or unexported fields
}

Maintains state for an ongoing Announce operation. An Announce is started by calling Server.Announce.

func (*Announce) Close

func (me *Announce) Close()

Stop the announce.

func (*Announce) NumContacted

func (me *Announce) NumContacted() int

Returns the number of distinct remote addresses the announce has queried.

type KRPCError

type KRPCError struct {
	Code int
	Msg  string
}

func (KRPCError) Error

func (me KRPCError) Error() string

type Msg

type Msg map[string]interface{}

A wrapper around the unmarshalled KRPC dict that constitutes messages in the DHT. There are various helpers for extracting common data from the message. In normal use, Msg is abstracted away for you, but it can be of interest.

func (Msg) AnnounceToken

func (m Msg) AnnounceToken() (token string, ok bool)

Returns the token given in response to a get_peers request for future announce_peer requests to that node.

func (Msg) Args

func (m Msg) Args() map[string]interface{}

func (Msg) Error

func (m Msg) Error() (ret *KRPCError)

func (Msg) Nodes

func (m Msg) Nodes() (nodes []NodeInfo)

Suggested nodes in a response.

func (Msg) SenderID

func (m Msg) SenderID() string

func (Msg) String

func (m Msg) String() string

func (Msg) T

func (m Msg) T() (t string)

func (Msg) Values

func (m Msg) Values() (vs []Peer)

In a get_peers response, the addresses of torrent clients involved with the queried info-hash.

type NodeInfo

type NodeInfo struct {
	ID   [20]byte
	Addr dHTAddr
}

func (*NodeInfo) PutCompact

func (ni *NodeInfo) PutCompact(b []byte) error

Writes the node info to its compact binary representation in b. See CompactNodeInfoLen.

func (*NodeInfo) UnmarshalCompact

func (cni *NodeInfo) UnmarshalCompact(b []byte) error

type Peer

type Peer struct {
	IP   net.IP
	Port int
}

func (*Peer) String

func (me *Peer) String() string

type PeersValues

type PeersValues struct {
	Peers    []Peer // Peers given in get_peers response.
	NodeInfo        // The node that gave the response.
}

Corresponds to the "values" key in a get_peers KRPC response. A list of peers that a node has reported as being in the swarm for a queried info hash.

type Server

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

func NewServer

func NewServer(c *ServerConfig) (s *Server, err error)

Create a new DHT server.

func (*Server) AddNode

func (s *Server) AddNode(ni NodeInfo)

Adds directly to the node table.

func (*Server) Addr

func (s *Server) Addr() net.Addr

Returns the listen address for the server. Packets arriving to this address are processed by the server (unless aliens are involved).

func (*Server) Announce

func (s *Server) Announce(infoHash string, port int, impliedPort bool) (*Announce, error)

This is kind of the main thing you want to do with DHT. It traverses the graph toward nodes that store peers for the infohash, streaming them to the caller, and announcing the local node to each node if allowed and specified.

func (*Server) Close

func (s *Server) Close()

Stops the server network activity. This is all that's required to clean-up a Server.

func (*Server) ID

func (s *Server) ID() string

Returns the 20-byte server ID. This is the ID used to communicate with the DHT network.

func (*Server) IPBlocklist

func (s *Server) IPBlocklist() *iplist.IPList

func (*Server) Nodes

func (s *Server) Nodes() (nis []NodeInfo)

Exports the current node table.

func (*Server) NumNodes

func (s *Server) NumNodes() int

Returns how many nodes are in the node table.

func (*Server) Ping

func (s *Server) Ping(node *net.UDPAddr) (*Transaction, error)

Sends a ping query to the address given.

func (*Server) SetIPBlockList

func (s *Server) SetIPBlockList(list *iplist.IPList)

Packets to and from any address matching a range in the list are dropped.

func (*Server) Stats

func (s *Server) Stats() (ss ServerStats)

Returns statistics for the server.

func (*Server) String

func (s *Server) String() string

Returns a description of the Server. Python repr-style.

type ServerConfig

type ServerConfig struct {
	Addr string // Listen address. Used if Conn is nil.
	Conn net.PacketConn
	// Don't respond to queries from other nodes.
	Passive bool
	// DHT Bootstrap nodes
	BootstrapNodes []string
	// Disable the DHT security extension:
	// http://www.libtorrent.org/dht_sec.html.
	NoSecurity bool
	// Initial IP blocklist to use. Applied before serving and bootstrapping
	// begins.
	IPBlocklist *iplist.IPList
	// Used to secure the server's ID. Defaults to the Conn's LocalAddr().
	PublicIP net.IP
}

type ServerStats

type ServerStats struct {
	// Count of nodes in the node table that responded to our last query or
	// haven't yet been queried.
	GoodNodes int
	// Count of nodes in the node table.
	Nodes int
	// Transactions awaiting a response.
	OutstandingTransactions int
	// Individual announce_peer requests that got a success response.
	ConfirmedAnnounces int
	// Nodes that have been blocked.
	BadNodes uint
}

type Transaction

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

func (*Transaction) Close

func (t *Transaction) Close()

Abandon the transaction.

func (*Transaction) SetResponseHandler

func (t *Transaction) SetResponseHandler(f func(Msg))

Set a function to be called with the response.