src/transport/transport.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 GNUnet e.V.
   4
   5      GNUnet is free software: you can redistribute it and/or modify it
   6      under the terms of the GNU Affero General Public License as published
   7      by the Free Software Foundation, either version 3 of the License,
   8      or (at your 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      Affero General Public License for more details.
  14
  15      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18
  19 /**
  20  * @file transport/transport.h
  21  * @brief common internal definitions for transport service
  22  * @author Christian Grothoff
  23  */
  24 #ifndef TRANSPORT_H
  25 #define TRANSPORT_H
  26
  27 #include "gnunet_crypto_lib.h"
  28 #include "gnunet_time_lib.h"
  29 #include "gnunet_transport_service.h"
  30 #include "gnunet_constants.h"
  31
  32 #define DEBUG_TRANSPORT GNUNET_EXTRA_LOGGING
  33
  34
  35 /**
  36  * For how long do we allow unused bandwidth
  37  * from the past to carry over into the future? (in seconds)
  38  */
  39 #define MAX_BANDWIDTH_CARRY_S GNUNET_CONSTANTS_MAX_BANDWIDTH_CARRY_S
  40
  41 /**
  42  * How often do we (at most) do a full quota
  43  * recalculation? (in ms)
  44  */
  45 #define MIN_QUOTA_REFRESH_TIME 2000
  46
  47 /**
  48  * What's the maximum number of sockets transport uses for validation and
  49  * neighbors
  50  */
  51 #define DEFAULT_MAX_FDS 256
  52
  53 /**
  54  * Maximum frequency for re-evaluating latencies for all transport addresses.
  55  */
  56 #define LATENCY_EVALUATION_MAX_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_HOURS, 1)
  57
  58 /**
  59  * Maximum frequency for re-evaluating latencies for connected addresses.
  60  */
  61 #define CONNECTED_LATENCY_EVALUATION_MAX_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MINUTES, 1)
  62
  63 /**
  64  * Similiar to GNUNET_TRANSPORT_NotifyDisconnect but in and out quotas are
  65  * included here. These values are not required outside transport_api
  66  *
  67  * @param cls closure
  68  * @param peer the peer that connected
  69  * @param bandwidth_in inbound bandwidth in NBO
  70  * @param bandwidth_out outbound bandwidth in NBO
  71  *
  72  */
  73 typedef void
  74 (*NotifyConnect) (void *cls,
  75                   const struct GNUNET_PeerIdentity *peer,
  76                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
  77                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out);
  78
  79
  80 GNUNET_NETWORK_STRUCT_BEGIN
  81
  82 /**
  83  * Message from the transport service to the library
  84  * asking to check if both processes agree about this
  85  * peers identity.
  86  */
  87 struct StartMessage
  88 {
  89
  90   /**
  91    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_START
  92    */
  93   struct GNUNET_MessageHeader header;
  94
  95   /**
  96    * 0: no options
  97    * 1: The 'self' field should be checked
  98    * 2: this client is interested in payload traffic
  99    */
 100   uint32_t options;
 101
 102   /**
 103    * Identity we think we have.  If it does not match, the
 104    * receiver should print out an error message and disconnect.
 105    */
 106   struct GNUNET_PeerIdentity self;
 107
 108 };
 109
 110
 111 /**
 112  * Message from the transport service to the library
 113  * informing about neighbors.
 114  */
 115 struct ConnectInfoMessage
 116 {
 117
 118   /**
 119    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_CONNECT
 120    */
 121   struct GNUNET_MessageHeader header;
 122
 123   /**
 124    * Identity of the new neighbour.
 125    */
 126   struct GNUNET_PeerIdentity id;
 127
 128   /**
 129    * Current inbound quota for this peer
 130    */
 131   struct GNUNET_BANDWIDTH_Value32NBO quota_in;
 132
 133   /**
 134    * Current outbound quota for this peer
 135    */
 136   struct GNUNET_BANDWIDTH_Value32NBO quota_out;
 137 };
 138
 139
 140 /**
 141  * Message from the transport service to the library
 142  * informing about disconnects.
 143  */
 144 struct DisconnectInfoMessage
 145 {
 146
 147   /**
 148    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_DISCONNECT
 149    */
 150   struct GNUNET_MessageHeader header;
 151
 152   /**
 153    * Reserved, always zero.
 154    */
 155   uint32_t reserved GNUNET_PACKED;
 156
 157   /**
 158    * Who got disconnected?
 159    */
 160   struct GNUNET_PeerIdentity peer;
 161
 162 };
 163
 164
 165 /**
 166  * Message used to set a particular bandwidth quota.  Sent TO the
 167  * service to set an incoming quota, sent FROM the service to update
 168  * an outgoing quota.
 169  */
 170 struct QuotaSetMessage
 171 {
 172
 173   /**
 174    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SET_QUOTA
 175    */
 176   struct GNUNET_MessageHeader header;
 177
 178   /**
 179    * Quota.
 180    */
 181   struct GNUNET_BANDWIDTH_Value32NBO quota;
 182
 183   /**
 184    * About which peer are we talking here?
 185    */
 186   struct GNUNET_PeerIdentity peer;
 187
 188 };
 189
 190
 191 /**
 192  * Message used to notify the transport API about a message
 193  * received from the network.  The actual message follows.
 194  */
 195 struct InboundMessage
 196 {
 197
 198   /**
 199    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_RECV
 200    */
 201   struct GNUNET_MessageHeader header;
 202
 203   /**
 204    * Which peer sent the message?
 205    */
 206   struct GNUNET_PeerIdentity peer;
 207
 208 };
 209
 210
 211 /**
 212  * Message used to notify the transport API that it can
 213  * send another message to the transport service.
 214  */
 215 struct SendOkMessage
 216 {
 217
 218   /**
 219    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND_OK
 220    */
 221   struct GNUNET_MessageHeader header;
 222
 223   /**
 224    * #GNUNET_OK if the transmission succeeded,
 225    * #GNUNET_SYSERR if it failed (i.e. network disconnect);
 226    * in either case, it is now OK for this client to
 227    * send us another message for the given peer.
 228    */
 229   uint32_t success GNUNET_PACKED;
 230
 231   /**
 232    * Size of message sent
 233    */
 234   uint32_t bytes_msg GNUNET_PACKED;
 235
 236   /**
 237    * Size of message sent over wire
 238    * Includes plugin and protocol specific overhead
 239    */
 240   uint32_t bytes_physical GNUNET_PACKED;
 241
 242   /**
 243    * Which peer can send more now?
 244    */
 245   struct GNUNET_PeerIdentity peer;
 246
 247 };
 248
 249 /**
 250  * Message used to notify the transport API about an address to string
 251  * conversion. Message is followed by the string with the humand-readable
 252  * address.  For each lookup, multiple results may be returned.  The
 253  * last message must have a @e res of #GNUNET_OK and an @e addr_len
 254  * of zero.
 255  */
 256 struct AddressToStringResultMessage
 257 {
 258
 259   /**
 260    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING_REPLY
 261    */
 262   struct GNUNET_MessageHeader header;
 263
 264   /**
 265    * #GNUNET_OK if the conversion succeeded,
 266    * #GNUNET_SYSERR if it failed
 267    */
 268   uint32_t res GNUNET_PACKED;
 269
 270   /**
 271    * Length of the following string, zero if @e is #GNUNET_SYSERR
 272    */
 273   uint32_t addr_len GNUNET_PACKED;
 274 };
 275
 276
 277 /**
 278  * Message used to notify the transport service about a message
 279  * to be transmitted to another peer.  The actual message follows.
 280  */
 281 struct OutboundMessage
 282 {
 283
 284   /**
 285    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND
 286    */
 287   struct GNUNET_MessageHeader header;
 288
 289   /**
 290    * Always zero.
 291    */
 292   uint32_t reserved GNUNET_PACKED;
 293
 294   /**
 295    * Allowed delay.
 296    */
 297   struct GNUNET_TIME_RelativeNBO timeout;
 298
 299   /**
 300    * Which peer should receive the message?
 301    */
 302   struct GNUNET_PeerIdentity peer;
 303
 304 };
 305
 306
 307 /**
 308  * Message from the library to the transport service
 309  * asking for converting a transport address to a
 310  * human-readable UTF-8 string.
 311  */
 312 struct AddressLookupMessage
 313 {
 314
 315   /**
 316    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING
 317    */
 318   struct GNUNET_MessageHeader header;
 319
 320   /**
 321    * Should the conversion use numeric IP addresses (otherwise
 322    * a reverse DNS lookup is OK -- if applicable).
 323    */
 324   int16_t numeric_only GNUNET_PACKED;
 325
 326   /**
 327    * Length of the (binary) address in bytes, in big-endian.
 328    */
 329   uint16_t addrlen GNUNET_PACKED;
 330
 331   /**
 332    * timeout to give up (for DNS resolution timeout mostly)
 333    */
 334   struct GNUNET_TIME_RelativeNBO timeout;
 335
 336   /* followed by @e addrlen bytes of the actual address, then
 337    * followed by the 0-terminated name of the transport */
 338 };
 339
 340
 341 /**
 342  * Message from the transport service to the library containing information
 343  * about a peer. Information contained are:
 344  * - current address used to communicate with this peer
 345  * - state
 346  * - state timeout
 347  *
 348  * Memory layout:
 349  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 350  */
 351 struct ValidationIterateResponseMessage
 352 {
 353   /**
 354    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_RESPONSE
 355    */
 356   struct GNUNET_MessageHeader header;
 357
 358   /**
 359    * For alignment.
 360    */
 361   uint32_t reserved;
 362
 363   /**
 364    * Peer identity
 365    */
 366   struct GNUNET_PeerIdentity peer;
 367
 368   /**
 369    * Local info about the address
 370    */
 371   uint32_t local_address_info GNUNET_PACKED;
 372
 373   /**
 374    * Address length
 375    */
 376   uint32_t addrlen GNUNET_PACKED;
 377
 378   /**
 379    * Length of the plugin name
 380    */
 381   uint32_t pluginlen GNUNET_PACKED;
 382
 383   /**
 384    * State
 385    */
 386   uint32_t state GNUNET_PACKED;
 387
 388   /**
 389    * At what time did we successfully validate the address last.
 390    * Will be NEVER if the address failed validation.
 391    */
 392   struct GNUNET_TIME_AbsoluteNBO last_validation;
 393
 394   /**
 395    * Until when is the address believed to be valid.
 396    * Will be ZERO if the address is not belived to be valid.
 397    */
 398   struct GNUNET_TIME_AbsoluteNBO valid_until;
 399
 400   /**
 401    * When will we next try to validate the address (typically
 402    * done before @e valid_until happens).
 403    */
 404   struct GNUNET_TIME_AbsoluteNBO next_validation;
 405 };
 406
 407 /**
 408  * Message from the library to the transport service
 409  * asking for binary addresses known for a peer.
 410  */
 411 struct ValidationMonitorMessage
 412 {
 413   /**
 414    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_REQUEST
 415    */
 416   struct GNUNET_MessageHeader header;
 417
 418   /**
 419    * One shot call or continous replies?
 420    */
 421   uint32_t one_shot GNUNET_PACKED;
 422
 423   /**
 424    * The identity of the peer to look up.
 425    */
 426   struct GNUNET_PeerIdentity peer;
 427
 428 };
 429
 430
 431 /**
 432  * Message from the library to the transport service
 433  * asking for binary addresses known for a peer.
 434  */
 435 struct PeerMonitorMessage
 436 {
 437   /**
 438    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_REQUEST
 439    */
 440   struct GNUNET_MessageHeader header;
 441
 442   /**
 443    * One shot call or continous replies?
 444    */
 445   uint32_t one_shot GNUNET_PACKED;
 446
 447   /**
 448    * The identity of the peer to look up.
 449    */
 450   struct GNUNET_PeerIdentity peer;
 451
 452 };
 453
 454
 455 /**
 456  * Message from the library to the transport service
 457  * asking for binary addresses known for a peer.
 458  */
 459 struct TrafficMetricMessage
 460 {
 461   /**
 462    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_TRAFFIC_METRIC
 463    */
 464   struct GNUNET_MessageHeader header;
 465
 466   /**
 467    * Always zero.
 468    */
 469   uint32_t reserved GNUNET_PACKED;
 470
 471   /**
 472    * The identity of the peer to look up.
 473    */
 474   struct GNUNET_PeerIdentity peer;
 475
 476   /**
 477    * Fake properties to generate.
 478    */
 479   struct GNUNET_ATS_PropertiesNBO properties;
 480
 481   /**
 482    * Fake delay to add on inbound traffic.
 483    */
 484   struct GNUNET_TIME_RelativeNBO delay_in;
 485
 486   /**
 487    * Fake delay to add on outbound traffic.
 488    */
 489   struct GNUNET_TIME_RelativeNBO delay_out;
 490 };
 491
 492
 493 /**
 494  * Message from the transport service to the library containing information
 495  * about a peer. Information contained are:
 496  * - current address used to communicate with this peer
 497  * - state
 498  * - state timeout
 499  *
 500  * Memory layout:
 501  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 502  */
 503 struct PeerIterateResponseMessage
 504 {
 505   /**
 506    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_RESPONSE
 507    */
 508   struct GNUNET_MessageHeader header;
 509
 510   /**
 511    * For alignment.
 512    */
 513   uint32_t reserved;
 514
 515   /**
 516    * Peer identity
 517    */
 518   struct GNUNET_PeerIdentity peer;
 519
 520   /**
 521    * Timeout for the state this peer is in
 522    */
 523   struct GNUNET_TIME_AbsoluteNBO state_timeout;
 524
 525   /**
 526    * Local info about the address
 527    */
 528   uint32_t local_address_info GNUNET_PACKED;
 529
 530   /**
 531    * State this peer is in as an `enum GNUNET_TRANSPORT_PeerState`
 532    */
 533   uint32_t state GNUNET_PACKED;
 534
 535   /**
 536    * Address length
 537    */
 538   uint32_t addrlen GNUNET_PACKED;
 539
 540   /**
 541    * Length of the plugin name
 542    */
 543   uint32_t pluginlen GNUNET_PACKED;
 544
 545 };
 546
 547
 548 /**
 549  * Change in blacklisting (either request or notification,
 550  * depending on which direction it is going).
 551  */
 552 struct BlacklistMessage
 553 {
 554
 555   /**
 556    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_QUERY or
 557    * #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_REPLY.
 558    */
 559   struct GNUNET_MessageHeader header;
 560
 561   /**
 562    * 0 for the query, #GNUNET_OK (allowed) or #GNUNET_SYSERR (disallowed)
 563    * for the response.
 564    */
 565   uint32_t is_allowed GNUNET_PACKED;
 566
 567   /**
 568    * Which peer is being blacklisted or queried?
 569    */
 570   struct GNUNET_PeerIdentity peer;
 571
 572 };
 573
 574
 575 /**
 576  * Transport-level connection status update.
 577  */
 578 struct TransportPluginMonitorMessage
 579 {
 580
 581   /**
 582    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PLUGIN_EVENT.
 583    */
 584   struct GNUNET_MessageHeader header;
 585
 586   /**
 587    * An `enum GNUNET_TRANSPORT_SessionState` in NBO.
 588    */
 589   uint16_t session_state GNUNET_PACKED;
 590
 591   /**
 592    * #GNUNET_YES if this is an inbound connection,
 593    * #GNUNET_NO if this is an outbound connection,
 594    * #GNUNET_SYSERR if connections of this plugin
 595    *             are so fundamentally bidirectional
 596    *             that they have no 'initiator'
 597    * Value given in NBO.
 598    */
 599   int16_t is_inbound GNUNET_PACKED;
 600
 601   /**
 602    * Number of messages waiting transmission.
 603    */
 604   uint32_t msgs_pending GNUNET_PACKED;
 605
 606   /**
 607    * Number of bytes waiting for transmission.
 608    */
 609   uint32_t bytes_pending GNUNET_PACKED;
 610
 611   /**
 612    * When will this transport plugin session time out?
 613    */
 614   struct GNUNET_TIME_AbsoluteNBO timeout;
 615
 616   /**
 617    * Until how long is this plugin currently blocked from reading?
 618    */
 619   struct GNUNET_TIME_AbsoluteNBO delay;
 620
 621   /**
 622    * Which peer is this connection for?
 623    */
 624   struct GNUNET_PeerIdentity peer;
 625
 626   /**
 627    * Unique identifier for the session.
 628    */
 629   uint64_t session_id;
 630
 631   /**
 632    * Length of the plugin name in bytes, including 0-termination.
 633    */
 634   uint16_t plugin_name_len GNUNET_PACKED;
 635
 636   /**
 637    * Length of the plugin address in bytes.
 638    */
 639   uint16_t plugin_address_len GNUNET_PACKED;
 640
 641   /* followed by 0-terminated plugin name and
 642      @e plugin_address_len bytes of plugin address */
 643
 644 };
 645
 646
 647 GNUNET_NETWORK_STRUCT_END
 648
 649 /* end of transport.h */
 650 #endif