src/ats/test_ats_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010-2015 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  * @file ats/test_ats_lib.h
  22  * @brief test ATS library with a generic interpreter for running ATS tests
  23  * @author Christian Grothoff
  24  */
  25 #ifndef TEST_ATS_LIB_H
  26 #define TEST_ATS_LIB_H
  27
  28 #include "gnunet_util_lib.h"
  29 #include "gnunet_ats_service.h"
  30 #include "gnunet_testing_lib.h"
  31
  32
  33 /**
  34  * Commands for the interpreter.
  35  */
  36 enum CommandCode {
  37   /**
  38    * End the test (passing).
  39    */
  40   CMD_END_PASS = 0,
  41
  42   /**
  43    * Call #GNUNET_ATS_address_add().
  44    */
  45   CMD_ADD_ADDRESS,
  46
  47   /**
  48    * Call #GNUNET_ATS_address_del().
  49    */
  50   CMD_DEL_ADDRESS,
  51
  52   /**
  53    * Wait for ATS to suggest address.
  54    */
  55   CMD_AWAIT_ADDRESS_SUGGESTION,
  56
  57   /**
  58    * Wait for ATS to suggest disconnect.
  59    */
  60   CMD_AWAIT_DISCONNECT_SUGGESTION,
  61
  62   /**
  63    * Ask ATS to connect to a peer, using
  64    * #GNUNET_ATS_connectivity_suggest().
  65    */
  66   CMD_REQUEST_CONNECTION_START,
  67
  68   /**
  69    * Tell ATS we no longer need a connection to a peer, using
  70    * #GNUNET_ATS_connectivity_suggest_cancel().
  71    */
  72   CMD_REQUEST_CONNECTION_STOP,
  73
  74   /**
  75    * Wait for certain address information to be provided.
  76    */
  77   CMD_AWAIT_ADDRESS_INFORMATION,
  78
  79   /**
  80    * Update properties of an address, using
  81    * #GNUNET_ATS_address_update().
  82    */
  83   CMD_UPDATE_ADDRESS,
  84
  85   /**
  86    * Add session to an address, using
  87    * #GNUNET_ATS_address_add_session().
  88    */
  89   CMD_ADD_SESSION,
  90
  91   /**
  92    * Remove session from an address, using
  93    * #GNUNET_ATS_address_del_session().
  94    */
  95   CMD_DEL_SESSION,
  96
  97   /**
  98    * Change performance preferences for a peer, testing
  99    * #GNUNET_ATS_performance_change_preference().
 100    */
 101   CMD_CHANGE_PREFERENCE,
 102
 103   /**
 104    * Provide allocation quality feedback, testing
 105    * #GNUNET_ATS_performance_give_feedback().
 106    */
 107   CMD_PROVIDE_FEEDBACK,
 108
 109   /**
 110    * Obtain list of all addresses, testing
 111    * #GNUNET_ATS_performance_list_addresses().
 112    */
 113   CMD_LIST_ADDRESSES,
 114
 115   /**
 116    * Reserve bandwidth, testing
 117    * #GNUNET_ATS_reserve_bandwidth().
 118    */
 119   CMD_RESERVE_BANDWIDTH,
 120
 121   /**
 122    * Wait for a bit.
 123    */
 124   CMD_SLEEP
 125 };
 126
 127
 128 /**
 129  * Details for the #CMD_ADD_ADDRESS command.
 130  */
 131 struct CommandAddAddress {
 132   /**
 133    * Number of the peer (used to generate PID).
 134    */
 135   unsigned int pid;
 136
 137   /**
 138    * Number of the address (used to generate binary address).
 139    */
 140   unsigned int addr_num;
 141
 142   /**
 143    * Session to supply, 0 for NULL.
 144    */
 145   unsigned int session;
 146
 147   /**
 148    * Flags to set for the address.
 149    */
 150   enum GNUNET_HELLO_AddressInfo addr_flags;
 151
 152   /**
 153    * Performance properties to supply.
 154    */
 155   struct GNUNET_ATS_Properties properties;
 156
 157   /**
 158    * Expect the operation to fail (duplicate).
 159    */
 160   int expect_fail;
 161
 162   /**
 163    * Here the result of the add address operation will be stored.
 164    */
 165   struct GNUNET_ATS_AddressRecord *ar;
 166 };
 167
 168
 169 /**
 170  * Details for the #CMD_DEL_ADDRESS command.
 171  */
 172 struct CommandDelAddress {
 173   /**
 174    * Label of the corresponding #CMD_ADD_ADDRESS that
 175    * we are now to remove.
 176    */
 177   const char *add_label;
 178 };
 179
 180
 181 /**
 182  * Details for the #CMD_AWAIT_ADDRESS_SUGGESTION command.
 183  */
 184 struct CommandAwaitAddressSuggestion {
 185   /**
 186    * For which peer do we expect a suggestion?
 187    */
 188   unsigned int pid;
 189
 190   /**
 191    * If we expect the address suggested to match a particular
 192    * addition, specify the label of the add operation here. Otherwise
 193    * use NULL for "any" available address.
 194    */
 195   const char *add_label;
 196 };
 197
 198
 199 /**
 200  * Details for the #CMD_AWAIT_DISCONNECT_SUGGESTION command.
 201  */
 202 struct CommandAwaitDisconnectSuggestion {
 203   /**
 204    * For which peer do we expect the disconnect?
 205    */
 206   unsigned int pid;
 207 };
 208
 209
 210 /**
 211  * Details for the #CMD_REQUEST_CONNECTION_START command.
 212  */
 213 struct CommandRequestConnectionStart {
 214   /**
 215    * Identity of the peer we would like to connect to.
 216    */
 217   unsigned int pid;
 218
 219   /**
 220    * Location where we store the handle returned from
 221    * #GNUNET_ATS_connectivity_suggest().
 222    */
 223   struct GNUNET_ATS_ConnectivitySuggestHandle *csh;
 224 };
 225
 226
 227 /**
 228  * Details for the #CMD_REQUEST_CONNECTION_STOP command.
 229  */
 230 struct CommandRequestConnectionStop {
 231   /**
 232    * Label of the corresponding #CMD_REQUEST_CONNECTION_START that
 233    * we are now stopping.
 234    */
 235   const char *connect_label;
 236 };
 237
 238
 239 /**
 240  * Details for the #CMD_AWAIT_ADDRESS_INFORMATION command.
 241  */
 242 struct CommandAwaitAddressInformation {
 243   /**
 244    * For which address do we expect information?
 245    * The address is identified by the respective
 246    * label of the corresponding add operation.
 247    */
 248   const char *add_label;
 249
 250   /**
 251    * Label of a possible update operation that may
 252    * have modified the properties.  NULL to use
 253    * the properties from the @e add_label.
 254    */
 255   const char *update_label;
 256 };
 257
 258
 259 /**
 260  * Details for the #CMD_UPDATE_ADDRESS command.
 261  */
 262 struct CommandUpdateAddress {
 263   /**
 264    * Label of the addresses's add operation.
 265    */
 266   const char *add_label;
 267
 268   /**
 269    * Performance properties to supply.
 270    */
 271   struct GNUNET_ATS_Properties properties;
 272 };
 273
 274
 275 /**
 276  * Details for the #CMD_ADD_SESSION command.
 277  */
 278 struct CommandAddSession {
 279   /**
 280    * Label of the addresses's add operation.
 281    */
 282   const char *add_label;
 283
 284   /**
 285    * Session to supply.
 286    */
 287   unsigned int session;
 288 };
 289
 290
 291 /**
 292  * Details for the #CMD_DEL_SESSION command.
 293  */
 294 struct CommandDelSession {
 295   /**
 296    * Label of the addresses's add operation.
 297    */
 298   const char *add_session_label;
 299 };
 300
 301
 302 /**
 303  * Details for the #CMD_CHANGE_PREFERENCE command.
 304  */
 305 struct CommandChangePreference {
 306   /**
 307    * Identity of the peer we have a preference change towards.
 308    */
 309   unsigned int pid;
 310
 311   /* FIXME: preference details! */
 312 };
 313
 314
 315 /**
 316  * Details for the #CMD_PROVIDE_FEEDBACK command.
 317  */
 318 struct CommandProvideFeedback {
 319   /**
 320    * Identity of the peer we have a feedback for.
 321    */
 322   unsigned int pid;
 323
 324   /**
 325    * Over which timeframe does the feedback apply?
 326    */
 327   struct GNUNET_TIME_Relative scope;
 328
 329   /* FIXME: feedback details! */
 330 };
 331
 332
 333 /**
 334  * Details for the #CMD_LIST_ADDRESSES command.
 335  */
 336 struct CommandListAddresses {
 337   /**
 338    * Identity of the peer we want a list for.
 339    */
 340   unsigned int pid;
 341
 342   /**
 343    * All addresses or just active?
 344    */
 345   int all;
 346
 347   /**
 348    * Minimum number of addresses the callback may report.
 349    */
 350   unsigned int min_calls;
 351
 352   /**
 353    * Maximum number of addresses the callback may report.
 354    */
 355   unsigned int max_calls;
 356
 357   /**
 358    * Minimum number of active addresses the callback may report.
 359    */
 360   unsigned int min_active_calls;
 361
 362   /**
 363    * Maximum number of active addresses the callback may report.
 364    */
 365   unsigned int max_active_calls;
 366
 367   /**
 368    * Number of calls the command invoked the callback with
 369    * an address marked as active. (Set by command).
 370    */
 371   unsigned int active_calls;
 372
 373   /**
 374    * Number of calls the command invoked the callback with
 375    * any address marked as available to ATS. (Set by command).
 376    */
 377   unsigned int calls;
 378
 379   /**
 380    * Location where we store the return value from
 381    * #GNUNET_ATS_performance_list_addresses().
 382    */
 383   struct GNUNET_ATS_AddressListHandle *alh;
 384 };
 385
 386
 387 /**
 388  * Details for the #CMD_RESERVE_BANDWIDTH command.
 389  */
 390 struct CommandReserveBandwidth {
 391   /**
 392    * For which peer do we reserve bandwidth?
 393    */
 394   unsigned int pid;
 395
 396   /**
 397    * How much should we try to reserve?
 398    */
 399   int32_t amount;
 400
 401   /**
 402    * Should we expect this to work or fail?
 403    * #GNUNET_YES: must work
 404    * #GNUNET_NO: may work or fail
 405    * #GNUNET_SYSERR: must fail
 406    */
 407   int expected_result;
 408
 409   /**
 410    * Location where we store the return value from
 411    * #GNUNET_ATS_reserve_bandwidth().
 412    */
 413   struct GNUNET_ATS_ReservationContext *rc;
 414 };
 415
 416
 417 /**
 418  * Details for the #CMD_SLEEP command.
 419  */
 420 struct CommandSleep {
 421   /**
 422    * How long should we wait before running the next command?
 423    */
 424   struct GNUNET_TIME_Relative delay;
 425 };
 426
 427
 428 /**
 429  * A command for the test case interpreter.
 430  */
 431 struct Command {
 432   /**
 433    * Command code to run.
 434    */
 435   enum CommandCode code;
 436
 437   /**
 438    * Commands can be given a label so we can reference them later.
 439    */
 440   const char *label;
 441
 442   /**
 443    * Additional arguments to commands, if any.
 444    */
 445   union {
 446     struct CommandAddAddress add_address;
 447
 448     struct CommandDelAddress del_address;
 449
 450     struct CommandAwaitAddressSuggestion await_address_suggestion;
 451
 452     struct CommandAwaitDisconnectSuggestion await_disconnect_suggestion;
 453
 454     struct CommandRequestConnectionStart request_connection_start;
 455
 456     struct CommandRequestConnectionStop request_connection_stop;
 457
 458     struct CommandAwaitAddressInformation await_address_information;
 459
 460     struct CommandUpdateAddress update_address;
 461
 462     struct CommandAddSession add_session;
 463
 464     struct CommandDelSession del_session;
 465
 466     struct CommandChangePreference change_preference;
 467
 468     struct CommandProvideFeedback provide_feedback;
 469
 470     struct CommandListAddresses list_addresses;
 471
 472     struct CommandReserveBandwidth reserve_bandwidth;
 473
 474     struct CommandSleep sleep;
 475   } details;
 476 };
 477
 478
 479 /**
 480  * Run ATS test.
 481  *
 482  * @param argc length of @a argv
 483  * @param argv command line
 484  * @param cmds commands to run with the interpreter
 485  * @param timeout how long is the test allowed to take?
 486  * @return 0 on success
 487  */
 488 int
 489 TEST_ATS_run(int argc,
 490              char *argv[],
 491              struct Command *cmds,
 492              struct GNUNET_TIME_Relative timeout);
 493
 494 #endif