docs/overnet.txt

   1 The Overnet Protocol
   2 --------------------
   3
   4  The Overnet protocol is divided in two parts: localisation and download.
   5 Localisation using UDP messages, while download is done using TCP/IP. The
   6 download protocol is mainly the same as in edonkey, except that the
   7 Connect/ConnectReply messages miss the server:port fields (ie they are 6
   8 bytes shorter).
   9
  10  In this draft, I focus on the localisation part.
  11
  12 I Messages Format
  13 =================
  14
  15 1) General Format:
  16 ------------------
  17
  18 UDP messages start with two bytes:
  19 byte: 227          eDonkey general magic number for messages
  20 byte:              the opcode of the message
  21 char[]:            message args
  22
  23 2) Opcodes:
  24 -----------
  25
  26 10     OvernetConnect
  27 11     OvernetConnectReply
  28 12     OvernetPublicize
  29 13     OvernetPublicized
  30 14     OvernetSearch
  31 15     OvernetSearchReply
  32 16     OvernetGetSearchResults
  33 17     OvernetSearchResult
  34 18     OvernetNoResult
  35 19     OvernetPublish
  36 20     OvernetPublished
  37
  38 24     OvernetFirewallConnection
  39 25     OvernetFirewallConnectionACK
  40 26     OvernetFirewallConnectionNACK
  41 27     OvernetGetMyIP
  42 28     OvernetGetMyIPResult
  43 29     OvernetGetMyIPDone
  44
  45 33     OvernetPeerNotFound
  46
  47 3) Conventions:
  48 ---------------
  49
  50 int8: one byte
  51 int16: two bytes in little endian format
  52 int32: four bytes in little endian format
  53 ip: an int32, for eg 127.0.0.1 = 127 + 0 << 8 + 0 << 16 + 1 << 24
  54 md4: the 16 bytes md4 of the file/client
  55
  56 peer: an overnet peer in the following format:
  57   md4: the peer md4
  58   ip:  the peer ip
  59   int16: the peer port
  60   int8: the peer kind/uptime/last seen ?
  61
  62 tags:
  63   int32: <n> number of tags
  64   tag[n]: the array of tag (as in edonkey proto)
  65
  66 4) Messages args:
  67 -----------------
  68
  69  OvernetConnect:
  70  ---------------
  71 md4: client md4
  72 ip:  my client ip
  73 int16: my client port
  74 int8: my client kind/uptime ? 0 is ok
  75
  76  OvernetConnectReply:
  77  --------------------
  78 int16: <n> number of peers propagated in this message
  79 peer[n]: the peers propagated
  80
  81  OvernetPublicize:
  82  -----------------
  83 md4:
  84 ip:    ip
  85 int16: port
  86 int8:  kind
  87
  88  OvernetPublicized: no args
  89  ------------------
  90
  91  OvernetSearch:
  92  --------------
  93 int8: kind of search ?
  94 md4:  the hash you are looking for
  95
  96  OvernetSearchReply:
  97  -------------------
  98 md4: the hash you have asked for
  99 int8: <n> number of peers that could be interesting for you
 100 peer[n]: the better peers you should ask
 101
 102  OvernetGetSearchResults:
 103  ------------------------
 104 md4: the hash you are looking for
 105 kind: ?
 106 int16: min (the range of results you want)
 107 int16: max
 108
 109  OvernetSearchResult:
 110  --------------------
 111 md4: the hash you have asked for
 112 md4: the hash of the client/file of the result (depends if you look for
 113   a file description or for a localisation)
 114 tags: the tags describing the result
 115
 116  OvernetNoResult:
 117  ----------------
 118 md4: the hash you have asked for
 119
 120  OvernetPublish:
 121  ---------------
 122 md4:
 123 md4:
 124 tags:
 125
 126  OvernetPublished:
 127  -----------------
 128 md4: the hash of the published file
 129
 130  OvernetGetMyIP:
 131  ---------------
 132 int8: 54
 133 int8: 18
 134
 135  OvernetGetMyIPResult:
 136  ---------------------
 137 ip: your ip
 138
 139  OvernetGetMyIPDone: no args
 140  -------------------
 141
 142  OvernetFirewallConnection:
 143  --------------------------
 144 md4: the md4 of the client you want to access
 145 int16: ?
 146
 147  OvernetFirewallConnectionACK:
 148  -----------------------------
 149 md4:
 150
 151  OvernetFirewallConnectionNACK:
 152 md4:
 153
 154 II Client behavior:
 155 ===================
 156
 157 1) Basics:
 158 ----------
 159
 160 In Overnet, the description and localisation of files are stored on peers
 161 such that the peer hash is as close as possible to the file hash.
 162
 163 When a peer wants a file, it tries to ask the peers which have the
 164 closest hashs to the file it wants. These peers reply by sending the
 165 closest peers they know to the requested hash.
 166
 167 The distance between two hashs is computed using what Kademlia calls a
 168 Xor metric: a xor is computed between the two hashs, and the result
 169 hash represents the distance. Two distances are then compared by using
 170 a lexicographical order on their bytes (ie first bytes are compared, and
 171 if equal, the second bytes, and so on...)
 172
 173 For this to work, the client needs to maintain a small list of peers it
 174 knows, which are as spreaded as possible in the space of possible hashs.
 175
 176 2) Sequences:
 177 -------------
 178
 179 a) Establishing a "connection" with other peers (booting)
 180 ---------------------------------------------------------
 181
 182 Client                                      Peer
 183 ------------------------------------------------
 184
 185  1:    -------    OvernetConnect  ------>
 186
 187  2:    <-----    OvernetConnectReply ----
 188
 189 OK, the peer is connected, it can be added to the list of available peers
 190 for searches. The peers propagated in the reply can be used for new
 191 connections.
 192
 193 b) Searches
 194 -----------
 195 From the keywords search, remove all keywords of 1 or 2 chars.
 196 Then, hash each keyword separately, and start one search per hash. When you
 197 will get results, you will have to filter them so that all keywords are
 198 matched, the protocol won't do that for you.
 199
 200 The search works as follows. You need a set of peers to be searched for the
 201 hash. Typically, you take the peers with the hashes with the same first char
 202 as the one you search.
 203
 204  Then, periodically (every 5 seconds ?), you take some peers (2 ? with the
 205 closest hashes), and ask them for the hash:
 206
 207 Client                                      Peer
 208 ------------------------------------------------
 209
 210  1:    ---------    OvernetSearch  ------->
 211  1':   -------  OvernetGetSearchResults -->
 212
 213  2:    <-----    OvernetSearchReply -------
 214  2':   <-----   OvernetSearchResult  ------
 215  2'':  <-----     OvernetNoResult   -------
 216
 217 1: query for better peers to ask for the hash
 218 2: return new peers which should be queried for the hash
 219
 220 1': query the peer directly for the hash: do you know it ?
 221 2': yes, I know it, here are the files containing this keyword
 222      (or the clients sharing this file if you are looking for a file-hash)
 223 2'': no, I have no info, try someone else...
 224
 225 Now, when you have the results, you need to remember what you are
 226 searching for:
 227 1) keywords: results are file descriptions, closed to edonkey ones
 228    (here, maybe some tags are different :)))
 229 2) files: you should look in the tags for one called "loc". It contains
 230    a string with the format "bcp://ip:port" or "bcp://????:ip:port"
 231     containing the source ip and port in ascii.
 232
 233 Now, you just need to connect and download ...
 234
 235
 236
 237