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