NAME

Net::BitTorrent::DHT - Kademlia-like DHT Node

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 and is implemented over UDP.

Methods

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.

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

Net::BitTorrent::DHT->new( nodeid => 'F' x 40 )

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.

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 .

• 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:

• 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 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;
    }

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.

• 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 is an array ref which contains the following data:

• infohash

  This is the infohash related to these peers.

• 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 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.

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

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 .

• port

  This is port you defined above.

• node

  This is a blessed object. TODO.

A single announce_peer quest is an array ref which contains the following data:

• infohash

  This is the infohash related to these peers.

• 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 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(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;
    }

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 <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

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.

cpanm Net::BitTorrent

perl -MCPAN -e shell
install Net::BitTorrent