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