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