src/include/gnunet_testing_lib.h

   1 /*
   2       This file is part of GNUnet
   3       (C) 2008, 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 2, 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 include/gnunet_testing_lib.h
  23  * @brief convenience API for writing testcases for GNUnet
  24  *        Many testcases need to start and stop gnunetd,
  25  *        and this library is supposed to make that easier
  26  *        for TESTCASES.  Normal programs should always
  27  *        use functions from gnunet_{util,arm}_lib.h.  This API is
  28  *        ONLY for writing testcases!
  29  * @author Christian Grothoff
  30  */
  31
  32 #ifndef GNUNET_TESTING_LIB_H
  33 #define GNUNET_TESTING_LIB_H
  34
  35 #include "gnunet_util_lib.h"
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #if 0                           /* keep Emacsens' auto-indent happy */
  41 }
  42 #endif
  43 #endif
  44
  45 /**
  46  * Handle for a GNUnet daemon (technically a set of
  47  * daemons; the handle is really for the master ARM
  48  * daemon) started by the testing library.
  49  */
  50 struct GNUNET_TESTING_Daemon;
  51
  52
  53 /**
  54  * Prototype of a function that will be called whenever
  55  * a daemon was started by the testing library.
  56  *
  57  * @param cls closure
  58  * @param id identifier for the daemon, NULL on error
  59  * @param cfg configuration used by this daemon
  60  * @param d handle for the daemon
  61  * @param emsg error message (NULL on success)
  62  */
  63 typedef void (*GNUNET_TESTING_NotifyDaemonRunning)(void *cls,
  64                                                    const struct GNUNET_PeerIdentity *id,
  65                                                    const struct GNUNET_CONFIGURATION_Handle *cfg,
  66                                                    struct GNUNET_TESTING_Daemon *d,
  67                                                    const char *emsg);
  68
  69
  70 /**
  71  * Handle to an entire testbed of GNUnet peers.
  72  */
  73 struct GNUNET_TESTING_Testbed;
  74
  75 /**
  76  * Phases of starting GNUnet on a system.
  77  */
  78 enum GNUNET_TESTING_StartPhase;
  79
  80
  81 /**
  82  * Handle for a GNUnet daemon (technically a set of
  83  * daemons; the handle is really for the master ARM
  84  * daemon) started by the testing library.
  85  */
  86 struct GNUNET_TESTING_Daemon
  87 {
  88   /**
  89    * Our scheduler.
  90    */
  91   struct GNUNET_SCHEDULER_Handle *sched;
  92
  93   /**
  94    * Our configuration.
  95    */
  96   struct GNUNET_CONFIGURATION_Handle *cfg;
  97
  98   /**
  99    * Host to run GNUnet on.
 100    */
 101   char *hostname;
 102
 103   /**
 104    * Result of GNUNET_i2s of this peer,
 105    * for printing
 106    */
 107   char *shortname;
 108
 109   /**
 110    * Username we are using.
 111    */
 112   char *username;
 113
 114   /**
 115    * Name of the configuration file
 116    */
 117   char *cfgfile;
 118
 119   /**
 120    * Function to call when the peer is running.
 121    */
 122   GNUNET_TESTING_NotifyDaemonRunning cb;
 123
 124   /**
 125    * Closure for cb.
 126    */
 127   void *cb_cls;
 128
 129   /**
 130    * Arguments from "daemon_stop" call.
 131    */
 132   GNUNET_TESTING_NotifyCompletion dead_cb;
 133
 134   /**
 135    * Closure for 'dead_cb'.
 136    */
 137   void *dead_cb_cls;
 138
 139   /**
 140    * Arguments from "daemon_stop" call.
 141    */
 142   GNUNET_TESTING_NotifyCompletion update_cb;
 143
 144   /**
 145    * Closure for 'update_cb'.
 146    */
 147   void *update_cb_cls;
 148
 149   /**
 150    * Identity of this peer (once started).
 151    */
 152   struct GNUNET_PeerIdentity id;
 153
 154   /**
 155    * Flag to indicate that we've already been asked
 156    * to terminate (but could not because some action
 157    * was still pending).
 158    */
 159   int dead;
 160
 161   /**
 162    * PID of the process that we started last.
 163    */
 164   pid_t pid;
 165
 166   /**
 167    * How many iterations have we been waiting for
 168    * the started process to complete?
 169    */
 170   unsigned int wait_runs;
 171
 172   /**
 173    * In which phase are we during the start of
 174    * this process?
 175    */
 176   enum GNUNET_TESTING_StartPhase phase;
 177
 178   /**
 179    * ID of the current task.
 180    */
 181   GNUNET_SCHEDULER_TaskIdentifier task;
 182
 183   /**
 184    * Handle to the server.
 185    */
 186   struct GNUNET_CORE_Handle *server;
 187
 188   /**
 189    * Handle to the transport service of this peer
 190    */
 191   struct GNUNET_TRANSPORT_Handle *th;
 192
 193   /**
 194    * HELLO message for this peer
 195    */
 196   struct GNUNET_HELLO_Message *hello;
 197 };
 198
 199
 200 /**
 201  * Handle to a group of GNUnet peers.
 202  */
 203 struct GNUNET_TESTING_PeerGroup;
 204
 205
 206 /**
 207  * Prototype of a function that will be called whenever
 208  * two daemons are connected by the testing library.
 209  *
 210  * @param cls closure
 211  * @param first peer id for first daemon
 212  * @param second peer id for the second daemon
 213  * @param first_cfg config for the first daemon
 214  * @param second_cfg config for the second daemon
 215  * @param first_daemon handle for the first daemon
 216  * @param second_daemon handle for the second daemon
 217  * @param emsg error message (NULL on success)
 218  */
 219 typedef void (*GNUNET_TESTING_NotifyConnection)(void *cls,
 220                                                    const struct GNUNET_PeerIdentity *first,
 221                                                    const struct GNUNET_PeerIdentity *second,
 222                                                    const struct GNUNET_CONFIGURATION_Handle *first_cfg,
 223                                                    const struct GNUNET_CONFIGURATION_Handle *second_cfg,
 224                                                    struct GNUNET_TESTING_Daemon *first_daemon,
 225                                                    struct GNUNET_TESTING_Daemon *second_daemon,
 226                                                    const char *emsg);
 227
 228 /**
 229  * Starts a GNUnet daemon.  GNUnet must be installed on the target
 230  * system and available in the PATH.  The machine must furthermore be
 231  * reachable via "ssh" (unless the hostname is "NULL") without the
 232  * need to enter a password.
 233  *
 234  * @param sched scheduler to use
 235  * @param cfg configuration to use
 236  * @param hostname name of the machine where to run GNUnet
 237  *        (use NULL for localhost).
 238  * @param cb function to call with the result
 239  * @param cb_cls closure for cb
 240  * @return handle to the daemon (actual start will be completed asynchronously)
 241  */
 242 struct GNUNET_TESTING_Daemon *
 243 GNUNET_TESTING_daemon_start (struct GNUNET_SCHEDULER_Handle *sched,
 244                              const struct GNUNET_CONFIGURATION_Handle *cfg,
 245                              const char *hostname,
 246                              GNUNET_TESTING_NotifyDaemonRunning cb,
 247                              void *cb_cls);
 248
 249 struct GNUNET_TESTING_Daemon *
 250 GNUNET_TESTING_daemon_get (struct GNUNET_TESTING_PeerGroup *pg, unsigned int position);
 251
 252 /**
 253  * Prototype of a function that will be called when a
 254  * particular operation was completed the testing library.
 255  *
 256  * @param cls closure
 257  * @param emsg NULL on success
 258  */
 259 typedef void (*GNUNET_TESTING_NotifyCompletion)(void *cls,
 260                                                 const char *emsg);
 261
 262
 263 /**
 264  * Stops a GNUnet daemon.
 265  *
 266  * @param d the daemon that should be stopped
 267  * @param cb function called once the daemon was stopped
 268  * @param cb_cls closure for cb
 269  */
 270 void GNUNET_TESTING_daemon_stop (struct GNUNET_TESTING_Daemon *d,
 271                                  GNUNET_TESTING_NotifyCompletion cb,
 272                                  void * cb_cls);
 273
 274
 275 /**
 276  * Changes the configuration of a GNUnet daemon.
 277  *
 278  * @param d the daemon that should be modified
 279  * @param cfg the new configuration for the daemon
 280  * @param cb function called once the configuration was changed
 281  * @param cb_cls closure for cb
 282  */
 283 void GNUNET_TESTING_daemon_reconfigure (struct GNUNET_TESTING_Daemon *d,
 284                                         struct GNUNET_CONFIGURATION_Handle *cfg,
 285                                         GNUNET_TESTING_NotifyCompletion cb,
 286                                         void * cb_cls);
 287
 288
 289 /**
 290  * Establish a connection between two GNUnet daemons.
 291  *
 292  * @param d1 handle for the first daemon
 293  * @param d2 handle for the second daemon
 294  * @param timeout how long is the connection attempt
 295  *        allowed to take?
 296  * @param max_connect_attempts how many times should we try to reconnect
 297  *        (within timeout)
 298  * @param cb function to call at the end
 299  * @param cb_cls closure for cb
 300  */
 301 void GNUNET_TESTING_daemons_connect (struct GNUNET_TESTING_Daemon *d1,
 302                                      struct GNUNET_TESTING_Daemon *d2,
 303                                      struct GNUNET_TIME_Relative timeout,
 304                                      unsigned int max_connect_attempts,
 305                                      GNUNET_TESTING_NotifyConnection cb,
 306                                      void *cb_cls);
 307
 308
 309
 310
 311 /**
 312  * Start count gnunetd processes with the same set of transports and
 313  * applications.  The port numbers (any option called "PORT") will be
 314  * adjusted to ensure that no two peers running on the same system
 315  * have the same port(s) in their respective configurations.
 316  *
 317  * @param sched scheduler to use
 318  * @param cfg configuration template to use
 319  * @param total number of daemons to start
 320  * @param cb function to call on each daemon that was started
 321  * @param cb_cls closure for cb
 322  * @param connect_callback function to call each time two hosts are connected
 323  * @param connect_callback_cls closure for connect_callback
 324  * @param hostnames space-separated list of hostnames to use,
 325  *        NULL to use localhost only
 326  * @return NULL on error, otherwise handle to control peer group
 327  */
 328 struct GNUNET_TESTING_PeerGroup *
 329 GNUNET_TESTING_daemons_start (struct GNUNET_SCHEDULER_Handle *sched,
 330                               const struct GNUNET_CONFIGURATION_Handle *cfg,
 331                               unsigned int total,
 332                               GNUNET_TESTING_NotifyDaemonRunning cb,
 333                               void *cb_cls,
 334                               GNUNET_TESTING_NotifyConnection connect_callback,
 335                               void *connect_callback_cls,
 336                               const char *hostnames);
 337
 338
 339 /**
 340  * Shutdown all peers started in the given group.
 341  *
 342  * @param pg handle to the peer group
 343  */
 344 void
 345 GNUNET_TESTING_daemons_stop (struct GNUNET_TESTING_PeerGroup *pg);
 346
 347
 348 /**
 349  * Topologies supported for testbeds.
 350  */
 351 enum GNUNET_TESTING_Topology
 352 {
 353   /**
 354    * A clique (everyone connected to everyone else).
 355    */
 356   GNUNET_TESTING_TOPOLOGY_CLIQUE,
 357
 358   /**
 359    * Small-world network (2d torus plus random links).
 360    */
 361   GNUNET_TESTING_TOPOLOGY_SMALL_WORLD,
 362
 363   /**
 364    * Small-world network (ring plus random links).
 365    */
 366   GNUNET_TESTING_TOPOLOGY_SMALL_WORLD_RING,
 367
 368   /**
 369    * Ring topology.
 370    */
 371   GNUNET_TESTING_TOPOLOGY_RING,
 372
 373   /**
 374    * 2-d torus.
 375    */
 376   GNUNET_TESTING_TOPOLOGY_2D_TORUS,
 377
 378   /**
 379    * Random graph.
 380    */
 381   GNUNET_TESTING_TOPOLOGY_ERDOS_RENYI,
 382
 383   /**
 384    * Certain percentage of peers are unable to communicate directly
 385    * replicating NAT conditions
 386    */
 387   GNUNET_TESTING_TOPOLOGY_INTERNAT,
 388
 389   /**
 390    * FIXME: implement
 391    */
 392   GNUNET_TESTING_TOPOLOGY_SCALE_FREE,
 393
 394   /**
 395    * All peers are disconnected.
 396    */
 397   GNUNET_TESTING_TOPOLOGY_NONE
 398 };
 399
 400
 401 /**
 402  * FIXME: document
 403  */
 404 int
 405 GNUNET_TESTING_create_topology (struct GNUNET_TESTING_PeerGroup *pg
 406                                 /* enum GNUNET_TESTING_Topology topo */);
 407
 408
 409 /**
 410  * Start "count" GNUnet daemons with a particular topology.
 411  *
 412  * @param sched scheduler to use
 413  * @param cfg configuration template to use
 414  * @param count number of peers the testbed should have
 415  * @param topology desired topology (enforced via F2F)
 416  * @param cb function to call on each daemon that was started
 417  * @param cb_cls closure for cb
 418  * @param hostname where to run the peers; can be NULL (to run
 419  *        everything on localhost). Additional
 420  *        hosts can be specified using a NULL-terminated list of
 421  *        varargs, hosts will then be used round-robin from that
 422  *        list.
 423  * @return handle to control the testbed
 424  */
 425 struct GNUNET_TESTING_Testbed *
 426 GNUNET_TESTING_testbed_start (struct GNUNET_SCHEDULER_Handle *sched,
 427                               const struct GNUNET_CONFIGURATION_Handle *cfg,
 428                               unsigned int count,
 429                               enum GNUNET_TESTING_Topology topology,
 430                               GNUNET_TESTING_NotifyDaemonRunning cb,
 431                               void *cb_cls,
 432                               const char *hostname,
 433                               ...);
 434
 435
 436 /**
 437  * Stop all of the daemons started with the start function.
 438  *
 439  * @param tb handle for the testbed
 440  * @param cb function to call when done
 441  * @param cb_cls closure for cb
 442  */
 443 void
 444 GNUNET_TESTING_testbed_stop (struct GNUNET_TESTING_Testbed *tb,
 445                              GNUNET_TESTING_NotifyCompletion cb,
 446                              void *cb_cls );
 447
 448
 449 /**
 450  * Simulate churn in the testbed by stopping some peers (and possibly
 451  * re-starting others if churn is called multiple times).  This
 452  * function can only be used to create leave-join churn (peers "never"
 453  * leave for good).  First "voff" random peers that are currently
 454  * online will be taken offline; then "von" random peers that are then
 455  * offline will be put back online.  No notifications will be
 456  * generated for any of these operations except for the callback upon
 457  * completion.  Note that the implementation is at liberty to keep
 458  * the ARM service itself (but none of the other services or daemons)
 459  * running even though the "peer" is being varied offline.
 460  *
 461  * @param tb handle for the testbed
 462  * @param voff number of peers that should go offline
 463  * @param von number of peers that should come back online;
 464  *            must be zero on first call (since "testbed_start"
 465  *            always starts all of the peers)
 466  * @param cb function to call at the end
 467  * @param cb_cls closure for cb
 468  */
 469 void
 470 GNUNET_TESTING_testbed_churn (struct GNUNET_TESTING_Testbed *tb,
 471                               unsigned int voff,
 472                               unsigned int von,
 473                               GNUNET_TESTING_NotifyCompletion cb,
 474                               void *cb_cls);
 475
 476
 477 #if 0                           /* keep Emacsens' auto-indent happy */
 478 {
 479 #endif
 480 #ifdef __cplusplus
 481 }
 482 #endif
 483
 484 #endif