Fixed one possible bug in the DHT and added a basic TODO list.

Fixed a possible segfault which could have been cause by handling an
empty packet.

1 files changed, 87 insertions, 0 deletions

diff --git a/docs/DHT.txt b/docs/DHT.txt
new file mode 100644
index 00000000..486aa38c
--- /dev/null
+++ b/docs/DHT.txt
@@ -0,0 +1,87 @@
+DHT protocol:
+        Follows pretty much the principle of the torrent DHT: http://www.bittorrent.org/beps/bep_0005.html (READ IT)
+    
+        But:
+            Vastly simplified packet format.
+            
+        Boostrapping:
+            The first time you install the client we bootstrap it with a node on our servers.(bandwidth should not be a problem as the client only needs to be sent one reply.)
+        
+    
+        Basics (All the numbers here are just guesses and are probably not optimal values):
+        
+            client list: A list of node ids closest (mathematically see bittorrent doc) to ours matched with ip addresses + port number corresponding to that id and a timestamp containing the time or time since the client was successfully pinged.
+            
+            "friends" list: A list containing the node_ids of all our "friends" or clients we want to connect to.
+                            Also contains the ip addresses + port + node_ids + timestamp(of last ping like in the client list) of the 8 clients closest (mathematically see bittorrent doc) to each "friend"
+                            
+            Two pinged lists: 
+                -One for storing a list of ips along with their ping_ids and a timestamp for the ping requests
+                -One for storing a list of ips along with their ping_ids and a timestamp for the get nodes requests
+                Entries in the pinged lists expire after 5 seconds.
+                If one of the lists becomes full, the expire rate reduces itself one second or the new ping takes the place of the oldest one.
+           
+      
+            Entries in client list and "friends" list expire after 300 seconds without ping response.
+            Each client stores a maximum of 32 entries in its client list.
+            Each client in the client list and "friends" list is pinged every 60 seconds.
+            Each client in the client list and "friends" list has a timestamp which denote the last time it was successfully pinged.
+            If the corresponding clients timestamp is more than 130 seconds old it is considered bad.
+            Send a get nodes request every 20 seconds to a random good node for each "friend" in our "friends" list.
+            Send a get nodes request every 20 seconds to a random good node in the client list.
+    
+    
+            When a client receives any request from another:
+              -Respond to the request
+                  -Ping request is replied to with with a ping response containing the same ping_id
+                  -Get nodes request is replied with a send nodes reply containing the same ping_id and the good nodes from the client list and/or the "friends" list that are closest to the requested_node_id
+    
+              -If the requesting client is not in the client list:
+                -If there are no bad clients in the list and the list is full:
+                        -If the id of the other client is closer (mathematically see bittorrent doc) than at least one of the clients in the list or our "friends" list:
+                            -Send a ping request to the client.
+                        -if not forget about the client.
+    
+                -If there are bad clients and/or the list isn't full:
+                        -Send a ping request to the client 
+    
+            When a client receives a response:
+                -Ping response
+                    -If the node was previously pinged with a matching ping_id (check in the corresponding pinged list.)
+                        -If the node is in the client list the matching client's timestamp is set to current time.
+                        -If the node is in the "friends" list the matching client's timestamp is set to current time for every occurrence.
+                        -If the node is not in the client list:
+                            -If the list isn't full, add it to the list.
+                            -If the list is full, the furthest away (mathematically see bittorrent doc) bad client is replaced by the new one.
+                            -If the list is filled with good nodes replace the furthest client with it only if it is closer than the replaced node.
+                        -for each friend in the "friends" list:
+                            -If that friend's client list isn't full, add that client to it
+                            -If that friend's client list contains bad clients, replace the furthest one with that client.
+                            -If that friend's client list contains only good clients
+                                -If the client is closer to the friend than one of the other clients, it replaces the farthest one
+                                -If not, nothing happens.
+                            
+                -Send nodes
+                    -If the ping_id matches what we sent previously (check in the corresponding pinged list.):
+                        -Each node in the response is pinged.
+              
+    
+            
+            
+    
+        Protocol:
+    
+            Node format: [char array (node_id), length=32 bytes][ip (in network byte order), length=4 bytes][port (in network byte order), length=2 bytes][Padding , length=2 bytes]
+    
+            Valid queries and Responses:
+    
+                Ping(Request and response): [byte with value: 00 for request, 01 for response][random 4 byte (ping_id)][char array (client node_id), length=32 bytes]
+                    ping_id = a random integer, the response must contain the exact same number as the request
+    
+    
+                Get nodes (Request):
+                Packet contents: [byte with value: 02][random 4 byte (ping_id)][char array (client node_id), length=32 bytes][char array: requested_node_id (node_id of which we want the ip), length=32 bytes]
+                Valid replies: a send_nodes packet
+    
+                Send_nodes (response): [byte with value: 03][random 4 byte (ping_id)][char array  (client node_id), length=32 bytes][Nodes in node format, length=40 * (number of nodes (maximum of 8 nodes)) bytes]
+                ex: 03[Node][Node][Node] 
\ No newline at end of file