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  * Add a unique ID to every request to make testing/profiling easier.
  34  * Should NEVER be enabled in production and makes the DHT incompatible
  35  * (since this changes the message format).
  36  */
  37 #define HAVE_UID_FOR_TESTING GNUNET_YES
  38
  39 /**
  40  * Include a bf for replies? Should not be needed (see Mantis #1769), but if I remove
  41  * this code it stops to work!?
  42  */
  43 #define HAVE_REPLY_BLOOMFILTER GNUNET_YES
  44
  45 /**
  46  * Needs to be GNUNET_YES for logging to dhtlog to work!
  47  */
  48 #define DEBUG_DHT_ROUTING GNUNET_YES
  49
  50 /**
  51  * Size of the bloom filter the DHT uses to filter peers.
  52  */
  53 #define DHT_BLOOM_SIZE 128
  54
  55 /**
  56  * Number of bits set per entry in the bloom filter for peers.
  57  */
  58 #define DHT_BLOOM_K 6
  59
  60 /**
  61  * How many requests to remember for forwarding responses.
  62  */
  63 #define MAX_OUTSTANDING_FORWARDS 100
  64
  65 /**
  66  * How long to remember requests so we can forward responses.
  67  */
  68 #define DHT_FORWARD_TIMEOUT GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MINUTES, 5)
  69
  70 /**
  71  * Priority for routing results from other peers through
  72  * the DHT.
  73  */
  74 #define DHT_SEND_PRIORITY 4
  75
  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 #define STAT_PEERS_KNOWN "# DHT Peers known"
 100
 101
 102 /**
 103  * FIXME: document.
 104  */
 105 typedef void (*GNUNET_DHT_MessageReceivedHandler) (void *cls,
 106                                                    const struct
 107                                                    GNUNET_MessageHeader * msg);
 108
 109
 110 /**
 111  * FIXME: document.
 112  */
 113 struct GNUNET_DHT_ControlMessage
 114 {
 115   /**
 116    * Type: GNUNET_MESSAGE_TYPE_DHT_CONTROL
 117    */
 118   struct GNUNET_MessageHeader header;
 119
 120   /**
 121    * Command code of the message.
 122    */
 123   uint16_t command;
 124
 125   /**
 126    * Variable parameter for the command.
 127    */
 128   uint16_t variable;
 129 };
 130
 131
 132 /**
 133  * Message which indicates the DHT should cancel outstanding
 134  * requests and discard any state.
 135  */
 136 struct GNUNET_DHT_StopMessage
 137 {
 138   /**
 139    * Type: GNUNET_MESSAGE_TYPE_DHT_STOP
 140    */
 141   struct GNUNET_MessageHeader header;
 142
 143   /**
 144    * Always zero.
 145    */
 146   uint32_t reserved GNUNET_PACKED;
 147
 148   /**
 149    * Unique ID identifying this request
 150    */
 151   uint64_t unique_id GNUNET_PACKED;
 152
 153   /**
 154    * Key of this request
 155    */
 156   GNUNET_HashCode key;
 157
 158 };
 159
 160
 161 /**
 162  * Generic DHT message, indicates that a route request
 163  * should be issued.
 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 outgoing
 216    * path from source to the final destination
 217    * of this message.
 218    */
 219   uint32_t outgoing_path_length GNUNET_PACKED;
 220
 221   /**
 222    * Unique ID identifying this request (necessary for
 223    * client to compare to sent requests)
 224    */
 225   uint64_t unique_id GNUNET_PACKED;
 226
 227   /**
 228    * The key that was searched for
 229    */
 230   GNUNET_HashCode key;
 231
 232   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 233
 234   /* OUTGOING path */
 235 };
 236
 237
 238 /**
 239  * Generic P2P DHT route message
 240  */
 241 struct GNUNET_DHT_P2PRouteMessage
 242 {
 243   /**
 244    * Type: GNUNET_MESSAGE_TYPE_DHT_P2P_ROUTE
 245    */
 246   struct GNUNET_MessageHeader header;
 247
 248   /**
 249    * Always zero.
 250    */
 251   uint32_t reserved GNUNET_PACKED;
 252
 253   /**
 254    * Message options
 255    */
 256   uint32_t options GNUNET_PACKED;
 257
 258   /**
 259    * Hop count
 260    */
 261   uint32_t hop_count GNUNET_PACKED;
 262
 263   /**
 264    * Replication level for this message
 265    */
 266   uint32_t desired_replication_level GNUNET_PACKED;
 267
 268   /**
 269    * Network size estimate
 270    */
 271   uint32_t network_size GNUNET_PACKED;
 272
 273   /**
 274    * Generic route path length for a message in the
 275    * DHT that arrived at a peer and generated
 276    * a reply. Copied to the end of this message.
 277    */
 278   uint32_t outgoing_path_length GNUNET_PACKED;
 279
 280 #if HAVE_UID_FOR_TESTING
 281   /**
 282    * Unique ID identifying this request (may not be set)
 283    */
 284   uint64_t unique_id GNUNET_PACKED;
 285 #endif
 286
 287   /**
 288    * Bloomfilter (for peer identities) 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   /* OUTGOING PATH */
 300
 301 };
 302
 303 /**
 304  * Generic P2P route result
 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 path
 315    * (inverse of the path the outgoing message took).
 316    * These peer identities follow this message.
 317    */
 318   uint32_t outgoing_path_length GNUNET_PACKED;
 319
 320   /**
 321    * Message options
 322    */
 323   uint32_t options GNUNET_PACKED;
 324
 325   /**
 326    * Hop count
 327    */
 328   uint32_t hop_count GNUNET_PACKED;
 329
 330 #if HAVE_UID_FOR_TESTING
 331   /**
 332    * Unique ID identifying this request (may not be set)
 333    */
 334   uint64_t unique_id GNUNET_PACKED;
 335 #endif
 336
 337 #if HAVE_REPLY_BLOOMFILTER
 338   /**
 339    * Bloomfilter to stop circular routes
 340    */
 341   char bloomfilter[DHT_BLOOM_SIZE];
 342 #endif
 343
 344   /**
 345    * The key that was searched for
 346    */
 347   GNUNET_HashCode key;
 348
 349   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 350
 351   /* OUTGOING PATH */
 352 };
 353
 354
 355 /**
 356  * Message to insert data into the DHT, shared
 357  * between api->server communication and P2P communication.
 358  * The type must be different for the two purposes.
 359  */
 360 struct GNUNET_DHT_PutMessage
 361 {
 362   /**
 363    * Type: GNUNET_MESSAGE_TYPE_DHT_PUT / GNUNET_MESSAGE_TYPE_DHT_P2P_PUT
 364    */
 365   struct GNUNET_MessageHeader header;
 366
 367   /**
 368    * The type of data to insert.
 369    */
 370   uint32_t type GNUNET_PACKED;
 371
 372   /**
 373    * How long should this data persist?
 374    */
 375   struct GNUNET_TIME_AbsoluteNBO expiration;
 376
 377   /* DATA copied to end of this message */
 378
 379 };
 380
 381
 382 /**
 383  * Message to request data from the DHT, shared
 384  * between P2P requests and local get requests.
 385  * Main difference is that if the request comes in
 386  * locally we need to remember it (for client response).
 387  */
 388 struct GNUNET_DHT_GetMessage
 389 {
 390   /**
 391    * Type: GNUNET_MESSAGE_TYPE_DHT_GET / GNUNET_MESSAGE_TYPE_DHT_P2P_GET
 392    */
 393   struct GNUNET_MessageHeader header;
 394
 395   /**
 396    * The type for the data for the GET request; actually an 'enum
 397    * GNUNET_BLOCK_Type'.
 398    */
 399   uint32_t type;
 400
 401   /**
 402    * Mutator used for the bloom filter (0 if no bf is used).
 403    */
 404   uint32_t bf_mutator;
 405
 406   /**
 407    * Size of the eXtended query (xquery).
 408    */
 409   uint16_t xquery_size;
 410
 411   /**
 412    * Size of the bloom filter.
 413    */
 414   uint16_t bf_size;
 415
 416   /* Followed by the xquery which has 'xquery_size' bytes */
 417
 418   /* Followed by the bloom filter (after xquery) with 'bf_size' bytes */
 419 };
 420
 421
 422 /**
 423  * Generic DHT message, indicates that a route request
 424  * should be issued, if coming from a client.  Shared
 425  * usage for api->server and P2P message passing.
 426  */
 427 struct GNUNET_DHT_FindPeerMessage
 428 {
 429   /**
 430    * Type: GNUNET_MESSAGE_TYPE_DHT_FIND_PEER
 431    */
 432   struct GNUNET_MessageHeader header;
 433
 434   /**
 435    * Bloomfilter to reduce find peer responses
 436    */
 437   char bloomfilter[DHT_BLOOM_SIZE];
 438 };
 439
 440
 441 /**
 442  * Message to return data either to the client API
 443  * or to respond to a request received from another
 444  * peer.  Shared format, different types.
 445  */
 446 struct GNUNET_DHT_GetResultMessage
 447 {
 448   /**
 449    * Type: GNUNET_MESSAGE_TYPE_DHT_GET_RESULT / GNUNET_MESSAGE_TYPE_DHT_P2P_GET_RESULT
 450    */
 451   struct GNUNET_MessageHeader header;
 452
 453   /**
 454    * The type for the data for the GET request
 455    * FIXME: use 32-bit types, as in block? What is this type exactly for?
 456    */
 457   uint16_t type;
 458
 459   /**
 460    * The number of peer identities appended to the end of this
 461    * message.
 462    */
 463   uint16_t put_path_length;
 464
 465   /**
 466    * When does this entry expire?
 467    */
 468   struct GNUNET_TIME_AbsoluteNBO expiration;
 469
 470   /* OUTGOING path copied to end of this message */
 471   /* DATA result copied to end of this message */
 472
 473 };
 474
 475 /**
 476  * Entry for inserting data into datacache from the DHT.
 477  * Needed here so block library can verify entries that
 478  * are shoveled into the DHT.
 479  */
 480 struct DHTPutEntry
 481 {
 482   /**
 483    * Size of data.
 484    */
 485   uint16_t data_size;
 486
 487   /**
 488    * Length of recorded path.
 489    */
 490   uint16_t path_length;
 491
 492   /* PUT DATA */
 493
 494   /* PATH ENTRIES */
 495 };
 496
 497
 498 #endif /* DHT_H_ */