src/dht/dht.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001, 2002, 2003, 2004, 2009 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  * @author Nathan Evans
  24  * @file dht/dht.h
  25  */
  26
  27 #ifndef DHT_H_
  28 #define DHT_H_
  29
  30 #define DEBUG_DHT GNUNET_YES
  31
  32 /**
  33  * Needs to be GNUNET_YES for logging to dhtlog to work!
  34  */
  35 #define DEBUG_DHT_ROUTING GNUNET_YES
  36
  37 /**
  38  * FIXME: document.
  39  */
  40 #define DHT_BLOOM_SIZE 128
  41
  42 /**
  43  * FIXME: document.
  44  */
  45 #define DHT_BLOOM_K 6
  46
  47 /**
  48  * How many requests to remember for forwarding responses.
  49  */
  50 #define MAX_OUTSTANDING_FORWARDS 100
  51
  52 /**
  53  * How long to remember requests so we can forward responses.
  54  */
  55 #define DHT_FORWARD_TIMEOUT GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MINUTES, 5)
  56
  57 /**
  58  * Priority for routing results from other peers through
  59  * the DHT.
  60  */
  61 #define DHT_SEND_PRIORITY 4
  62
  63
  64 #define STAT_ROUTES "# DHT ROUTE Requests Seen"
  65 #define STAT_ROUTE_FORWARDS "# DHT ROUTE Requests Forwarded"
  66 #define STAT_ROUTE_FORWARDS_CLOSEST "# DHT ROUTE Requests Forwarded to Closest Known Peer"
  67 #define STAT_RESULTS "# DHT ROUTE RESULT Requests Seen"
  68 #define STAT_RESULTS_TO_CLIENT "# DHT ROUTE RESULT Sent to Client"
  69 #define STAT_RESULT_FORWARDS "# DHT ROUTE RESULT Requests Forwarded"
  70 #define STAT_GETS "# DHT GET Requests Handled"
  71 #define STAT_PUTS "# DHT PUT Requests Handled"
  72 #define STAT_PUTS_INSERTED "# DHT PUT Data Inserts"
  73 #define STAT_FIND_PEER "# DHT FIND_PEER Requests Handled"
  74 #define STAT_FIND_PEER_START "# DHT FIND_PEER Requests Initiated"
  75 #define STAT_GET_START "# DHT GET Requests Initiated"
  76 #define STAT_PUT_START "# DHT PUT Requests Initiated"
  77 #define STAT_FIND_PEER_REPLY "# DHT FIND_PEER Responses Received"
  78 #define STAT_GET_REPLY "# DHT GET Responses Received"
  79 #define STAT_FIND_PEER_ANSWER "# DHT FIND_PEER Responses Initiated"
  80 #define STAT_BLOOM_FIND_PEER "# DHT FIND_PEER Responses Ignored (bloom match)"
  81 #define STAT_GET_RESPONSE_START "# DHT GET Responses Initiated"
  82 #define STAT_HELLOS_PROVIDED "# HELLO Messages given to transport"
  83 #define STAT_DISCONNECTS "# Disconnects received"
  84 #define STAT_DUPLICATE_UID "# Duplicate UID's encountered (bad if any!)"
  85 #define STAT_RECENT_SEEN "# recent requests seen again (routing loops, alternate paths)"
  86
  87
  88 /**
  89  * FIXME: document.
  90  */
  91 typedef void (*GNUNET_DHT_MessageReceivedHandler) (void *cls,
  92                                                    const struct GNUNET_MessageHeader
  93                                                    *msg);
  94
  95
  96 /**
  97  * FIXME: document.
  98  */
  99 struct GNUNET_DHT_ControlMessage
 100 {
 101   /**
 102    * Type: GNUNET_MESSAGE_TYPE_DHT_CONTROL
 103    */
 104   struct GNUNET_MessageHeader header;
 105
 106   /**
 107    * Command code of the message.
 108    */
 109   uint16_t command;
 110
 111   /**
 112    * Variable parameter for the command.
 113    */
 114   uint16_t variable;
 115 };
 116
 117
 118 /**
 119  * Message which indicates the DHT should cancel outstanding
 120  * requests and discard any state.
 121  */
 122 struct GNUNET_DHT_StopMessage
 123 {
 124   /**
 125    * Type: GNUNET_MESSAGE_TYPE_DHT_STOP
 126    */
 127   struct GNUNET_MessageHeader header;
 128
 129   /**
 130    * Always zero.
 131    */
 132   uint32_t reserved GNUNET_PACKED;
 133
 134   /**
 135    * Unique ID identifying this request
 136    */
 137   uint64_t unique_id GNUNET_PACKED;
 138
 139   /**
 140    * Key of this request
 141    */
 142   GNUNET_HashCode key;
 143
 144 };
 145
 146
 147 /**
 148  * Generic DHT message, indicates that a route request
 149  * should be issued, if coming from a client.  Shared
 150  * usage for api->server and P2P message passing.
 151  */
 152 struct GNUNET_DHT_RouteMessage
 153 {
 154   /**
 155    * Type: GNUNET_MESSAGE_TYPE_DHT_LOCAL_ROUTE
 156    */
 157   struct GNUNET_MessageHeader header;
 158
 159   /**
 160    * Message options, actually an 'enum GNUNET_DHT_RouteOption' value.
 161    */
 162   uint32_t options GNUNET_PACKED;
 163
 164   /**
 165    * Replication level for this message
 166    */
 167   uint32_t desired_replication_level GNUNET_PACKED;
 168
 169   /**
 170    * For alignment, always zero.
 171    */
 172   uint32_t reserved GNUNET_PACKED;
 173
 174   /**
 175    * The key to search for
 176    */
 177   GNUNET_HashCode key;
 178
 179   /**
 180    * Unique ID identifying this request, if 0 then
 181    * the client will not expect a response
 182    */
 183   uint64_t unique_id GNUNET_PACKED;
 184
 185
 186   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 187
 188 };
 189
 190
 191 /**
 192  * Generic local route result message
 193  */
 194 struct GNUNET_DHT_RouteResultMessage
 195 {
 196   /**
 197    * Type: GNUNET_MESSAGE_TYPE_DHT_LOCAL_ROUTE_RESULT
 198    */
 199   struct GNUNET_MessageHeader header;
 200
 201   /**
 202    * Number of peers recorded in the "PUT" path.
 203    * (original path message took during "PUT").  These
 204    * peer identities follow this message.
 205    */
 206   uint16_t put_path_length GNUNET_PACKED;
 207
 208   /**
 209    * Number of peers recorded in the "GET" path
 210    * (inverse of the path the GET message took).  These
 211    * peer identities follow this message.
 212    */
 213   uint16_t get_path_length GNUNET_PACKED;
 214
 215   /**
 216    * Unique ID identifying this request (necessary for
 217    * client to compare to sent requests)
 218    */
 219   uint64_t unique_id GNUNET_PACKED;
 220
 221   /**
 222    * The key that was searched for
 223    */
 224   GNUNET_HashCode key;
 225
 226   /* PUT path */
 227
 228   /* GET path */
 229
 230   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 231 };
 232
 233
 234 /**
 235  * Generic P2P DHT route message
 236  */
 237 struct GNUNET_DHT_P2PRouteMessage
 238 {
 239   /**
 240    * Type: GNUNET_MESSAGE_TYPE_DHT_P2P_ROUTE
 241    */
 242   struct GNUNET_MessageHeader header;
 243
 244   /**
 245    * Always zero.
 246    */
 247   uint32_t reserved GNUNET_PACKED;
 248
 249   /**
 250    * Message options
 251    */
 252   uint32_t options GNUNET_PACKED;
 253
 254   /**
 255    * Hop count
 256    */
 257   uint32_t hop_count GNUNET_PACKED;
 258
 259   /**
 260    * Replication level for this message
 261    */
 262   uint32_t desired_replication_level GNUNET_PACKED;
 263
 264   /**
 265    * Network size estimate
 266    */
 267   uint32_t network_size GNUNET_PACKED;
 268
 269   /**
 270    * Unique ID identifying this request
 271    */
 272   uint64_t unique_id GNUNET_PACKED;
 273
 274   /**
 275    * Bloomfilter to stop circular routes
 276    */
 277   char bloomfilter[DHT_BLOOM_SIZE];
 278
 279   /**
 280    * The key to search for
 281    */
 282   GNUNET_HashCode key;
 283
 284   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 285
 286 };
 287
 288 /**
 289  * Generic P2P route result
 290  *
 291  * FIXME: One question is how much to include for a route result message.
 292  *        Assuming a peer receives such a message, but has no record of a
 293  *        route message, what should it do?  It can either drop the message
 294  *        or try to forward it towards the original peer...  However, for
 295  *        that to work we would need to include the original peer identity
 296  *        in the GET request, which adds more data to the message.
 297  */
 298 struct GNUNET_DHT_P2PRouteResultMessage
 299 {
 300   /**
 301    * Type: GNUNET_MESSAGE_TYPE_DHT_P2P_ROUTE_RESULT
 302    */
 303   struct GNUNET_MessageHeader header;
 304
 305   /**
 306    * Number of peers recorded in the "PUT" path.
 307    * (original path message took during "PUT").  These
 308    * peer identities follow this message.
 309    */
 310   uint16_t put_path_length GNUNET_PACKED;
 311
 312   /**
 313    * Number of peers recorded in the "GET" path
 314    * (inverse of the path the GET message took).  These
 315    * peer identities follow this message.
 316    */
 317   uint16_t get_path_length GNUNET_PACKED;
 318
 319   /**
 320    * Message options
 321    */
 322   uint32_t options GNUNET_PACKED;
 323
 324   /**
 325    * Hop count
 326    */
 327   uint32_t hop_count GNUNET_PACKED;
 328
 329   /**
 330    * Unique ID identifying this request (may not be set)
 331    */
 332   uint64_t unique_id GNUNET_PACKED;
 333
 334   /**
 335    * Bloomfilter to stop circular routes
 336    */
 337   char bloomfilter[DHT_BLOOM_SIZE];
 338
 339   /**
 340    * The key that was searched for
 341    */
 342   GNUNET_HashCode key;
 343
 344 #if FORWARD_UNKNOWN
 345   /**
 346    * Network size estimate
 347    */
 348   uint32_t network_size GNUNET_PACKED;
 349 #endif
 350
 351
 352   /* PUT path */
 353
 354   /* GET path */
 355
 356   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 357 };
 358
 359
 360 /**
 361  * Message to insert data into the DHT, shared
 362  * between api->server communication and P2P communication.
 363  * The type must be different for the two purposes.
 364  */
 365 struct GNUNET_DHT_PutMessage
 366 {
 367   /**
 368    * Type: GNUNET_MESSAGE_TYPE_DHT_PUT / GNUNET_MESSAGE_TYPE_DHT_P2P_PUT
 369    */
 370   struct GNUNET_MessageHeader header;
 371
 372   /**
 373    * The type of data to insert.
 374    */
 375   uint32_t type GNUNET_PACKED;
 376
 377   /**
 378    * How long should this data persist?
 379    */
 380   struct GNUNET_TIME_AbsoluteNBO expiration;
 381
 382 };
 383
 384
 385 /**
 386  * Message to request data from the DHT, shared
 387  * between P2P requests and local get requests.
 388  * Main difference is that if the request comes in
 389  * locally we need to remember it (for client response).
 390  */
 391 struct GNUNET_DHT_GetMessage
 392 {
 393   /**
 394    * Type: GNUNET_MESSAGE_TYPE_DHT_GET / GNUNET_MESSAGE_TYPE_DHT_P2P_GET
 395    */
 396   struct GNUNET_MessageHeader header;
 397
 398   /**
 399    * The type for the data for the GET request; actually an 'enum
 400    * GNUNET_BLOCK_Type'.
 401    */
 402   uint32_t type;
 403
 404   /**
 405    * Mutator used for the bloom filter (0 if no bf is used).
 406    */
 407   uint32_t bf_mutator;
 408
 409   /**
 410    * Size of the eXtended query (xquery).
 411    */
 412   uint16_t xquery_size;
 413
 414   /**
 415    * Size of the bloom filter.
 416    */
 417   uint16_t bf_size;
 418
 419   /* Followed by the xquery which has 'xquery_size' bytes */
 420
 421   /* Followed by the bloom filter (after xquery) with 'bf_size' bytes */
 422 };
 423
 424
 425 /**
 426  * Generic DHT message, indicates that a route request
 427  * should be issued, if coming from a client.  Shared
 428  * usage for api->server and P2P message passing.
 429  */
 430 struct GNUNET_DHT_FindPeerMessage
 431 {
 432   /**
 433    * Type: GNUNET_MESSAGE_TYPE_DHT_FIND_PEER
 434    */
 435   struct GNUNET_MessageHeader header;
 436
 437   /**
 438    * Bloomfilter to reduce find peer responses
 439    */
 440   char bloomfilter[DHT_BLOOM_SIZE];
 441 };
 442
 443
 444 /**
 445  * Message to return data either to the client API
 446  * or to respond to a request received from another
 447  * peer.  Shared format, different types.
 448  */
 449 struct GNUNET_DHT_GetResultMessage
 450 {
 451   /**
 452    * Type: GNUNET_MESSAGE_TYPE_DHT_GET_RESULT / GNUNET_MESSAGE_TYPE_DHT_P2P_GET_RESULT
 453    */
 454   struct GNUNET_MessageHeader header;
 455
 456   /**
 457    * The type for the data for the GET request
 458    */
 459   uint32_t type;
 460
 461   /**
 462    * When does this entry expire?
 463    */
 464   struct GNUNET_TIME_AbsoluteNBO expiration;
 465
 466 };
 467
 468
 469 #endif /* DHT_H_ */