| 1 | BEP: 23 |
|---|
| 2 | Title: Tracker Returns Compact Peer Lists |
|---|
| 3 | Version: $Revision$ |
|---|
| 4 | Last-Modified: $Date$ |
|---|
| 5 | Author: David Harrison <dave@bittorrent.com> |
|---|
| 6 | Status: Accepted |
|---|
| 7 | Type: Standards track |
|---|
| 8 | Content-Type: text/x-rst |
|---|
| 9 | Created: 12-May-2008 |
|---|
| 10 | Post-History: |
|---|
| 11 | |
|---|
| 12 | |
|---|
| 13 | Abstract |
|---|
| 14 | ======== |
|---|
| 15 | |
|---|
| 16 | To reduce the size of tracker responses and to reduce memory and |
|---|
| 17 | computational requirements in trackers, trackers may return |
|---|
| 18 | peers as a packed string rather than as a bencoded list. |
|---|
| 19 | |
|---|
| 20 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL |
|---|
| 21 | NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and |
|---|
| 22 | "OPTIONAL" in this document are to be interpreted as described in |
|---|
| 23 | IETF RFC 2119 [#RFC-2119]_. |
|---|
| 24 | |
|---|
| 25 | |
|---|
| 26 | Overview |
|---|
| 27 | ======== |
|---|
| 28 | |
|---|
| 29 | In BitTorrent as described in BEP 3 [#BEP-3]_, peers wishing to |
|---|
| 30 | transfer a file contact a central tracker. This tracker returns a |
|---|
| 31 | list of peers that are currently transferring the file. The list of |
|---|
| 32 | peers is implemented as a list of bencoded dicts. Each dict in the |
|---|
| 33 | list contains three fields: *peer id*, *ip*, and *port*. The *peer |
|---|
| 34 | id* is 20 bytes plus 3 bytes bencoding overhead. The *ip* is a string |
|---|
| 35 | containing a domain name or an IP address, and an integer port number. |
|---|
| 36 | The *ip* is variable length, but since in its longest form it is a |
|---|
| 37 | domain name it cannot exceed 255 bytes [#RFC-1034]_ plus 4 bytes |
|---|
| 38 | bencoding overhead. Bencoded integers are also variable length but |
|---|
| 39 | since it is a port number, it cannot be more than 7 bytes including |
|---|
| 40 | bencoding overhead. Thus, |
|---|
| 41 | |
|---|
| 42 | :: |
|---|
| 43 | |
|---|
| 44 | total peer list length in bytes < n * ( 23 + 259 + 7 ) |
|---|
| 45 | |
|---|
| 46 | It is common now to use a compact format where each peer is represented |
|---|
| 47 | using only 6 bytes. The first 4 bytes contain the 32-bit ipv4 address. |
|---|
| 48 | The remaining two bytes contain the port number. Both address and port |
|---|
| 49 | use network-byte order. |
|---|
| 50 | |
|---|
| 51 | It is SUGGESTED that trackers return compact format by default. |
|---|
| 52 | By including *compact=0* in the announce URL, the client advises the |
|---|
| 53 | tracker that is prefers the original format described in [#BEP-3]_, and |
|---|
| 54 | analogously *compact=1* advises the tracker that the client prefers |
|---|
| 55 | compact format. However the *compact* key-value pair is only |
|---|
| 56 | advisory: the tracker MAY return using either format. *compact* is |
|---|
| 57 | advisory so that trackers may support only the compact format. |
|---|
| 58 | However, clients MUST continue to support both. |
|---|
| 59 | |
|---|
| 60 | For example, |
|---|
| 61 | |
|---|
| 62 | :: |
|---|
| 63 | |
|---|
| 64 | GET /announce?peer_id=aaaaaaaaaaaaaaaaaaaa&info_hash=aaaaaaaaaaaaaaaaaaaa |
|---|
| 65 | &port=6881&left=0&downloaded=100&uploaded=0&compact=1 |
|---|
| 66 | |
|---|
| 67 | The compact format uses the same *peers* key in the bencoded tracker |
|---|
| 68 | response, but the value is a bencoded string rather than a bencoded |
|---|
| 69 | list. |
|---|
| 70 | |
|---|
| 71 | The peer id does not appear in the compact format. The format has been |
|---|
| 72 | in use for years and the lack of a peer id has posed no problems. |
|---|
| 73 | |
|---|
| 74 | This compact format is supported by BitTorrent mainline, Azureus, |
|---|
| 75 | libtorrent, uTorrent, and probably most other clients. |
|---|
| 76 | |
|---|
| 77 | |
|---|
| 78 | References |
|---|
| 79 | ========== |
|---|
| 80 | |
|---|
| 81 | .. [#BEP-3] BEP_0003. The BitTorrent Protocol Specification. Cohen. |
|---|
| 82 | (http://www.bittorrent.org/beps/bep_0003.html) |
|---|
| 83 | |
|---|
| 84 | .. [#RFC-1034] RFC-1034. DOMAIN NAMES - CONCEPTS AND FACILITIES. Mockapetris, |
|---|
| 85 | November 1987. (http://tools.ietf.org/html/rfc1034) |
|---|
| 86 | |
|---|
| 87 | .. [#RFC-2119] RFC-2119. (http://www.ietf.org/rfc/rfc2119.txt) |
|---|
| 88 | |
|---|
| 89 | |
|---|
| 90 | Copyright |
|---|
| 91 | ========= |
|---|
| 92 | |
|---|
| 93 | This document has been placed in the public domain. |
|---|
| 94 | |
|---|
| 95 | |
|---|
| 96 | |
|---|
| 97 | .. |
|---|
| 98 | Local Variables: |
|---|
| 99 | mode: indented-text |
|---|
| 100 | indent-tabs-mode: nil |
|---|
| 101 | sentence-end-double-space: t |
|---|
| 102 | fill-column: 70 |
|---|
| 103 | coding: utf-8 |
|---|
| 104 | End: |
|---|
| 105 | |
|---|
