# NAME
Net::BitTorrent::DHT - Kademlia-like DHT Node for BitTorrent
# Synopsis
use Net::BitTorrent::DHT;
use AnyEvent;
use Bit::Vector;
# Standalone node with user-defined port and boot_nodes
my $dht = Net::BitTorrent::DHT->new(
port => [1337 .. 1340, 0],
boot_nodes =>
[['router.bittorrent.com', 6881], ['router.utorrent.com', 6881]]
);
my $peer_quest
= $dht->get_peers(Bit::Vector->new_Hex('ab97a7bca78f2628380e6609a8241a7fb02aa981'), \&dht_cb);
# tick, tick, tick, ...
AnyEvent->condvar->recv;
sub dht_cb {
my ($infohash, $node, $peers) = @_;
printf "We found %d peers for %s from %s:%d via DHT\n\t%s\n",
scalar(@$peers),
$infohash->to_Hex, $node->host, $node->port,
join ', ', map { sprintf '%s:%d', @$_ } @$peers;
}
# Description
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](#kademlia) and is implemented
over UDP.
# Methods
[Net::BitTorrent::DHT](https://metacpan.org/pod/Net::BitTorrent::DHT)'s API is simple but powerful.
...well, I think so anyway.
# Net::BitTorrent::DHT->new( )
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.
For brevity, the following examples assume you are building a
[standalone node](https://metacpan.org/pod/Net::BitTorrent::DHT::Standalone) (for reasearch, etc.).
## Net::BitTorrent::DHT->new( nodeid => ... )
During construction, our local DHT nodeID can be set during construction. This
is mostly useful when creating a
[standalone DHT node](https://metacpan.org/pod/Net::BitTorrent::DHT::Standalone).
use Net::BitTorrent::DHT;
# Bit::Vector object
use Bit::Vector;
my $node_c = Net::BitTorrent::DHT->new(
nodeid => Bit::Vector->new_Hex( 160, 'ABCD' x 10 )
);
# A SHA1 digest
use Digest::SHA;
my $node_d = Net::BitTorrent::DHT->new(
nodeid => Bit::Vector->new_Hex( 160, 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.
NodeIDs, are 160-bit integers.
## Net::BitTorrent::DHT->new( port => ... )
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.
# Net::BitTorrent::DHT->find\_node( $target, $callback )
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](#quests-and-callbacks).
Targets are 160-bit [Bit::Vector](https://metacpan.org/pod/Bit::Vector) objects.
- 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](https://metacpan.org/pod/Net::BitTorrent::Notes#Quests-and-Callbacks)
is an array ref which contains the following data:
- target
This is the target nodeID.
- coderef
This is the callback triggered as we locate new peers.
- nodes
This is a list of nodes we have announced to so far.
- timer
This is an [AnyEvent](https://metacpan.org/pod/AnyEvent) timer which is triggered every few minutes.
Don't modify this.
# Net::BitTorrent::DHT->get\_peers( $infohash, $callback )
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. This is a
160-bit [Bit::Vector](https://metacpan.org/pod/Bit::Vector) object.
- node
This is a blessed object. TODO.
- peers
This is an array ref of peers sent to us by aforementioned remote node.
A single `get_peers` [quest](https://metacpan.org/pod/Net::BitTorrent::Notes#Quests-and-Callbacks)
is an array ref which contains the following data:
- infohash
This is the infohash related to these peers. This is a 160-bit
[Bit::Vector](https://metacpan.org/pod/Bit::Vector) object.
- coderef
This is the callback triggered as we locate new peers.
- peers
This is a compacted list of all peers found so far. This is probably more
useful than the list passed to the callback.
- timer
This is an [AnyEvent](https://metacpan.org/pod/AnyEvent) timer which is triggered every five minutes.
When triggered, the node requests new peers from nodes in the bucket nearest
to the infohash.
Don't modify this.
# Net::BitTorrent::DHT->**announce\_peer**( $infohash, $port, $callback )
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:
- infohash
This is the infohash related to this announcment. This is useful when you've
set the same callback for multiple, concurrent `announce_peer( )`
[quest](#quests-and-callbacks). Infohashes are 160-bit
[Bit::Vector](https://metacpan.org/pod/Bit::Vector) objects.
- port
This is port you defined above.
- node
This is a blessed object. TODO.
A single `announce_peer` [quest](#quests-and-callbacks) is an array ref
which contains the following data:
- infohash
This is the infohash related to these peers. This is a 160-bit
[Bit::Vector](https://metacpan.org/pod/Bit::Vector) object.
- coderef
This is the callback triggered as we locate new peers.
- port
This is port you defined above.
- nodes
This is a list of nodes we have announced to so far.
- timer
This is an [AnyEvent](https://metacpan.org/pod/AnyEvent) timer which is triggered every few minutes.
Don't modify this.
`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(Bit::Vector->new_Hex('A' x 40), 6881, \&dht_cb);
my $quest_b = $dht->announce_peer(Bit::Vector->new_Hex('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;
}
# Net::BitTorrent::DHT->dump\_ipv4\_buckets( )
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
# Net::BitTorrent::DHT->dump\_ipv6\_buckets( )
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
# Author
Sanko Robinson - http://sankorobinson.com/
CPAN ID: SANKO
# License and Legal
Copyright (C) 2008-2014 by Sanko Robinson
This program is free software; you can redistribute it and/or modify it under
the terms of
[The Artistic License 2.0](http://www.perlfoundation.org/artistic_license_2_0).
See the `LICENSE` file included with this distribution or
[notes on the Artistic License 2.0](http://www.perlfoundation.org/artistic_2_0_notes)
for clarification.
When separated from the distribution, all original POD documentation is
covered by the
[Creative Commons Attribution-Share Alike 3.0 License](http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
See the
[clarification of the CCA-SA3.0](http://creativecommons.org/licenses/by-sa/3.0/us/).
Neither this module nor the [Author](#author) is affiliated with BitTorrent,
Inc.