Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Adding pod versions of BEP12 and BEP15 to repo and dist

  • Loading branch information...
commit b927142f087cb2b980da0676813bd8ceb1580130 1 parent 3ff0077
@sanko authored
View
2  MANIFEST
@@ -32,7 +32,9 @@ lib/Net/BitTorrent/Protocol/BEP05/RoutingTable.pm
lib/Net/BitTorrent/Protocol/BEP05/Tracker.pm
lib/Net/BitTorrent/Protocol/BEP07.pod
lib/Net/BitTorrent/Protocol/BEP07/Compact.pm
+lib/Net/BitTorrent/Protocol/BEP12.pod
lib/Net/BitTorrent/Protocol/BEP12/MultiTracker.pm
+lib/Net/BitTorrent/Protocol/BEP15.pod
lib/Net/BitTorrent/Protocol/BEP15/Tracker/UDP.pm
lib/Net/BitTorrent/Protocol/BEP23.pod
lib/Net/BitTorrent/Protocol/BEP23/Compact.pm
View
65 lib/Net/BitTorrent/Protocol/BEP12.pod
@@ -0,0 +1,65 @@
+=pod
+
+=head1 NAME
+
+Net::BitTorrent::Protocol::BEP12 - Multitracker Metadata Extension
+
+=begin header
+
+BEP: 12
+Title: Multitracker Metadata Extension
+Version: $Rev$
+Last-Modified: $Date$
+Author: John Hoffman <theshadow@degreez.net>
+Status: Draft
+Type: Standards Track
+Created: 07-Feb-2008
+Post-History:
+
+=end header
+
+=head1 Metadata Extension
+
+In addition to the standard "announce" key, in the main area of the metadata
+file and not part of the "info" section, will be a new key, "announce-list".
+This key will refer to a list of lists of URLs, and will contain a list of
+tiers of announces. If the client is compatible with the multitracker
+specification, and if the "announce-list" key is present, the client will
+ignore the "announce" key and only use the URLs in "announce-list".
+
+=head1 Order of Processing
+
+The tiers of announces will be processed sequentially; all URLs in each tier
+must be checked before the client goes on to the next tier. URLs within each
+tier will be processed in a randomly chosen order; in other words, the list
+will be shuffled when first read, and then parsed in order. In addition, if a
+connection with a tracker is successful, it will be moved to the front of the
+tier.
+
+=head2 Examples:
+
+ d['announce-list'] = [ [tracker1], [backup1], [backup2] ]
+
+On each announce, first try tracker1, then if that cannot be reached, try
+backup1 and backup2 respectively. On the next announce, repeat in the same
+order. This is meant for when the trackers are standard and can not share
+information.
+
+ d['announce-list'] = [[ tracker1, tracker2, tracker3 ]]
+
+First, shuffle the list. (For argument's sake, we'll say the list has already
+been shuffled.) Then, if tracker1 cannot be reached, try tracker2. If
+tracker2 can be reached, the list is now: tracker2,tracker1,tracker3. From
+then on, this will be the order the client tries. If later neither tracker2
+nor tracker1 can be reached, but tracker3 responds, then the list will be
+changed to: tracker3,tracker2,tracker1, and will be tried in that order in the
+future. This form is meant for trackers which can trade peer information and
+will cause the clients to help balance the load between the trackers.
+
+ d['announce-list'] = [ [ tracker1, tracker2 ], [backup1] ]
+
+The first tier, consisting of tracker1 and tracker2, is shuffled. Both
+trackers 1 and 2 will be tried on each announce (though perhaps in varying
+order) before the client tries to reach backup1.
+
+=cut
View
316 lib/Net/BitTorrent/Protocol/BEP15.pod
@@ -0,0 +1,316 @@
+=pod
+
+=head1 NAME
+
+Net::BitTorrent::Protocol::BEP15 - UDP Tracker Protocol for BitTorrent
+
+=begin header
+
+BEP: 15
+Title: UDP Tracker Protocol for BitTorrent
+Version: $Rev$
+Last-Modified: $Date$
+Author: Olaf van der Spek <olafvdspek@gmail.com>
+Status: Draft
+Type: Standards Track
+Created: 13-Feb-2008
+Post-History:
+
+=end header
+
+=head1 Introduction
+
+To discover other peers in a swarm a client announces it's existance to a
+tracker. The HTTP protocol is used and a typical request contains the
+following parameters: info_hash, key, peer_id, port, downloaded, left,
+uploaded and compact. A response contains a list of peers (host and port) and
+some other information. The request and response are both quite short. Since
+TCP is used, a connection has to be opened and closed, introducing additional
+overhead.
+
+=head1 Overhead
+
+Using HTTP introduces significant overhead. There's overhead at the ethernet
+layer (14 bytes per packet), at the IP layer (20 bytes per packet), at the TCP
+layer (20 bytes per packet) and at the HTTP layer. About 10 packets are used
+for a request plus response containing 50 peers and the total number of bytes
+used is about L<1206|http://xbtt.sourceforge.net/udp_tracker_protocol.html>.
+This overhead can be reduced significantly by using a UDP based protocol. The
+protocol proposed here uses 4 packets and about 618 bytes, reducing traffic by
+50%. For a client, saving 1 kbyte every hour isn't significant, but for a
+tracker serving a million peers, reducing traffic by 50% matters a lot. An
+additional advantage is that a UDP based binary protocol doesn't require a
+complex parser and no connection handling, reducing the complexity of tracker
+code and increasing it's performance.
+
+=head1 UDP connections / spoofing
+
+In the ideal case, only 2 packets would be necessary. However, it is possible
+to spoof the source address of a UDP packet. The tracker has to ensure this
+doesn't occur, so it calculates a value (connection_id) and sends it to the
+client. If the client spoofed it's source address, it won't receive this
+value (unless it's sniffing the network). The connection_id will then be send
+to the tracker again in packet 3. The tracker verifies the connection_id and
+ignores the request if it doesn't match. Connection IDs should not be
+guessable by the client. This is comparable to a TCP handshake and a syn
+cookie like approach can be used to storing the connection IDs on the tracker
+side. A connection ID can be used for multiple requests. A client can use a
+connection ID until one minute after it has received it. Trackers should
+accept the connection ID until two minutes after it has been send.
+
+=head1 Time outs
+
+UDP is an 'unreliable' protocol. This means it doesn't retransmit lost packets
+itself. The application is responsible for this. If a response is not
+received after 15 * 2 ^ n seconds, the client should retransmit the request,
+where n starts at 0 and is increased up to 8 (3840 seconds) after every
+retransmission. Note that it is necessary to rerequest a connection ID when
+it has expired.
+
+=head1 Examples
+
+Normal announce::
+
+ t = 0: connect request
+ t = 1: connect response
+ t = 2: announce request
+ t = 3: annonce response
+
+Connect times out::
+
+ t = 0: connect request
+ t = 15: connect request
+ t = 45: connect request
+ t = 105: connect request
+ etc
+
+Announce times out::
+
+ t = 0:
+ t = 0: connect request
+ t = 1: connect response
+ t = 2: announce request
+ t = 17: announce request
+ t = 47: announce request
+ t = 107: connect request (because connection ID expired)
+ t = 227: connect request
+ etc
+
+Multiple requests::
+
+ t = 0: connect request
+ t = 1: connect response
+ t = 2: announce request
+ t = 3: annonce response
+ t = 4: announce request
+ t = 5: annonce response
+ t = 60: announce request
+ t = 61: annonce response
+ t = 62: connect request
+ t = 63: connect response
+ t = 64: announce request
+ t = 64: scrape request
+ t = 64: scrape request
+ t = 64: announce request
+ t = 65: announce response
+ t = 66: announce response
+ t = 67: scrape response
+ t = 68: scrape response
+
+=head1 UDP tracker protocol
+
+All values are send in network byte order (big endian). Do not expect
+packets to be exactly of a certain size. Future extensions could
+increase the size of packets.
+
+Before announcing or scraping, you have to obtain a connection ID.
+
+=over
+
+=item 1. Choose a random transaction ID.
+
+=item 2. Fill the connect request structure.
+
+=item 3. Send the packet.
+
+=back
+
+connect request::
+
+ Offset Size Name Value
+ 0 64-bit integer connection_id 0x41727101980
+ 8 32-bit integer action 0 // connect
+ 12 32-bit integer transaction_id
+ 16
+
+=over
+
+=item 1. Receive the packet.
+
+=item 2. Check whether the packet is at least 16 bytes.
+
+=item 3. Check whether the transaction ID is equal to the one you chose.
+
+=item 4. Check whether the action is connect.
+
+=item 5. Store the connection ID for future use.
+
+=back
+
+connect response::
+
+ Offset Size Name Value
+ 0 32-bit integer action 0 // connect
+ 4 32-bit integer transaction_id
+ 8 64-bit integer connection_id
+ 16
+
+=over
+
+=item 1. Choose a random transaction ID.
+
+=item 2. Fill the announce request structure.
+
+=item 3. Send the packet.
+
+=back
+
+announce request::
+
+ Offset Size Name Value
+ 0 64-bit integer connection_id
+ 8 32-bit integer action 1 // announce
+ 12 32-bit integer transaction_id
+ 16 20-byte string info_hash
+ 36 20-byte string peer_id
+ 56 64-bit integer downloaded
+ 64 64-bit integer left
+ 72 64-bit integer uploaded
+ 80 32-bit integer event 0 // 0: none; 1: completed; 2: started; 3: stopped
+ 84 32-bit integer IP address 0 // default
+ 88 32-bit integer key
+ 92 32-bit integer num_want -1 // default
+ 96 16-bit integer port
+ 98
+
+=over
+
+=item 1. Receive the packet.
+
+=item 2. Check whether the packet is at least 20 bytes.
+
+=item 3. Check whether the transaction ID is equal to the one you chose.
+
+=item 4. Check whether the action is announce.
+
+=item 5. Do not announce again until interval seconds have passed or an event
+has occurred.
+
+=back
+
+announce response::
+
+ Offset Size Name Value
+ 0 32-bit integer action 1 // announce
+ 4 32-bit integer transaction_id
+ 8 32-bit integer interval
+ 12 32-bit integer leechers
+ 16 32-bit integer seeders
+ 20 + 6 * n 32-bit integer IP address
+ 24 + 6 * n 16-bit integer TCP port
+ 20 + 6 * N
+
+Up to about 74 torrents can be scraped at once. A full scrape can't be done
+with this protocol.
+
+=over
+
+=item 1. Choose a random transaction ID.
+
+=item 2. Fill the scrape request structure.
+
+=item 3. Send the packet.
+
+=back
+
+scrape request::
+
+ Offset Size Name Value
+ 0 64-bit integer connection_id
+ 8 32-bit integer action 2 // scrape
+ 12 32-bit integer transaction_id
+ 16 + 20 * n 20-byte string info_hash
+ 16 + 20 * N
+
+=over
+
+=item 1. Receive the packet.
+
+=item 2. Check whether the packet is at least 8 bytes.
+
+=item 3. Check whether the transaction ID is equal to the one you chose.
+
+=item 4. Check whether the action is scrape.
+
+=back
+
+scrape response::
+
+ Offset Size Name Value
+ 0 32-bit integer action 2 // scrape
+ 4 32-bit integer transaction_id
+ 8 + 12 * n 32-bit integer seeders
+ 12 + 12 * n 32-bit integer completed
+ 16 + 12 * n 32-bit integer leechers
+ 8 + 12 * N
+
+If the tracker encounters an error, it might send an error packet.
+
+=over
+
+=item 1. Receive the packet.
+
+=item 2. Check whether the packet is at least 8 bytes.
+
+=item 3. Check whether the transaction ID is equal to the one you chose.
+
+=back
+
+error response::
+
+ Offset Size Name Value
+ 0 32-bit integer action 3 // error
+ 4 32-bit integer transaction_id
+ 8 string message
+
+=head1 Existing implementations
+
+Azureus,
+L<libtorrent|http://www.rasterbar.com/products/libtorrent/udp_tracker_protocol.html>,
+L<opentracker|http://opentracker.blog.h3q.com/>, XBT Client and XBT Tracker
+support this protocol.
+
+=head1 IPv6
+
+IPv6 is not supported at the moment. A simple way to support IPv6 would be to
+increase the size of all IP addresses to 128 bits when the request is done
+over IPv6. However, I think more experience with IPv6 and discussion is
+needed before including it.
+
+=head1 Extensions
+
+Extension bits or a version field are not included. Clients and trackers
+should not assume packets to be of a certain size. This way, additional fields
+can be added without breaking compatibility.
+
+=head1 References and Footnotes
+
+=over
+
+=item 1. http://xbtt.sourceforge.net/udp_tracker_protocol.html
+
+=item 2. http://www.rasterbar.com/products/libtorrent/udp_tracker_protocol.html
+
+=item 3. http://opentracker.blog.h3q.com/
+
+=cut
Please sign in to comment.
Something went wrong with that request. Please try again.