src/testbed/testbed.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2012 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  * @file testbed/testbed.h
  23  * @brief IPC messages between testing API and service ("controller")
  24  * @author Christian Grothoff
  25  */
  26
  27 #ifndef TESTBED_H
  28 #define TESTBED_H
  29
  30 #include "gnunet_util_lib.h"
  31
  32
  33 /**
  34  * Initial message from a client to a testing control service.
  35  */
  36 struct GNUNET_TESTBED_InitMessage
  37 {
  38
  39   /**
  40    * Type is GNUNET_MESSAGE_TYPE_TESTBED_INIT
  41    */
  42   struct GNUNET_MessageHeader header;
  43
  44   /**
  45    * Host ID that the controller is either given (if this is the
  46    * dominating client) or assumed to have (for peer-connections
  47    * between controllers).  A controller must check that all
  48    * connections make consistent claims...
  49    */
  50   uint32_t host_id GNUNET_PACKED;
  51
  52   /**
  53    * Event mask that specifies which events this client
  54    * is interested in.  In NBO.
  55    */
  56   uint64_t event_mask GNUNET_PACKED;
  57
  58   /* Followed by 0-terminated hostname of the controller */
  59 };
  60
  61
  62 /**
  63  * Notify the service about a host that we intend to use.
  64  */
  65 struct GNUNET_TESTBED_AddHostMessage
  66 {
  67
  68   /**
  69    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADDHOST
  70    */
  71   struct GNUNET_MessageHeader header;
  72
  73   /**
  74    * Unique ID for the host (in NBO).
  75    */
  76   uint32_t host_id GNUNET_PACKED;
  77
  78   /**
  79    * SSH port to use, 0 for default (in NBO).
  80    */
  81   uint16_t ssh_port GNUNET_PACKED;
  82
  83   /**
  84    * Number of bytes in the user name that follows;
  85    * 0 to use no user name; otherwise 'strlen (username)',
  86    * excluding 0-termination!
  87    */
  88   uint16_t user_name_length GNUNET_PACKED;
  89
  90   /* followed by 0-terminated user name */
  91
  92   /* followed by 0-terminated host name */
  93
  94 };
  95
  96
  97 /**
  98  * Confirmation from the service that adding a host
  99  * worked (or failed).
 100  * FIXME: Where is this required?
 101  */
 102 struct GNUNET_TESTBED_HostConfirmedMessage
 103 {
 104
 105   /**
 106    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADDHOSTSUCCESS
 107    */
 108   struct GNUNET_MessageHeader header;
 109
 110   /**
 111    * Unique ID for the host (in NBO).
 112    */
 113   uint32_t host_id GNUNET_PACKED;
 114
 115   /* followed by the 0-terminated error message (on failure)
 116    (typical errors include failure to login and
 117    host-id already in use) */
 118
 119 };
 120
 121
 122 /**
 123  * Message to testing service: configure service sharing
 124  * at a host.
 125  */
 126 struct GNUNET_TESTBED_ConfigureSharedServiceMessage
 127 {
 128
 129   /**
 130    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SERVICESHARE
 131    */
 132   struct GNUNET_MessageHeader header;
 133
 134   /**
 135    * Host that is being configured.
 136    */
 137   uint32_t host_id GNUNET_PACKED;
 138
 139   /**
 140    * Number of peers that should share a service instance;
 141    * 1 for no sharing, 0 to forcefully disable the service.
 142    */
 143   uint32_t num_peers GNUNET_PACKED;
 144
 145   /* followed by 0-terminated name of the service */
 146
 147 };
 148
 149
 150 /**
 151  * Client notifies controller that it should delegate
 152  * requests for a particular client to a particular
 153  * sub-controller.
 154  */
 155 struct GNUNET_TESTBED_ControllerLinkMessage
 156 {
 157
 158   /**
 159    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LCONTROLLERS
 160    */
 161   struct GNUNET_MessageHeader header;
 162
 163   /**
 164    * For which host should requests be delegated? NBO.
 165    */
 166   uint32_t delegated_host_id GNUNET_PACKED;
 167
 168   /**
 169    * Which host is responsible for managing the delegation? NBO
 170    */
 171   uint32_t slave_host_id GNUNET_PACKED;
 172
 173   /**
 174    * The size of the uncompressed configuration
 175    */
 176   uint16_t config_size GNUNET_PACKED;
 177
 178   /**
 179    * Set to 1 if the receiving controller is the master controller for
 180    * the slave host (and thus responsible for starting it?). 0 if not
 181    */
 182   uint8_t is_subordinate;
 183
 184   /* followed by serialized slave configuration;
 185      gzip'ed configuration file in INI format */
 186
 187 };
 188
 189
 190 /**
 191  * Message sent from client to testing service to
 192  * create (configure, but not start) a peer.
 193  */
 194 struct GNUNET_TESTBED_PeerCreateMessage
 195 {
 196
 197   /**
 198    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATEPEER
 199    */
 200   struct GNUNET_MessageHeader header;
 201
 202   /**
 203    * Unique operation id
 204    */
 205   uint64_t operation_id GNUNET_PACKED;
 206
 207   /**
 208    * On which host should the peer be started?
 209    */
 210   uint32_t host_id GNUNET_PACKED;
 211
 212   /**
 213    * Unique ID for the peer.
 214    */
 215   uint32_t peer_id GNUNET_PACKED;
 216
 217   /**
 218    * Size of the uncompressed configuration
 219    */
 220   uint32_t config_size GNUNET_PACKED;
 221
 222   /* followed by serialized peer configuration;
 223      gzip'ed configuration file in INI format */
 224
 225 };
 226
 227
 228 /**
 229  * Message sent from client to testing service to
 230  * reconfigure a (stopped) a peer.
 231  */
 232 struct GNUNET_TESTBED_PeerReconfigureMessage
 233 {
 234
 235   /**
 236    * Type is GNUNET_MESSAGE_TYPDE_TESTBED_PEERRECONF
 237    */
 238   struct GNUNET_MessageHeader header;
 239
 240   /**
 241    * Unique ID for the peer.
 242    */
 243   uint32_t peer_id GNUNET_PACKED;
 244
 245   /**
 246    * Operation ID that is used to identify this operation.
 247    */
 248   uint64_t operation_id GNUNET_PACKED;
 249
 250   /* followed by serialized peer configuration;
 251      gzip'ed configuration file in INI format */
 252
 253 };
 254
 255
 256 /**
 257  * Message sent from client to testing service to
 258  * start a peer.
 259  */
 260 struct GNUNET_TESTBED_PeerStartMessage
 261 {
 262
 263   /**
 264    * Type is GNUNET_MESSAGE_TYPE_TESTBED_STARTPEER
 265    */
 266   struct GNUNET_MessageHeader header;
 267
 268   /**
 269    * Unique ID for the peer.
 270    */
 271   uint32_t peer_id GNUNET_PACKED;
 272
 273   /**
 274    * Operation ID that is used to identify this operation.
 275    */
 276   uint64_t operation_id GNUNET_PACKED;
 277
 278 };
 279
 280
 281 /**
 282  * Message sent from client to testing service to
 283  * stop a peer.
 284  */
 285 struct GNUNET_TESTBED_PeerStopMessage
 286 {
 287
 288   /**
 289    * Type is GNUNET_MESSAGE_TYPE_TESTBED_STOPPEER
 290    */
 291   struct GNUNET_MessageHeader header;
 292
 293   /**
 294    * Unique ID for the peer.
 295    */
 296   uint32_t peer_id GNUNET_PACKED;
 297
 298   /**
 299    * Operation ID that is used to identify this operation.
 300    */
 301   uint64_t operation_id GNUNET_PACKED;
 302
 303 };
 304
 305
 306 /**
 307  * Message sent from client to testing service to
 308  * destroy a (stopped) peer.
 309  */
 310 struct GNUNET_TESTBED_PeerDestroyMessage
 311 {
 312
 313   /**
 314    * Type is GNUNET_MESSAGE_TYPE_TESTBED_DESTROYPEER
 315    */
 316   struct GNUNET_MessageHeader header;
 317
 318   /**
 319    * Unique ID for the peer.
 320    */
 321   uint32_t peer_id GNUNET_PACKED;
 322
 323   /**
 324    * Operation ID that is used to identify this operation.
 325    */
 326   uint64_t operation_id GNUNET_PACKED;
 327
 328 };
 329
 330
 331 /**
 332  * Message sent from client to testing service to
 333  * (re)configure a "physical" link between two peers.
 334  */
 335 struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage
 336 {
 337
 338   /**
 339    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CONFIGULLINK
 340    */
 341   struct GNUNET_MessageHeader header;
 342
 343   /**
 344    * 'enum GNUNET_TESTBED_ConnectOption' of the option to change
 345    */
 346   int32_t connect_option GNUNET_PACKED;
 347
 348   /**
 349    * Unique ID for the first peer.
 350    */
 351   uint32_t peer1 GNUNET_PACKED;
 352
 353   /**
 354    * Unique ID for the second peer.
 355    */
 356   uint32_t peer2 GNUNET_PACKED;
 357
 358   /**
 359    * Operation ID that is used to identify this operation.
 360    */
 361   uint64_t operation_id GNUNET_PACKED;
 362
 363   /* followed by option-dependent variable-size values */
 364
 365 };
 366
 367
 368 /**
 369  * Message sent from client to testing service to
 370  * connect two peers.
 371  */
 372 struct GNUNET_TESTBED_OverlayConnectMessage
 373 {
 374
 375   /**
 376    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OLCONNECT
 377    */
 378   struct GNUNET_MessageHeader header;
 379
 380   /**
 381    * Unique ID for the first peer.
 382    */
 383   uint32_t peer1 GNUNET_PACKED;
 384
 385   /**
 386    * Operation ID that is used to identify this operation.
 387    */
 388   uint64_t operation_id GNUNET_PACKED;
 389
 390   /**
 391    * Unique ID for the second peer.
 392    */
 393   uint32_t peer2 GNUNET_PACKED;
 394
 395 };
 396
 397
 398 /**
 399  * Event notification from a controller to a client.
 400  */
 401 struct GNUNET_TESTBED_PeerEventMessage
 402 {
 403
 404   /**
 405    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEEREVENT
 406    */
 407   struct GNUNET_MessageHeader header;
 408
 409   /**
 410    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 411    * either GNUNET_TESTBED_ET_PEER_START or GNUNET_TESTBED_ET_PEER_STOP.
 412    */
 413   int32_t event_type GNUNET_PACKED;
 414
 415   /**
 416    * Host where the peer is running.
 417    */
 418   uint32_t host_id GNUNET_PACKED;
 419
 420   /**
 421    * Peer that was started or stopped.
 422    */
 423   uint32_t peer_id GNUNET_PACKED;
 424
 425   /**
 426    * Operation ID that is used to identify this operation.
 427    */
 428   uint64_t operation_id GNUNET_PACKED;
 429
 430 };
 431
 432
 433 /**
 434  * Event notification from a controller to a client.
 435  */
 436 struct GNUNET_TESTBED_ConnectionEventMessage
 437 {
 438
 439   /**
 440    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEERCONEVENT
 441    */
 442   struct GNUNET_MessageHeader header;
 443
 444   /**
 445    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 446    * either GNUNET_TESTBED_ET_CONNECT or GNUNET_TESTBED_ET_DISCONNECT.
 447    */
 448   int32_t event_type GNUNET_PACKED;
 449
 450   /**
 451    * First peer.
 452    */
 453   uint32_t peer1 GNUNET_PACKED;
 454
 455   /**
 456    * Second peer.
 457    */
 458   uint32_t peer2 GNUNET_PACKED;
 459
 460   /**
 461    * Operation ID that is used to identify this operation.
 462    */
 463   uint64_t operation_id GNUNET_PACKED;
 464
 465 };
 466
 467
 468 /**
 469  * Event notification from a controller to a client.
 470  */
 471 struct GNUNET_TESTBED_OperationFailureEventMessage
 472 {
 473
 474   /**
 475    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OPERATIONEVENT
 476    */
 477   struct GNUNET_MessageHeader header;
 478
 479   /**
 480    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 481    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 482    */
 483   int32_t event_type GNUNET_PACKED;
 484
 485   /**
 486    * Operation ID of the operation that created this event.
 487    */
 488   uint64_t operation_id GNUNET_PACKED;
 489
 490   /* followed by 0-terminated error message */
 491
 492 };
 493
 494
 495 /**
 496  * Event notification from a controller to a client.
 497  */
 498 struct GNUNET_TESTBED_PeerCreateSuccessEventMessage
 499 {
 500
 501   /**
 502    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEERCREATESUCCESS
 503    */
 504   struct GNUNET_MessageHeader header;
 505
 506   /**
 507    * Peer identity of the peer that was created.
 508    */
 509   uint32_t peer_id GNUNET_PACKED;
 510
 511   /**
 512    * Operation ID of the operation that created this event.
 513    */
 514   uint64_t operation_id GNUNET_PACKED;
 515
 516 };
 517
 518
 519 /**
 520  * Event notification from a controller to a client for
 521  * a generic operational success where the operation does
 522  * not return any data.
 523  */
 524 struct GNUNET_TESTBED_GenericOperationSuccessEventMessage
 525 {
 526
 527   /**
 528    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GENERICOPSUCCESS
 529    */
 530   struct GNUNET_MessageHeader header;
 531
 532   /**
 533    * 'enum GNUNET_TESTBED_EventType' (in NBO);
 534    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
 535    */
 536   int32_t event_type GNUNET_PACKED;
 537
 538   /**
 539    * Operation ID of the operation that created this event.
 540    */
 541   uint64_t operation_id GNUNET_PACKED;
 542
 543 };
 544
 545
 546
 547
 548 /**
 549  * Message sent from client to testing service to
 550  * obtain the configuration of a peer.
 551  */
 552 struct GNUNET_TESTBED_PeerGetConfigurationMessage
 553 {
 554
 555   /**
 556    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GETPEERCONFIG
 557    */
 558   struct GNUNET_MessageHeader header;
 559
 560   /**
 561    * Unique ID for the peer.
 562    */
 563   uint32_t peer_id GNUNET_PACKED;
 564
 565   /**
 566    * Operation ID that is used to identify this operation.
 567    */
 568   uint64_t operation_id GNUNET_PACKED;
 569
 570 };
 571
 572
 573
 574 /**
 575  * Event notification from a controller to a client.
 576  */
 577 struct GNUNET_TESTBED_PeerConfigurationInformationMessage
 578 {
 579
 580   /**
 581    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG
 582    */
 583   struct GNUNET_MessageHeader header;
 584
 585   /**
 586    * The id of the peer relevant to this information
 587    */
 588   uint32_t peer_id GNUNET_PACKED;
 589
 590   /**
 591    * Operation ID of the operation that created this event.
 592    */
 593   uint64_t operation_id GNUNET_PACKED;
 594
 595   /**
 596    * Identity of the peer.
 597    */
 598   struct GNUNET_PeerIdentity peer_identity;
 599
 600   /**
 601    * The size of configuration when uncompressed
 602    */
 603   uint16_t config_size;
 604
 605   /* followed by gzip-compressed configuration of the peer */
 606
 607 };
 608
 609
 610 #endif