Net::BitTorrent::DHT - Kademlia-like DHT Node
BitTorrent uses a "distributed sloppy hash table" (DHT) for storing peer contact information for "trackerless" torrents. In effect, each peer becomes a tracker. The protocol is based on Kademila and is implemented over UDP.
Net::BitTorrent::DHT's API is simple but powerful. ...well, I think so anyway.
The constructor accepts a number different arguments which all greatly affect the function of your DHT node. Any combination of the following arguments may be used during construction.
Note that standalone DHT nodes do not support or require the client argument but internally a Net::BitTorrent client is passed and serves as the parent of this node. For brevity, the following examples assume you are building a standalone node (for reasearch, etc.).
client
During construction, our local DHT nodeID can be set during construction. This is mostly useful when creating a standalone DHT node.
use Net::BitTorrent::DHT; # Plain text hex string my $node_a = Net::BitTorrent::DHT->new( nodeid => 'F' x 40 ); # Packed hex string my $node_b = Net::BitTorrent::DHT->new( nodeid => pack 'H*', 'F' x 40 ); # Bit::Vector object require Bit::Vector; my $node_c = Net::BitTorrent::DHT->new( nodeid => Bit::Vector->new_Hex( 160, 'ABCD' x 10 ) ); # A SHA1 digest require Digest::SHA; my $node_d = Net::BitTorrent::DHT->new( nodeid => Digest::SHA::sha1( $possibly_random_value ) );
Note that storing and reusing DHT nodeIDs over a number of sessions may seem advantagious (as if you had a "reserved parking place" in the DHT network) but will likely not improve performance as unseen nodeIDs are removed from remote routing tables after a half hour.
Also note that, for ease of use, the constructor can coerce many different forms into the Bit::Vector object we're expecting. NodeIDs, like SHA1 digests, are 160-bit integers.
Opens a specific UDP port number to the outside world on both IPv4 and IPv6.
use Net::BitTorrent::DHT; # A single possible port my $node_a = Net::BitTorrent::DHT->new( port => 1123 ); # A list of ports my $node_b = Net::BitTorrent::DHT->new( port => [1235 .. 9875] );
Note that when handed a list of ports, they are each tried until we are able to bind to the specific port.
This method asks for remote nodes with nodeIDs closer to our target. As the remote nodes respond, the callback is called with the following arguments:
target
This is the target nodeid. This is useful when you've set the same callback for multiple, concurrent find_node( ) quest .
find_node( )
node
This is a blessed object. TODO.
nodes
This is a list of ip:port combinations the remote node claims are close to our target.
A single find_node quest is an array ref which contains the following data:
find_node
This is the target nodeID.
coderef
This is the callback triggered as we locate new peers.
This is a list of nodes we have announced to so far.
timer
This is an AnyEvent timer which is triggered every few minutes.
Don't modify this.
use Net::BitTorrent::DHT; my $node = Net::BitTorrent::DHT->new( ); my $quest_a = $dht->find_node( pack( 'H*', 'A' x 40 ), \&dht_cb ); my $quest_b = $dht->find_node( '1' x 40, \&dht_cb ); sub dht_cb { my ($target, $node, $nodes) = @_; say sprintf '%s:%d handed us %d nodes they claim are close to %s', $node->host, $node->port, scalar(@$nodes), $target->to_Hex; }
This method initiates a search for peers serving a torrent with this infohash. As they are found, the callback is called with the following arguments:
infohash
This is the infohash related to these peers. This is useful when you've set the same callback for multiple, concurrent get_peers( ) quests.
get_peers( )
peers
This is an array ref of peers sent to us by aforementioned remote node.
A single get_peers quest is an array ref which contains the following data:
get_peers
This is the infohash related to these peers.
This is a compacted list of all peers found so far. This is probably more useful than the list passed to the callback.
This is an AnyEvent timer which is triggered every five minutes. When triggered, the node requests new peers from nodes in the bucket nearest to the infohash.
use Net::BitTorrent::DHT; my $node = Net::BitTorrent::DHT->new( ); my $quest_a = $dht->get_peers(pack('H*', 'A' x 40), \&dht_cb); my $quest_b = $dht->get_peers('1' x 40, \&dht_cb); sub dht_cb { my ($infohash, $node, $peers) = @_; say sprintf 'We found %d peers for %s from %s:%d via DHT', scalar(@$peers), $infohash->to_Hex, $node->host, $node->port; }
This method announces that the peer controlling the querying node is downloading a torrent on a port. These outgoing queries are sent to nodes 'close' to the target infohash. As the remote nodes respond, the callback is called with the following arguments:
This is the infohash related to this announcment. This is useful when you've set the same callback for multiple, concurrent announce_peer( ) quest .
announce_peer( )
port
This is port you defined above.
A single announce_peer quest is an array ref which contains the following data:
announce_peer
announce_peer queries require a token sent in reply to a get_peers query so they should be used together.
use Net::BitTorrent::DHT; my $node = Net::BitTorrent::DHT->new( ); my $quest_a = $dht->announce_peer(pack('H*', 'A' x 40), 6881, \&dht_cb); my $quest_b = $dht->announce_peer('1' x 40, 9585, \&dht_cb); sub dht_cb { my ($infohash, $port, $node) = @_; say sprintf '%s:%d now knows we are serving %s on port %d', $node->host, $node->port, $infohash->to_Hex, $port; }
This is a quick utility method which returns or prints (depending on context) a list of the IPv4-based routing table's bucket structure.
use Net::BitTorrent::DHT; my $node = Net::BitTorrent::DHT->new( ); # After some time has passed... $node->dump_ipv4_buckets; # prints to STDOUT with say my @dump = $node->dump_ipv4_buckets; # returns list of lines
This is a quick utility method which returns or prints (depending on context) a list of the IPv6-based routing table's bucket structure.
use Net::BitTorrent::DHT; my $node = Net::BitTorrent::DHT->new( ); # After some time has passed... $node->dump_ipv6_buckets; # prints to STDOUT with say my @dump = $node->dump_ipv6_buckets; # returns list of lines
Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/
CPAN ID: SANKO
Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>
This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.
When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.
Neither this module nor the Author is affiliated with BitTorrent, Inc.
To install Net::BitTorrent, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::BitTorrent
CPAN shell
perl -MCPAN -e shell install Net::BitTorrent
For more information on module installation, please visit the detailed CPAN module installation guide.