Notes on extension messages for adding magneturi

diff --git a/src/FuncTorrent/Peer.hs b/src/FuncTorrent/Peer.hs
index bf1153bd1063a7182e49f2d1ee2b641ae9ca63e9..87e7d23bff683a448beb8f644b8820601db10886 100644 (file)
--- a/src/FuncTorrent/Peer.hs
+++ b/src/FuncTorrent/Peer.hs
@@ -199,3 +199,76 @@ downloadPiece h index pieceLength = do
                                                   putStrLn $ "ignoring irrelevant msg: " ++ show msg
                                                   return empty)
 
+
+{-
+ -- Extension messages support (BEP-0010) --
+
+
+   In the regular peer handshake, adventise support for extension protocol. Protocol
+   extensions are done via the reserved bytes (8 of them) in the handshake message
+   as detailed in BEP-0003. For this particular "Extension Protocol" extension, we use
+   20th bit (counted from the right, from 0) is set to 1.
+
+   Once support for the extension protocol is established by the peer, the Peer is supposed
+   to support one message with the ID 20. This is sent like a regular message with 4-byte
+   length prefix and the msg id (20) in this case.
+
+   First byte of the payload of this message is either 0, which means it is a handshake
+   msg.
+
+   The rest of the payload is a dictionary with various keys. All of them are optional. The
+   one of interest at the moment for me is the one with key 'm' whose value is another
+   dictionary of all supported extensions.
+
+   Here is where it gets interesting for us (to support magneturi. When the torrent client
+   has only got a magneturi to look at, it has only got the list of trackers with it (we
+   are not looking at the DHT case for the time being). So, it somehow needs to get the info
+   dictionary. It gets this by talking to another peer in the network. To do that, the client
+   needs to talk tracker protocol, get the list of peers and talk to peers using the above
+   extension protocol to get the infodict as payload. Let us see how we can do that now.
+
+   If a peer already has the full infodict, then, the handshake message sent by that peer
+   is something like this:
+
+     {'m': {'ut_metadata', 3}, 'metadata_size': 31235}
+
+   Note that the 'metadata_size' is not part of the value of the key 'm'.
+   If we are a new client and are requesting the handshake to a peer, then we don't have
+   the infodict yet, in which case, we only send the first part:
+
+     {'m': {'ut_metadata', 3}}
+
+   This is bencoded and sent across the wire. The value "3" (integer) against the key
+   'ut_metadata" is an ordered integer within a client that identifies the extention.
+   No two extension supported by the same client shares the same value. If the value is
+   '0', then the extension is unsupported.
+
+   Here we use the BEP-0009, the metadata extension protocol. The metadata in this case
+   is the infodict. The infodict itself is divided into 16KB sized pieces.
+
+   Here is a possible interaction between two peers:
+
+   1. Peer Pn comes up, gets the ip/ports of other peers, P0, P1.... Pn does not have the
+   size of the infodict. Pn has advertised itself as supporting the extension protocol.
+   It sends the handshake msg to other peers with this bit on in the reserved bytes.
+   2. Let us say, P1 replied with a handshake. We check if it also supports the extension
+   mechanism.
+   3. Now we get into the extension message passing so that we have the info dict.
+   To do that, we send the extension handshake (ut_metadata) m dict without the
+   metadata_size. We get back the extension handshake with metadata_size. We take
+   note of the size.
+   4. We calculate the number of 16384 chunks in the total size of the metadata. That
+   gives us the number of pieces the metadata has.
+   5. We send a "request" extension msg:
+     {'msg_type': 0, 'piece': 0}
+   6. We recieve the "data" message.
+     {'msg_type': 1, 'piece': 0, 'total_size': 3425} in bencoded format, followed by
+     total_size bytes. total_size is 16KiB except perhaps for the last piece.
+   7. If the peer does not have the requested piece, it sends the "reject" message.
+     {'msg_type': 2, 'piece': 0}
+   8. Repeat 5, 6/7 for every piece.
+
+   At this point, we have the infodict.
+
+-)
+