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