src/testbed/testbed_api.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008--2013 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_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_testbed_service.h"
  31 #include "testbed.h"
  32 #include "testbed_helper.h"
  33
  34 /**
  35  * Testbed Helper binary name
  36  */
  37 #define HELPER_TESTBED_BINARY "gnunet-helper-testbed"
  38
  39
  40 /**
  41  * Enumeration of operations
  42  */
  43 enum OperationType
  44 {
  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  * The message queue for sending messages to the controller service
 109  */
 110 struct MessageQueue;
 111
 112
 113 /**
 114  * Enumeration of states of OperationContext
 115  */
 116 enum OperationContextState
 117 {
 118     /**
 119      * The initial state where the associated operation has just been created
 120      * and is waiting in the operation queues to be started
 121      */
 122   OPC_STATE_INIT = 0,
 123
 124     /**
 125      * The operation has been started. It may occupy some resources which are to
 126      * be freed if cancelled.
 127      */
 128   OPC_STATE_STARTED,
 129
 130     /**
 131      * The operation has finished. The end results of this operation may occupy
 132      * some resources which are to be freed by operation_done
 133      */
 134   OPC_STATE_FINISHED
 135 };
 136
 137
 138 /**
 139  * Context information for GNUNET_TESTBED_Operation
 140  */
 141 struct OperationContext
 142 {
 143   /**
 144    * The controller to which this operation context belongs to
 145    */
 146   struct GNUNET_TESTBED_Controller *c;
 147
 148   /**
 149    * The operation
 150    */
 151   struct GNUNET_TESTBED_Operation *op;
 152
 153   /**
 154    * The operation closure
 155    */
 156   void *op_cls;
 157
 158   /**
 159    * Data relevant to the operation
 160    */
 161   void *data;
 162
 163   /**
 164    * The id of the opearation
 165    */
 166   uint64_t id;
 167
 168   /**
 169    * The type of operation
 170    */
 171   enum OperationType type;
 172
 173   /**
 174    * The state of the operation
 175    */
 176   enum OperationContextState state;
 177 };
 178
 179
 180 /**
 181  * Handle to interact with a GNUnet testbed controller.  Each
 182  * controller has at least one master handle which is created when the
 183  * controller is created; this master handle interacts with the
 184  * controller process, destroying it destroys the controller (by
 185  * closing stdin of the controller process).  Additionally,
 186  * controllers can interact with each other (in a P2P fashion); those
 187  * links are established via TCP/IP on the controller's service port.
 188  */
 189 struct GNUNET_TESTBED_Controller
 190 {
 191   /**
 192    * The host where the controller is running
 193    */
 194   struct GNUNET_TESTBED_Host *host;
 195
 196   /**
 197    * The controller callback
 198    */
 199   GNUNET_TESTBED_ControllerCallback cc;
 200
 201   /**
 202    * The closure for controller callback
 203    */
 204   void *cc_cls;
 205
 206   /**
 207    * The configuration to use while connecting to controller
 208    */
 209   struct GNUNET_CONFIGURATION_Handle *cfg;
 210
 211   /**
 212    * The client connection handle to the controller service
 213    */
 214   struct GNUNET_CLIENT_Connection *client;
 215
 216   /**
 217    * The head of the message queue
 218    */
 219   struct MessageQueue *mq_head;
 220
 221   /**
 222    * The tail of the message queue
 223    */
 224   struct MessageQueue *mq_tail;
 225
 226   /**
 227    * The client transmit handle
 228    */
 229   struct GNUNET_CLIENT_TransmitHandle *th;
 230
 231   /**
 232    * The host registration handle; NULL if no current registration requests are
 233    * present
 234    */
 235   struct GNUNET_TESTBED_HostRegistrationHandle *rh;
 236
 237   /**
 238    * The map of active operation contexts
 239    */
 240   struct GNUNET_CONTAINER_MultiHashMap32 *opc_map;
 241
 242   /**
 243    * Operation queue for simultaneous operations
 244    */
 245   struct OperationQueue *opq_parallel_operations;
 246
 247   /**
 248    * Operation queue for simultaneous service connections
 249    */
 250   struct OperationQueue *opq_parallel_service_connections;
 251
 252   /**
 253    * Operation queue for simultaneous topology configuration operations
 254    */
 255   struct OperationQueue *opq_parallel_topology_config_operations;
 256
 257   /**
 258    * The controller event mask
 259    */
 260   uint64_t event_mask;
 261
 262   /**
 263    * Did we start the receive loop yet?
 264    */
 265   int in_receive;
 266
 267   /**
 268    * The operation id counter. use current value and increment
 269    */
 270   uint32_t operation_counter;
 271
 272 };
 273
 274
 275 /**
 276  * Queues a message in send queue for sending to the service
 277  *
 278  * @param controller the handle to the controller
 279  * @param msg the message to queue
 280  */
 281 void
 282 GNUNET_TESTBED_queue_message_ (struct GNUNET_TESTBED_Controller *controller,
 283                                struct GNUNET_MessageHeader *msg);
 284
 285
 286 /**
 287  * Inserts the given operation context into the operation context map of the
 288  * given controller.  Creates the operation context map if one does not exist
 289  * for the controller
 290  *
 291  * @param c the controller
 292  * @param opc the operation context to be inserted
 293  */
 294 void
 295 GNUNET_TESTBED_insert_opc_ (struct GNUNET_TESTBED_Controller *c,
 296                             struct OperationContext *opc);
 297
 298
 299 /**
 300  * Removes the given operation context from the operation context map of the
 301  * given controller
 302  *
 303  * @param c the controller
 304  * @param opc the operation context to remove
 305  */
 306 void
 307 GNUNET_TESTBED_remove_opc_ (const struct GNUNET_TESTBED_Controller *c,
 308                             struct OperationContext *opc);
 309
 310
 311 /**
 312  * Compresses given configuration using zlib compress
 313  *
 314  * @param config the serialized configuration
 315  * @param size the size of config
 316  * @param xconfig will be set to the compressed configuration (memory is fresly
 317  *          allocated)
 318  * @return the size of the xconfig
 319  */
 320 size_t
 321 GNUNET_TESTBED_compress_config_ (const char *config, size_t size,
 322                                  char **xconfig);
 323
 324
 325 /**
 326  * Function to serialize and compress using zlib a configuration through a
 327  * configuration handle
 328  *
 329  * @param cfg the configuration
 330  * @param size the size of configuration when serialize.  Will be set on success.
 331  * @param xsize the sizeo of the compressed configuration.  Will be set on success.
 332  * @return the serialized and compressed configuration
 333  */
 334 char *
 335 GNUNET_TESTBED_compress_cfg_ (const struct GNUNET_CONFIGURATION_Handle *cfg,
 336                               size_t *size, size_t *xsize);
 337
 338
 339 /**
 340  * Creates a helper initialization message. This function is here because we
 341  * want to use this in testing
 342  *
 343  * @param trusted_ip the ip address of the controller which will be set as TRUSTED
 344  *          HOST(all connections form this ip are permitted by the testbed) when
 345  *          starting testbed controller at host. This can either be a single ip
 346  *          address or a network address in CIDR notation.
 347  * @param hostname the hostname of the destination this message is intended for
 348  * @param cfg the configuration that has to used to start the testbed service
 349  *          thru helper
 350  * @return the initialization message
 351  */
 352 struct GNUNET_TESTBED_HelperInit *
 353 GNUNET_TESTBED_create_helper_init_msg_ (const char *cname, const char *hostname,
 354                                         const struct GNUNET_CONFIGURATION_Handle
 355                                         *cfg);
 356
 357
 358 /**
 359  * Sends the given message as an operation. The given callback is called when a
 360  * reply for the operation is available.  Call
 361  * GNUNET_TESTBED_forward_operation_msg_cancel_() to cleanup the returned
 362  * operation context if the cc hasn't been called
 363  *
 364  * @param controller the controller to which the message has to be sent
 365  * @param operation_id the operation id of the message
 366  * @param msg the message to send
 367  * @param cc the callback to call when reply is available
 368  * @param cc_cls the closure for the above callback
 369  * @return the operation context which can be used to cancel the forwarded
 370  *           operation
 371  */
 372 struct OperationContext *
 373 GNUNET_TESTBED_forward_operation_msg_ (struct GNUNET_TESTBED_Controller
 374                                        *controller, uint64_t operation_id,
 375                                        const struct GNUNET_MessageHeader *msg,
 376                                        GNUNET_CLIENT_MessageHandler cc,
 377                                        void *cc_cls);
 378
 379 /**
 380  * Function to cancel an operation created by simply forwarding an operation
 381  * message.
 382  *
 383  * @param opc the operation context from GNUNET_TESTBED_forward_operation_msg_()
 384  */
 385 void
 386 GNUNET_TESTBED_forward_operation_msg_cancel_ (struct OperationContext *opc);
 387
 388
 389 /**
 390  * Generates configuration by uncompressing configuration in given message. The
 391  * given message should be of the following types:
 392  * GNUNET_MESSAGE_TYPE_TESTBED_PEERCONFIG,
 393  * GNUNET_MESSAGE_TYPE_TESTBED_SLAVECONFIG
 394  *
 395  * @param msg the message containing compressed configuration
 396  * @return handle to the parsed configuration
 397  */
 398 struct GNUNET_CONFIGURATION_Handle *
 399 GNUNET_TESTBED_extract_config_ (const struct GNUNET_MessageHeader *msg);
 400
 401
 402 /**
 403  * Checks the integrity of the OpeationFailureEventMessage and if good returns
 404  * the error message it contains.
 405  *
 406  * @param msg the OperationFailureEventMessage
 407  * @return the error message
 408  */
 409 const char *
 410 GNUNET_TESTBED_parse_error_string_ (const struct
 411                                     GNUNET_TESTBED_OperationFailureEventMessage
 412                                     *msg);
 413
 414
 415 /**
 416  * Function to return the operation id for a controller. The operation id is
 417  * created from the controllers host id and its internal operation counter.
 418  *
 419  * @param controller the handle to the controller whose operation id has to be incremented
 420  * @return the incremented operation id.
 421  */
 422 uint64_t
 423 GNUNET_TESTBED_get_next_op_id (struct GNUNET_TESTBED_Controller *controller);
 424
 425
 426 /**
 427  * Like GNUNET_TESTBED_get_slave_config(), however without the host registration
 428  * check. Another difference is that this function takes the id of the slave
 429  * host.
 430  *
 431  * @param op_cls the closure for the operation
 432  * @param master the handle to master controller
 433  * @param slave_host_id id of the host where the slave controller is running to
 434  *          the slave_host should remain valid until this operation is cancelled
 435  *          or marked as finished
 436  * @return the operation handle;
 437  */
 438 struct GNUNET_TESTBED_Operation *
 439 GNUNET_TESTBED_get_slave_config_ (void *op_cls,
 440                                   struct GNUNET_TESTBED_Controller *master,
 441                                   uint32_t slave_host_id);
 442
 443
 444 /**
 445  * Same as the GNUNET_TESTBED_controller_link_2, but with ids for delegated host
 446  * and slave host
 447  *
 448  * @param op_cls the operation closure for the event which is generated to
 449  *          signal success or failure of this operation
 450  * @param master handle to the master controller who creates the association
 451  * @param delegated_host_id id of the host to which requests should be delegated
 452  * @param slave_host_id id of the host which is used to run the slave controller
 453  * @param sxcfg serialized and compressed configuration
 454  * @param sxcfg_size the size sxcfg
 455  * @param scfg_size the size of uncompressed serialized configuration
 456  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 457  *          be started by the slave controller; GNUNET_NO if the slave
 458  *          controller has to connect to the already started delegated
 459  *          controller via TCP/IP
 460  * @return the operation handle
 461  */
 462 struct GNUNET_TESTBED_Operation *
 463 GNUNET_TESTBED_controller_link_2_ (void *op_cls,
 464                                    struct GNUNET_TESTBED_Controller *master,
 465                                    uint32_t delegated_host_id,
 466                                    uint32_t slave_host_id, const char *sxcfg,
 467                                    size_t sxcfg_size, size_t scfg_size,
 468                                    int is_subordinate);
 469
 470
 471 /**
 472  * Same as the GNUNET_TESTBED_controller_link, but with ids for delegated host
 473  * and slave host
 474  *
 475  * @param op_cls the operation closure for the event which is generated to
 476  *          signal success or failure of this operation
 477  * @param master handle to the master controller who creates the association
 478  * @param delegated_host_id id of the host to which requests should be
 479  *          delegated; cannot be NULL
 480  * @param slave_host_id id of the host which should connect to controller
 481  *          running on delegated host ; use NULL to make the master controller
 482  *          connect to the delegated host
 483  * @param slave_cfg configuration to use for the slave controller
 484  * @param is_subordinate GNUNET_YES if the controller at delegated_host should
 485  *          be started by the slave controller; GNUNET_NO if the slave
 486  *          controller has to connect to the already started delegated
 487  *          controller via TCP/IP
 488  * @return the operation handle
 489  */
 490 struct GNUNET_TESTBED_Operation *
 491 GNUNET_TESTBED_controller_link_ (void *op_cls,
 492                                  struct GNUNET_TESTBED_Controller *master,
 493                                  uint32_t delegated_host_id,
 494                                  uint32_t slave_host_id,
 495                                  const struct GNUNET_CONFIGURATION_Handle
 496                                  *slave_cfg, int is_subordinate);
 497
 498
 499
 500
 501 #endif
 502 /* end of testbed_api.h */