File Coverage

blib/lib/Net/BitTorrent/Protocol/BEP05.pm
Criterion Covered Total %
statement 15 33 45.4
branch 0 4 0.0
condition n/a
subroutine 5 14 35.7
pod 9 9 100.0
total 29 60 48.3


line stmt bran cond sub pod time code
1             package Net::BitTorrent::Protocol::BEP05;
2 1     1   3 use strict;
  1         2  
  1         21  
3 1     1   3 use warnings;
  1         0  
  1         31  
4             our $VERSION = "1.5.2";
5 1     1   2 use Net::BitTorrent::Protocol::BEP03::Bencode qw[bencode];
  1         9  
  1         38  
6 1     1   3 use vars qw[@EXPORT_OK %EXPORT_TAGS];
  1         1  
  1         30  
7 1     1   3 use Exporter qw[];
  1         1  
  1         583  
8             *import = *import = *Exporter::import;
9             %EXPORT_TAGS = (
10             build => [
11             qw[build_get_peers_query build_get_peers_reply
12             build_announce_peer_query build_announce_peer_reply
13             build_ping_query build_ping_reply build_find_node_query
14             build_find_node_reply build_error_reply]
15             ],
16             parse => [qw[ ]], # XXX - None yet
17             query => [
18             qw[build_get_peers_query build_announce_peer_query build_ping_query
19             build_find_node_query]
20             ],
21             reply => [
22             qw[build_get_peers_reply build_announce_peer_reply build_ping_reply
23             build_find_node_reply build_error_reply]
24             ]
25             );
26             @EXPORT_OK = sort map { @$_ = sort @$_; @$_ } values %EXPORT_TAGS;
27             $EXPORT_TAGS{'all'} = \@EXPORT_OK;
28              
29             # Node ID and version
30             our $v = 'NB' . pack 'C2', $VERSION =~ m[\.(\d+)]g;
31              
32             #
33             sub build_ping_query ($$) {
34 0     0 1   my ($tid, $nid) = @_;
35             return
36 0           bencode({t => $tid,
37             y => 'q',
38             q => 'ping',
39             a => {id => $nid},
40             v => $v
41             }
42             );
43             }
44              
45             sub build_announce_peer_query ($$$$$) {
46 0     0 1   my ($tid, $nid, $info_hash, $token, $port) = @_;
47             return
48 0           bencode({t => $tid,
49             y => 'q',
50             q => 'announce_peer',
51             a => {id => $nid,
52             port => $port,
53             info_hash => $info_hash,
54             token => $token
55             },
56             v => $v
57             }
58             );
59             }
60              
61             sub build_find_node_query ($$$) {
62 0     0 1   my ($tid, $nid, $target) = @_;
63             return
64 0           bencode({t => $tid,
65             y => 'q',
66             q => 'find_node',
67             a => {id => $nid,
68             target => $target
69             },
70             v => $v
71             }
72             );
73             }
74              
75             sub build_get_peers_query ($$$) {
76 0     0 1   my ($tid, $nid, $info_hash) = @_;
77             return
78 0           bencode({t => $tid,
79             y => 'q',
80             q => 'get_peers',
81             a => {id => $nid, info_hash => $info_hash},
82             v => $v
83             }
84             );
85             }
86              
87             sub build_ping_reply ($$) {
88 0     0 1   my ($tid, $nid) = @_;
89 0           return bencode({t => $tid, y => 'r', r => {id => $nid}, v => $v});
90             }
91              
92             sub build_announce_peer_reply ($$) {
93 0     0 1   my ($tid, $nid) = @_;
94 0           return bencode({t => $tid, y => 'r', r => {id => $nid}, v => $v});
95             }
96              
97             sub build_find_node_reply ($$$) {
98 0     0 1   my ($tid, $nid, $nodes) = @_;
99             return
100 0           bencode({t => $tid,
101             y => 'r',
102             r => {id => $nid, nodes => $nodes},
103             v => $v
104             }
105             );
106             }
107              
108             sub build_get_peers_reply ($$$$$) {
109 0     0 1   my ($tid, $nid, $values, $nodes, $token) = @_;
110             return
111 0 0         bencode({t => $tid,
    0          
112             y => 'r',
113             r => {id => $nid,
114             token => $token,
115             (@$values ? (values => $values) : ()),
116             ($nodes ? (nodes => $nodes) : ())
117             },
118             v => $v
119             }
120             );
121             }
122              
123             sub build_error_reply ($@) {
124 0     0 1   my ($tid, $error) = @_;
125             return
126 0           bencode({t => $tid,
127             y => 'e',
128             e => $error,
129             v => $v
130             }
131             );
132             }
133             1;
134              
135             =pod
136              
137             =head1 NAME
138              
139             Net::BitTorrent::Protocol::BEP05 - Packet Utilities for BEP05: The DHT Protocol
140              
141             =head1 Description
142              
143             BitTorrent uses a "distributed sloppy hash table" (DHT) for storing peer
144             contact information for "trackerless" torrents. In effect, each peer becomes a
145             tracker. The protocol is based on Kademila and is implemented over UDP. This
146             module provides packet building functions for this protocol.
147              
148             =head1 Importing From Net::BitTorrent::Protocol::BEP05
149              
150             By default, nothing is exported.
151              
152             You may import any of the following or use one or more of these tag:
153              
154             =over
155              
156             =item C<:all>
157              
158             Imports everything. If you're importing anything, this is probably what you
159             want.
160              
161             =item C<:query>
162              
163             Imports the functions which generate query messages.
164              
165             =item C<:reply>
166              
167             Imports the functions which generate proper responses to query messages.
168              
169             =back
170              
171             =head1 Functions
172              
173             Note that all functions require a transaction ID. Please see the
174             L below. Queries also require a user
175             generated L.
176              
177             =over
178              
179             =item C
180              
181             Generates an appropriate reply to a
182             L.
183              
184             =item C
185              
186             Generates a C packet. C<$info_hash> is the infohash of the torrent
187             you're seeking peers for.
188              
189             If the queried node has peers for the infohash, they are returned in a key
190             "values" as a list of strings. Each string containing "compact" format peer
191             information for a single peer.
192              
193             If the queried node has no peers for the infohash, a key "nodes" is returned
194             containing the K nodes in the queried nodes routing table closest to the
195             infohash supplied in the query. In either case a "token" key is also included
196             in the return value. The token value is a required argument for a future
197             L.
198             The token value should be a short binary string.
199              
200             =item C
201              
202             Generates a packet suitable for use as a response to an
203             L.
204              
205             =item C
206              
207             This packet announces that the peer controlling the querying node is
208             downloading a torrent and is accepting peers for said torrent on a certain
209             port. C<$info_hash> contains the infohash of the torrent and C<$token> is
210             taken from the response to a previous
211             L.
212              
213             The queried node must verify that the token was previously sent to the same IP
214             address as the querying node. Then the queried node should store the IP
215             address of the querying node and the supplied port number under the infohash
216             in its store of peer contact information.
217              
218             =item C
219              
220             Generates the pong to a L.
221              
222             =item C
223              
224             Generates a simple ping packet.
225              
226             =item C
227              
228             A find node reply contains a string which is a compacted list of the K (8)
229             good C<$nodes> nearest to the target from the routing table.
230              
231             =item C
232              
233             Find node is used to find the contact information for a node given its ID.
234             C<$target> contains the ID of the node sought by the queryer.
235              
236             =item C
237              
238             Generates an error packet. An error may be sent in reply to any query.
239             C<$error> is a list ref. The first element is an integer representing the
240             error code. The second element is a string containing the error message which
241             may or may not be suitable for display. Errors are sent when a query cannot be
242             fulfilled. The following describes the possible error codes:
243              
244             Code Description
245             ----------------------------------------------
246             201 Generic Error
247             202 Server Error
248             203 Protocol Error such as a malformed packet, invalid arguments, or
249             a bad token
250             204 Method Unknown
251              
252             =back
253              
254             =head1 Transaction IDs
255              
256             Every message has a transaction ID which is created by the querying node and
257             is echoed in the response so responses may be correlated with multiple queries
258             to the same node. The transaction ID should be a short string of binary
259             numbers, in general 2 characters are enough as they cover C<2 ** 16>
260             outstanding queries.
261              
262             =head1 Node IDs
263              
264             Each node has a globally unique identifier known as the "node ID." Node IDs
265             are chosen at random from the same 160-bit space as BitTorrent infohashes. A
266             "distance metric" is used to compare two node IDs or a node ID and an infohash
267             for "closeness."
268              
269             =head1 See Also
270              
271             =over
272              
273             =item BEP 05: DHT Protocol
274              
275             http://bittorrent.org/beps/bep_0005.html
276              
277             =back
278              
279             =head1 Author
280              
281             Sanko Robinson - http://sankorobinson.com/
282              
283             CPAN ID: SANKO
284              
285             =head1 License and Legal
286              
287             Copyright (C) 2010-2012 by Sanko Robinson
288              
289             This program is free software; you can redistribute it and/or modify it under
290             the terms of
291             L.
292             See the F file included with this distribution or
293             L
294             for clarification.
295              
296             When separated from the distribution, all original POD documentation is
297             covered by the
298             L.
299             See the
300             L.
301              
302             Neither this module nor the L is affiliated with BitTorrent,
303             Inc.
304              
305             =cut