src/testbed/testbed_api.h

   1 /*
   2       This file is part of GNUnet
   3       Copyright (C) 2008--2013 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      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @file testbed/testbed_api.h
  23  * @brief Interface for functions internally exported from testbed_api.c
  24  * @author Sree Harsha Totakura
  25  */
  26
  27 #ifndef TESTBED_API_H
  28 #define TESTBED_API_H
  29
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_testbed_service.h"
  32 #include "testbed.h"
  33 #include "testbed_helper.h"
  34
  35 /**
  36  * Testbed Helper binary name
  37  */
  38 #define HELPER_TESTBED_BINARY "gnunet-helper-testbed"
  39
  40
  41 /**
  42  * Enumeration of operations
  43  */
  44 enum OperationType {
  45   /**
  46    * Peer create operation
  47    */
  48   OP_PEER_CREATE,
  49
  50   /**
  51    * Peer start operation
  52    */
  53   OP_PEER_START,
  54
  55   /**
  56    * Peer stop operation
  57    */
  58   OP_PEER_STOP,
  59
  60   /**
  61    * Peer destroy operation
  62    */
  63   OP_PEER_DESTROY,
  64
  65   /**
  66    * Get peer information operation
  67    */
  68   OP_PEER_INFO,
  69
  70   /**
  71    * Reconfigure a peer
  72    */
  73   OP_PEER_RECONFIGURE,
  74
  75   /**
  76    * Overlay connection operation
  77    */
  78   OP_OVERLAY_CONNECT,
  79
  80   /**
  81    * Forwarded operation
  82    */
  83   OP_FORWARDED,
  84
  85   /**
  86    * Link controllers operation
  87    */
  88   OP_LINK_CONTROLLERS,
  89
  90   /**
  91    * Get slave config operation
  92    */
  93   OP_GET_SLAVE_CONFIG,
  94
  95   /**
  96    * Stop and destroy all peers
  97    */
  98   OP_SHUTDOWN_PEERS,
  99
 100   /**
 101    * Start/stop service at a peer
 102    */
 103   OP_MANAGE_SERVICE
 104 };
 105
 106
 107
 108 /**
 109  * Enumeration of states of OperationContext
 110  */
 111 enum OperationContextState {
 112   /**
 113    * The initial state where the associated operation has just been created
 114    * and is waiting in the operation queues to be started
 115    */
 116   OPC_STATE_INIT = 0,
 117
 118   /**
 119    * The operation has been started. It may occupy some resources which are to
 120    * be freed if cancelled.
 121    */
 122   OPC_STATE_STARTED,
 123
 124   /**
 125    * The operation has finished. The end results of this operation may occupy
 126    * some resources which are to be freed by operation_done
 127    */
 128   OPC_STATE_FINISHED
 129 };
 130
 131
 132 /**
 133  * Context information for GNUNET_TESTBED_Operation
 134  */
 135 struct OperationContext {
 136   /**
 137    * The controller to which this operation context belongs to
 138    */
 139   struct GNUNET_TESTBED_Controller *c;
 140
 141   /**
 142    * The operation
 143    */
 144   struct GNUNET_TESTBED_Operation *op;
 145
 146   /**
 147    * The operation closure
 148    */
 149   void *op_cls;
 150
 151   /**
 152    * Data relevant to the operation
 153    */
 154   void *data;
 155
 156   /**
 157    * The id of the opearation
 158    */
 159   uint64_t id;
 160
 161   /**
 162    * The type of operation
 163    */
 164   enum OperationType type;
 165
 166   /**
 167    * The state of the operation
 168    */
 169   enum OperationContextState state;
 170 };
 171
 172
 173 /**
 174  * Operation empty callback
 175  *
 176  * @param cls closure
 177  */
 178 typedef void
 179 (*TESTBED_opcq_empty_cb) (void *cls);
 180
 181
 182 /**
 183  * Handle to interact with a GNUnet testbed controller.  Each
 184  * controller has at least one master handle which is created when the
 185  * controller is created; this master handle interacts with the
 186  * controller process, destroying it destroys the controller (by
 187  * closing stdin of the controller process).  Additionally,
 188  * controllers can interact with each other (in a P2P fashion); those
 189  * links are established via TCP/IP on the controller's service port.
 190  */
 191 struct GNUNET_TESTBED_Controller {
 192   /**
 193    * The host where the controller is running
 194    */
 195   struct GNUNET_TESTBED_Host *host;
 196
 197   /**
 198    * The controller callback
 199    */
 200   GNUNET_TESTBED_ControllerCallback cc;
 201
 202   /**
 203    * The closure for controller callback
 204    */
 205   void *cc_cls;
 206
 207   /**
 208    * The configuration to use while connecting to controller
 209    */
 210   struct GNUNET_CONFIGURATION_Handle *cfg;
 211
 212   /**
 213    * The message queue to the controller service
 214    */
 215   struct GNUNET_MQ_Handle *mq;
 216
 217   /**
 218    * The host registration handle; NULL if no current registration requests are
 219    * present
 220    */
 221   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 222
 223   /**
 224    * The map of active operation contexts
 225    */
 226   struct GNUNET_CONTAINER_MultiHashMap32 *opc_map;
 227
 228   /**
 229    * If this callback is not NULL, schedule it as a task when opc_map gets empty
 230    */
 231   TESTBED_opcq_empty_cb opcq_empty_cb;
 232
 233   /**
 234    * Closure for the above task
 235    */
 236   void *opcq_empty_cls;
 237
 238   /**
 239    * Operation queue for simultaneous operations
 240    */
 241   struct OperationQueue *opq_parallel_operations;
 242
 243   /**
 244    * Operation queue for simultaneous service connections
 245    */
 246   struct OperationQueue *opq_parallel_service_connections;
 247
 248   /**
 249    * Operation queue for simultaneous topology configuration operations
 250    */
 251   struct OperationQueue *opq_parallel_topology_config_operations;
 252
 253   /**
 254    * handle for hashtable of barrier handles, values are
 255    * of type `struct GNUNET_TESTBED_Barrier`.
 256    */
 257   struct GNUNET_CONTAINER_MultiHashMap *barrier_map;
 258
 259   /**
 260    * The controller event mask
 261    */
 262   uint64_t event_mask;
 263
 264   /**
 265    * The operation id counter. use current value and increment
 266    */
 267   uint32_t operation_counter;
 268 };
 269
 270
 271 /**
 272  * Handle for barrier
 273  */
 274 struct GNUNET_TESTBED_Barrier {
 275   /**
 276    * hashcode identifying this barrier in the hashmap
 277    */
 278   struct GNUNET_HashCode key;
 279
 280   /**
 281    * The controller handle given while initiliasing this barrier
 282    */
 283   struct GNUNET_TESTBED_Controller *c;
 284
 285   /**
 286    * The name of the barrier
 287    */
 288   char *name;
 289
 290   /**
 291    * The continuation callback to call when we have a status update on this
 292    */
 293   GNUNET_TESTBED_barrier_status_cb cb;
 294
 295   /**
 296    * the closure for the above callback
 297    */
 298   void *cls;
 299
 300   /**
 301    * Should the barrier crossed status message be echoed back to the controller?
 302    */
 303   int echo;
 304 };
 305
 306
 307
 308 /**
 309  * Queues a message in send queue for sending to the service
 310  *
 311  * @param controller the handle to the controller
 312  * @param msg the message to queue
 313  * @deprecated
 314  */
 315 void
 316 GNUNET_TESTBED_queue_message_(struct GNUNET_TESTBED_Controller *controller,
 317                               struct GNUNET_MessageHeader *msg);
 318
 319
 320 /**
 321  * Inserts the given operation context into the operation context map of the
 322  * given controller.  Creates the operation context map if one does not exist
 323  * for the controller
 324  *
 325  * @param c the controller
 326  * @param opc the operation context to be inserted
 327  */
 328 void
 329 GNUNET_TESTBED_insert_opc_(struct GNUNET_TESTBED_Controller *c,
 330                            struct OperationContext *opc);
 331
 332
 333 /**
 334  * Removes the given operation context from the operation context map of the
 335  * given controller
 336  *
 337  * @param c the controller
 338  * @param opc the operation context to remove
 339  */
 340 void
 341 GNUNET_TESTBED_remove_opc_(const struct GNUNET_TESTBED_Controller *c,
 342                            struct OperationContext *opc);
 343
 344
 345 /**
 346  * Compresses given configuration using zlib compress
 347  *
 348  * @param config the serialized configuration
 349  * @param size the size of config
 350  * @param xconfig will be set to the compressed configuration (memory is fresly
 351  *          allocated)
 352  * @return the size of the xconfig
 353  */
 354 size_t
 355 GNUNET_TESTBED_compress_config_(const char *config,
 356                                 size_t size,
 357                                 char **xconfig);
 358
 359
 360 /**
 361  * Function to serialize and compress using zlib a configuration through a
 362  * configuration handle
 363  *
 364  * @param cfg the configuration
 365  * @param size the size of configuration when serialize.  Will be set on success.
 366  * @param xsize the sizeo of the compressed configuration.  Will be set on success.
 367  * @return the serialized and compressed configuration
 368  */
 369 char *
 370 GNUNET_TESTBED_compress_cfg_(const struct GNUNET_CONFIGURATION_Handle *cfg,
 371                              size_t *size,
 372                              size_t *xsize);
 373
 374
 375 /**
 376  * Creates a helper initialization message. This function is here because we
 377  * want to use this in testing
 378  *
 379  * @param trusted_ip the ip address of the controller which will be set as TRUSTED
 380  *          HOST(all connections form this ip are permitted by the testbed) when
 381  *          starting testbed controller at host. This can either be a single ip
 382  *          address or a network address in CIDR notation.
 383  * @param hostname the hostname of the destination this message is intended for
 384  * @param cfg the configuration that has to used to start the testbed service
 385  *          thru helper
 386  * @return the initialization message
 387  */
 388 struct GNUNET_TESTBED_HelperInit *
 389 GNUNET_TESTBED_create_helper_init_msg_(const char *cname,
 390                                        const char *hostname,
 391                                        const struct GNUNET_CONFIGURATION_Handle *cfg);
 392
 393
 394 /**
 395  * Sends the given message as an operation. The given callback is called when a
 396  * reply for the operation is available.  Call
 397  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 398  * operation context if the cc hasn't been called
 399  *
 400  * @param controller the controller to which the message has to be sent
 401  * @param operation_id the operation id of the message
 402  * @param msg the message to send
 403  * @param cc the callback to call when reply is available
 404  * @param cc_cls the closure for the above callback
 405  * @return the operation context which can be used to cancel the forwarded
 406  *           operation
 407  */
 408 struct OperationContext *
 409 GNUNET_TESTBED_forward_operation_msg_(struct GNUNET_TESTBED_Controller *controller,
 410                                       uint64_t operation_id,
 411                                       const struct GNUNET_MessageHeader *msg,
 412                                       GNUNET_MQ_MessageCallback cc,
 413                                       void *cc_cls);
 414
 415 /**
 416  * Function to cancel an operation created by simply forwarding an operation
 417  * message.
 418  *
 419  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 420  */
 421 void
 422 GNUNET_TESTBED_forward_operation_msg_cancel_(struct OperationContext *opc);
 423
 424
 425 /**
 426  * Generates configuration by uncompressing configuration in given message. The
 427  * given message should be of the following types:
 428  * #GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG,
 429  * #GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG
 430  *
 431  * @param msg the message containing compressed configuration
 432  * @return handle to the parsed configuration
 433  */
 434 struct GNUNET_CONFIGURATION_Handle *
 435 GNUNET_TESTBED_extract_config_(const struct GNUNET_MessageHeader *msg);
 436
 437
 438 /**
 439  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 440  * the error message it contains.
 441  *
 442  * @param msg the OperationFailureEventMessage
 443  * @return the error message
 444  */
 445 const char *
 446 GNUNET_TESTBED_parse_error_string_(const struct GNUNET_TESTBED_OperationFailureEventMessage *msg);
 447
 448
 449 /**
 450  * Function to return the operation id for a controller. The operation id is
 451  * created from the controllers host id and its internal operation counter.
 452  *
 453  * @param controller the handle to the controller whose operation id has to be incremented
 454  * @return the incremented operation id.
 455  */
 456 uint64_t
 457 GNUNET_TESTBED_get_next_op_id(struct GNUNET_TESTBED_Controller *controller);
 458
 459
 460 /**
 461  * Like GNUNET_TESTBED_get_slave_config(), however without the host registration
 462  * check. Another difference is that this function takes the id of the slave
 463  * host.
 464  *
 465  * @param op_cls the closure for the operation
 466  * @param master the handle to master controller
 467  * @param slave_host_id id of the host where the slave controller is running to
 468  *          the slave_host should remain valid until this operation is cancelled
 469  *          or marked as finished
 470  * @return the operation handle;
 471  */
 472 struct GNUNET_TESTBED_Operation *
 473 GNUNET_TESTBED_get_slave_config_(void *op_cls,
 474                                  struct GNUNET_TESTBED_Controller *master,
 475                                  uint32_t slave_host_id);
 476
 477
 478
 479 /**
 480  * Initialise a barrier and call the given callback when the required percentage
 481  * of peers (quorum) reach the barrier OR upon error.
 482  *
 483  * @param controller the handle to the controller
 484  * @param name identification name of the barrier
 485  * @param quorum the percentage of peers that is required to reach the barrier.
 486  *   Peers signal reaching a barrier by calling
 487  *   GNUNET_TESTBED_barrier_reached().
 488  * @param cb the callback to call when the barrier is reached or upon error.
 489  *   Cannot be NULL.
 490  * @param cls closure for the above callback
 491  * @param echo #GNUNET_YES to echo the barrier crossed status message back to the
 492  *   controller
 493  * @return barrier handle; NULL upon error
 494  */
 495 struct GNUNET_TESTBED_Barrier *
 496 GNUNET_TESTBED_barrier_init_(struct GNUNET_TESTBED_Controller *controller,
 497                              const char *name,
 498                              unsigned int quorum,
 499                              GNUNET_TESTBED_barrier_status_cb cb,
 500                              void *cls,
 501                              int echo);
 502
 503
 504 /**
 505  * Remove a barrier and it was the last one in the barrier hash map, destroy the
 506  * hash map
 507  *
 508  * @param barrier the barrier to remove
 509  */
 510 void
 511 GNUNET_TESTBED_barrier_remove_(struct GNUNET_TESTBED_Barrier *barrier);
 512
 513
 514
 515 #endif
 516 /* end of testbed_api.h */