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_NO
  38
  39 /**
  40  * Needs to be GNUNET_YES for logging to dhtlog to work!
  41  */
  42 #define DEBUG_DHT_ROUTING GNUNET_YES
  43
  44 /**
  45  * Size of the bloom filter the DHT uses to filter peers.
  46  */
  47 #define DHT_BLOOM_SIZE 128
  48
  49 /**
  50  * Number of bits set per entry in the bloom filter for peers.
  51  */
  52 #define DHT_BLOOM_K 6
  53
  54 /**
  55  * How many requests to remember for forwarding responses.
  56  */
  57 #define MAX_OUTSTANDING_FORWARDS 100
  58
  59 /**
  60  * How long to remember requests so we can forward responses.
  61  */
  62 #define DHT_FORWARD_TIMEOUT GNUNET_TIME_relative_multiply(GNUNET_TIME_UNIT_MINUTES, 5)
  63
  64 /**
  65  * Priority for routing results from other peers through
  66  * the DHT.
  67  */
  68 #define DHT_SEND_PRIORITY 4
  69
  70
  71 #define STAT_ROUTES "# DHT ROUTE Requests Seen"
  72 #define STAT_ROUTE_FORWARDS "# DHT ROUTE Requests Forwarded"
  73 #define STAT_ROUTE_FORWARDS_CLOSEST "# DHT ROUTE Requests Forwarded to Closest Known Peer"
  74 #define STAT_RESULTS "# DHT ROUTE RESULT Requests Seen"
  75 #define STAT_RESULTS_TO_CLIENT "# DHT ROUTE RESULT Sent to Client"
  76 #define STAT_RESULT_FORWARDS "# DHT ROUTE RESULT Requests Forwarded"
  77 #define STAT_GETS "# DHT GET Requests Handled"
  78 #define STAT_PUTS "# DHT PUT Requests Handled"
  79 #define STAT_PUTS_INSERTED "# DHT PUT Data Inserts"
  80 #define STAT_FIND_PEER "# DHT FIND_PEER Requests Handled"
  81 #define STAT_FIND_PEER_START "# DHT FIND_PEER Requests Initiated"
  82 #define STAT_GET_START "# DHT GET Requests Initiated"
  83 #define STAT_PUT_START "# DHT PUT Requests Initiated"
  84 #define STAT_FIND_PEER_REPLY "# DHT FIND_PEER Responses Received"
  85 #define STAT_GET_REPLY "# DHT GET Responses Received"
  86 #define STAT_FIND_PEER_ANSWER "# DHT FIND_PEER Responses Initiated"
  87 #define STAT_BLOOM_FIND_PEER "# DHT FIND_PEER Responses Ignored (bloom match)"
  88 #define STAT_GET_RESPONSE_START "# DHT GET Responses Initiated"
  89 #define STAT_HELLOS_PROVIDED "# HELLO Messages given to transport"
  90 #define STAT_DISCONNECTS "# Disconnects received"
  91 #define STAT_DUPLICATE_UID "# Duplicate UID's encountered (bad if any!)"
  92 #define STAT_RECENT_SEEN "# recent requests seen again (routing loops, alternate paths)"
  93 #define STAT_PEERS_KNOWN "# DHT Peers known"
  94
  95
  96 /**
  97  * FIXME: document.
  98  */
  99 typedef void (*GNUNET_DHT_MessageReceivedHandler) (void *cls,
 100                                                    const struct
 101                                                    GNUNET_MessageHeader * 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.
 158  */
 159 struct GNUNET_DHT_RouteMessage
 160 {
 161   /**
 162    * Type: GNUNET_MESSAGE_TYPE_DHT_LOCAL_ROUTE
 163    */
 164   struct GNUNET_MessageHeader header;
 165
 166   /**
 167    * Message options, actually an 'enum GNUNET_DHT_RouteOption' value.
 168    */
 169   uint32_t options GNUNET_PACKED;
 170
 171   /**
 172    * Replication level for this message
 173    */
 174   uint32_t desired_replication_level GNUNET_PACKED;
 175
 176   /**
 177    * For alignment, always zero.
 178    */
 179   uint32_t reserved GNUNET_PACKED;
 180
 181   /**
 182    * The key to search for
 183    */
 184   GNUNET_HashCode key;
 185
 186   /**
 187    * Unique ID identifying this request, if 0 then
 188    * the client will not expect a response
 189    */
 190   uint64_t unique_id GNUNET_PACKED;
 191
 192
 193   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 194
 195 };
 196
 197
 198 /**
 199  * Generic local route result message
 200  */
 201 struct GNUNET_DHT_RouteResultMessage
 202 {
 203   /**
 204    * Type: GNUNET_MESSAGE_TYPE_DHT_LOCAL_ROUTE_RESULT
 205    */
 206   struct GNUNET_MessageHeader header;
 207
 208   /**
 209    * Number of peers recorded in the outgoing
 210    * path from source to the final destination
 211    * of this message.
 212    */
 213   uint32_t outgoing_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   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 227
 228   /* OUTGOING path */
 229 };
 230
 231
 232 /**
 233  * Generic P2P DHT route message
 234  */
 235 struct GNUNET_DHT_P2PRouteMessage
 236 {
 237   /**
 238    * Type: GNUNET_MESSAGE_TYPE_DHT_P2P_ROUTE
 239    */
 240   struct GNUNET_MessageHeader header;
 241
 242   /**
 243    * Always zero.
 244    */
 245   uint32_t reserved GNUNET_PACKED;
 246
 247   /**
 248    * Message options
 249    */
 250   uint32_t options GNUNET_PACKED;
 251
 252   /**
 253    * Hop count
 254    */
 255   uint32_t hop_count GNUNET_PACKED;
 256
 257   /**
 258    * Replication level for this message
 259    */
 260   uint32_t desired_replication_level GNUNET_PACKED;
 261
 262   /**
 263    * Network size estimate
 264    */
 265   uint32_t network_size GNUNET_PACKED;
 266
 267   /**
 268    * Generic route path length for a message in the
 269    * DHT that arrived at a peer and generated
 270    * a reply. Copied to the end of this message.
 271    */
 272   uint32_t outgoing_path_length GNUNET_PACKED;
 273
 274 #if HAVE_UID_FOR_TESTING
 275   /**
 276    * Unique ID identifying this request (may not be set)
 277    */
 278   uint64_t unique_id GNUNET_PACKED;
 279 #endif
 280
 281   /**
 282    * Bloomfilter (for peer identities) to stop circular routes
 283    */
 284   char bloomfilter[DHT_BLOOM_SIZE];
 285
 286   /**
 287    * The key to search for
 288    */
 289   GNUNET_HashCode key;
 290
 291   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 292
 293   /* OUTGOING PATH */
 294
 295 };
 296
 297 /**
 298  * Generic P2P route result
 299  */
 300 struct GNUNET_DHT_P2PRouteResultMessage
 301 {
 302   /**
 303    * Type: GNUNET_MESSAGE_TYPE_DHT_P2P_ROUTE_RESULT
 304    */
 305   struct GNUNET_MessageHeader header;
 306
 307   /**
 308    * Number of peers recorded in the path
 309    * (inverse of the path the outgoing message took).
 310    * These peer identities follow this message.
 311    */
 312   uint32_t outgoing_path_length GNUNET_PACKED;
 313
 314   /**
 315    * Message options
 316    */
 317   uint32_t options GNUNET_PACKED;
 318
 319   /**
 320    * Hop count
 321    */
 322   uint32_t hop_count GNUNET_PACKED;
 323
 324 #if HAVE_UID_FOR_TESTING
 325   /**
 326    * Unique ID identifying this request (may not be set)
 327    */
 328   uint64_t unique_id GNUNET_PACKED;
 329 #endif
 330
 331   /**
 332    * The key that was searched for
 333    */
 334   GNUNET_HashCode key;
 335
 336   /* GNUNET_MessageHeader *enc actual DHT message, copied to end of this dealy do */
 337
 338   /* OUTGOING PATH */
 339 };
 340
 341
 342 /**
 343  * Message to insert data into the DHT, shared
 344  * between api->server communication and P2P communication.
 345  * The type must be different for the two purposes.
 346  */
 347 struct GNUNET_DHT_PutMessage
 348 {
 349   /**
 350    * Type: GNUNET_MESSAGE_TYPE_DHT_PUT / GNUNET_MESSAGE_TYPE_DHT_P2P_PUT
 351    */
 352   struct GNUNET_MessageHeader header;
 353
 354   /**
 355    * The type of data to insert.
 356    */
 357   uint32_t type GNUNET_PACKED;
 358
 359   /**
 360    * How long should this data persist?
 361    */
 362   struct GNUNET_TIME_AbsoluteNBO expiration;
 363
 364   /* DATA copied to end of this message */
 365
 366 };
 367
 368
 369 /**
 370  * Message to request data from the DHT, shared
 371  * between P2P requests and local get requests.
 372  * Main difference is that if the request comes in
 373  * locally we need to remember it (for client response).
 374  */
 375 struct GNUNET_DHT_GetMessage
 376 {
 377   /**
 378    * Type: GNUNET_MESSAGE_TYPE_DHT_GET / GNUNET_MESSAGE_TYPE_DHT_P2P_GET
 379    */
 380   struct GNUNET_MessageHeader header;
 381
 382   /**
 383    * The type for the data for the GET request; actually an 'enum
 384    * GNUNET_BLOCK_Type'.
 385    */
 386   uint32_t type;
 387
 388   /**
 389    * Mutator used for the bloom filter (0 if no bf is used).
 390    */
 391   uint32_t bf_mutator;
 392
 393   /**
 394    * Size of the eXtended query (xquery).
 395    */
 396   uint16_t xquery_size;
 397
 398   /**
 399    * Size of the bloom filter.
 400    */
 401   uint16_t bf_size;
 402
 403   /* Followed by the xquery which has 'xquery_size' bytes */
 404
 405   /* Followed by the bloom filter (after xquery) with 'bf_size' bytes */
 406 };
 407
 408
 409 /**
 410  * Generic DHT message, indicates that a route request
 411  * should be issued, if coming from a client.  Shared
 412  * usage for api->server and P2P message passing.
 413  */
 414 struct GNUNET_DHT_FindPeerMessage
 415 {
 416   /**
 417    * Type: GNUNET_MESSAGE_TYPE_DHT_FIND_PEER
 418    */
 419   struct GNUNET_MessageHeader header;
 420
 421   /**
 422    * Bloomfilter to reduce find peer responses
 423    */
 424   char bloomfilter[DHT_BLOOM_SIZE];
 425 };
 426
 427
 428 /**
 429  * Message to return data either to the client API
 430  * or to respond to a request received from another
 431  * peer.  Shared format, different types.
 432  */
 433 struct GNUNET_DHT_GetResultMessage
 434 {
 435   /**
 436    * Type: GNUNET_MESSAGE_TYPE_DHT_GET_RESULT / GNUNET_MESSAGE_TYPE_DHT_P2P_GET_RESULT
 437    */
 438   struct GNUNET_MessageHeader header;
 439
 440   /**
 441    * The type for the data for the GET request
 442    * FIXME: use 32-bit types, as in block? What is this type exactly for?
 443    */
 444   uint16_t type;
 445
 446   /**
 447    * The number of peer identities appended to the end of this
 448    * message.
 449    */
 450   uint16_t put_path_length;
 451
 452   /**
 453    * When does this entry expire?
 454    */
 455   struct GNUNET_TIME_AbsoluteNBO expiration;
 456
 457   /* OUTGOING path copied to end of this message */
 458   /* DATA result copied to end of this message */
 459
 460 };
 461
 462 /**
 463  * Entry for inserting data into datacache from the DHT.
 464  * Needed here so block library can verify entries that
 465  * are shoveled into the DHT.
 466  */
 467 struct DHTPutEntry
 468 {
 469   /**
 470    * Size of data.
 471    */
 472   uint16_t data_size;
 473
 474   /**
 475    * Length of recorded path.
 476    */
 477   uint16_t path_length;
 478
 479   /* PUT DATA */
 480
 481   /* PATH ENTRIES */
 482 };
 483
 484
 485 #endif /* DHT_H_ */