| 1 | metadata extension |
|---|
| 2 | ================== |
|---|
| 3 | |
|---|
| 4 | The purpose of this extension is to allow clients to join a swarm and |
|---|
| 5 | complete a download without the need of downloading a .torrent file |
|---|
| 6 | first. This extension instead allows clients to download the metadata |
|---|
| 7 | from peers. It makes it possible to support *magnet links*, a link |
|---|
| 8 | on a web page only containing enough information to join the swarm |
|---|
| 9 | (the info hash). |
|---|
| 10 | |
|---|
| 11 | metadata |
|---|
| 12 | -------- |
|---|
| 13 | |
|---|
| 14 | This extension only transfers the info-dictionary part of the .torrent |
|---|
| 15 | file. This part can be validated by the info-hash. In this document, that |
|---|
| 16 | part of the .torrent file is referred to as *the metadata*. |
|---|
| 17 | |
|---|
| 18 | The metadata is plit up in 16kiB pieces. The pieces are indexed starting |
|---|
| 19 | from 0 for the first 16kiB of metadata. |
|---|
| 20 | |
|---|
| 21 | extension header |
|---|
| 22 | ---------------- |
|---|
| 23 | |
|---|
| 24 | The metadata extension uses the `extension protocol`_ to advertize its |
|---|
| 25 | existence. It adds the "ut_metadata" entry to the "m" dictionary in the |
|---|
| 26 | extension header hand-shake message. This identifies the message code |
|---|
| 27 | used for this message. It also adds "metadata_size" to the handshake |
|---|
| 28 | message (not the "m" dictionary) specifying an integer value of the |
|---|
| 29 | number of bytes of the metadata. |
|---|
| 30 | |
|---|
| 31 | .. _`extension protocol`: extension_protocol.html |
|---|
| 32 | |
|---|
| 33 | Example extension handshake message:: |
|---|
| 34 | |
|---|
| 35 | {'m': {'ut_metadata', 3}, 'metadata_size': 31235} |
|---|
| 36 | |
|---|
| 37 | |
|---|
| 38 | extension message |
|---|
| 39 | ----------------- |
|---|
| 40 | |
|---|
| 41 | The extension messages are bencoded. There are 3 different kinds of messages: |
|---|
| 42 | |
|---|
| 43 | 0. request |
|---|
| 44 | 1. data |
|---|
| 45 | 2. reject |
|---|
| 46 | |
|---|
| 47 | The bencoded messages have a key "msg_type" which value is an integer |
|---|
| 48 | corresponding to the type of message. They also have a key "piece", which |
|---|
| 49 | indicates which part of the metadata this message refers to. |
|---|
| 50 | |
|---|
| 51 | request |
|---|
| 52 | ~~~~~~~ |
|---|
| 53 | |
|---|
| 54 | The ``request`` message does not have any additional keys in the dictionary. |
|---|
| 55 | The response to this message, from a peer supporting the extension, is either |
|---|
| 56 | a ``reject`` or a ``data`` message. The response MUST have the same ``piece`` |
|---|
| 57 | as the request did. |
|---|
| 58 | |
|---|
| 59 | A peer MUST verify that any piece it sends passes the info-hash verification. |
|---|
| 60 | i.e. until the peer has the entire metadata, it cannot run SHA-1 to verify that |
|---|
| 61 | it yields the same hash as the info-hash. Peers that do not have the entire |
|---|
| 62 | metadata MUST respond with a ``reject`` message to any metadata request. |
|---|
| 63 | |
|---|
| 64 | Example:: |
|---|
| 65 | |
|---|
| 66 | {'msg_type': 0, 'piece': 0} |
|---|
| 67 | d8:msg_typei0e5:piecei0ee |
|---|
| 68 | |
|---|
| 69 | That request message requests the first metadata piece. |
|---|
| 70 | |
|---|
| 71 | data |
|---|
| 72 | ~~~~ |
|---|
| 73 | |
|---|
| 74 | The ``data`` message adds another entry to the dictionary, "total_size". This |
|---|
| 75 | key has the same semantics as the "metadata_size" in the extension header. This |
|---|
| 76 | is an integer. |
|---|
| 77 | |
|---|
| 78 | The metadata piece is appended to the bencoded dictionary, it is not a part of |
|---|
| 79 | the dictionary, but it is a part of the message (the length prefix MUST include it). |
|---|
| 80 | |
|---|
| 81 | If the piece is the last piece of the metadata, it may be less than 16kiB. If it |
|---|
| 82 | is not the last piece of the metadata, it MUST be 16kiB. |
|---|
| 83 | |
|---|
| 84 | Example:: |
|---|
| 85 | |
|---|
| 86 | {'msg_type': 1, 'piece': 0, 'total_size': 3425} |
|---|
| 87 | d8:msg_typei1e5:piecei0e10:total_sizei34256eexxxxxxxx... |
|---|
| 88 | |
|---|
| 89 | The ``x`` represents binary data (the metadata). |
|---|
| 90 | |
|---|
| 91 | reject |
|---|
| 92 | ~~~~~~ |
|---|
| 93 | |
|---|
| 94 | The ``reject`` message does not have any additional keys in its message. |
|---|
| 95 | It SHOULD be interpreted as the peer does not have the piece of metadata |
|---|
| 96 | that was requested. |
|---|
| 97 | |
|---|
| 98 | Clients MAY implement flood protection by rejecting ``request`` messages |
|---|
| 99 | after a certain number of them have been served. Typically the number of |
|---|
| 100 | pieces of metadata times a factor. |
|---|
| 101 | |
|---|
| 102 | Example:: |
|---|
| 103 | |
|---|
| 104 | {'msg_type': 2, 'piece': 0} |
|---|
| 105 | d8:msg_typei1e5:piecei0ee |
|---|
| 106 | |
|---|
| 107 | magnet URI format |
|---|
| 108 | ----------------- |
|---|
| 109 | |
|---|
| 110 | The magnet URI format is:: |
|---|
| 111 | |
|---|
| 112 | magnet:?xt=urn:btih:<info-hash>&dn=<name>&tr=<tracker-url> |
|---|
| 113 | |
|---|
| 114 | <info-hash> |
|---|
| 115 | Is the info-hash encoded as base32. |
|---|
| 116 | |
|---|
| 117 | ``xt`` is the only mandatory parameter. ``dn`` is the display name that may be |
|---|
| 118 | used by the client to display while waiting for metadata. ``tr`` is a tracker |
|---|
| 119 | url, if there is one. If there are multiple trackers, multiple ``tr`` entries |
|---|
| 120 | may be included. |
|---|
| 121 | |
|---|
| 122 | Both ``dn`` and ``tr`` are optional. |
|---|
| 123 | |
|---|
| 124 | If no tracker is specified, the client SHOULD use the DHT to acquire peers. |
|---|
| 125 | |
|---|
| 126 | authors |
|---|
| 127 | ------- |
|---|
| 128 | |
|---|
| 129 | | `Greg Hazel`__ |
|---|
| 130 | | `Arvid Norberg`__ |
|---|
| 131 | |
|---|
| 132 | .. __: mailto:greg@bittorrent.com |
|---|
| 133 | .. __: mailto:arvid@bittorrent.com |
|---|
