NAME

Net::BitTorrent::Protocol::BEP05 - Packet Utilities for BEP05: The DHT Protocol

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. This module provides packet building functions for this protocol.

Importing From Net::BitTorrent::Protocol::BEP05

By default, nothing is exported.

You may import any of the following or use one or more of these tag:

:all

Imports everything. If you're importing anything, this is probably what you want.

:query

Imports the functions which generate query messages.

:reply

Imports the functions which generate proper responses to query messages.

Functions

Note that all functions require a transaction ID. Please see the related section below. Queries also require a user generated node ID.

build_get_peers_reply( $tid, $nid, $values, $nodes, $token )

Generates an appropriate reply to a get_peers query.

build_get_peers_query( $tid, $nid, $info_hash )

Generates a get_peers packet. $info_hash is the infohash of the torrent you're seeking peers for.

If the queried node has peers for the infohash, they are returned in a key "values" as a list of strings. Each string containing "compact" format peer information for a single peer.

If the queried node has no peers for the infohash, a key "nodes" is returned containing the K nodes in the queried nodes routing table closest to the infohash supplied in the query. In either case a "token" key is also included in the return value. The token value is a required argument for a future announce_peer query. The token value should be a short binary string.

build_announce_peer_reply( $tid, $nid )

Generates a packet suitable for use as a response to an announce peer query.

build_announce_peer_query( $tid, $nid, $info_hash, $token, $port )

This packet announces that the peer controlling the querying node is downloading a torrent and is accepting peers for said torrent on a certain port. $info_hash contains the infohash of the torrent and $token is taken from the response to a previous get_peers query.

The queried node must verify that the token was previously sent to the same IP address as the querying node. Then the queried node should store the IP address of the querying node and the supplied port number under the infohash in its store of peer contact information.

build_ping_reply( $tid, $nid )

Generates the pong to a ping query.

build_ping_query( $tid, $nid )

Generates a simple ping packet.

build_find_node_reply( $tid, $nid, $nodes )

A find node reply contains a string which is a compacted list of the K (8) good $nodes nearest to the target from the routing table.

build_find_node_query( $tid, $nid, $target )

Find node is used to find the contact information for a node given its ID. $target contains the ID of the node sought by the queryer.

build_error_reply( $tid, $error )

Generates an error packet. An error may be sent in reply to any query. $error is a list ref. The first element is an integer representing the error code. The second element is a string containing the error message which may or may not be suitable for display. Errors are sent when a query cannot be fulfilled. The following describes the possible error codes:

Code    Description
----------------------------------------------
201     Generic Error
202     Server Error
203     Protocol Error such as a malformed packet, invalid arguments, or
            a bad token
204     Method Unknown

Transaction IDs

Every message has a transaction ID which is created by the querying node and is echoed in the response so responses may be correlated with multiple queries to the same node. The transaction ID should be a short string of binary numbers, in general 2 characters are enough as they cover 2 ** 16 outstanding queries.

Node IDs

Each node has a globally unique identifier known as the "node ID." Node IDs are chosen at random from the same 160-bit space as BitTorrent infohashes. A "distance metric" is used to compare two node IDs or a node ID and an infohash for "closeness."

See Also

BEP 05: DHT Protocol

http://bittorrent.org/beps/bep_0005.html

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

License and Legal

Copyright (C) 2010-2012 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.