2 This file is part of GNUnet.
3 Copyright (C) 2006, 2009, 2015, 2016 GNUnet e.V.
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.
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.
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/>.
20 * @file transport-testing.h
21 * @brief testing lib for transport service
22 * @author Matthias Wachs
23 * @author Christian Grothoff
25 #ifndef TRANSPORT_TESTING_H
26 #define TRANSPORT_TESTING_H
28 #include "gnunet_util_lib.h"
29 #include "gnunet_hello_lib.h"
30 #include "gnunet_transport_service.h"
31 #include "gnunet_transport_core_service.h"
32 #include "gnunet_transport_hello_service.h"
33 #include "gnunet_transport_manipulation_service.h"
34 #include "gnunet_testing_lib.h"
37 /* ************* Basic functions for starting/stopping/connecting *********** */
40 * Context for a single peer
42 struct GNUNET_TRANSPORT_TESTING_PeerContext;
45 * Definition for a transport testing handle
47 struct GNUNET_TRANSPORT_TESTING_Handle;
51 * Context for a single peer
53 struct GNUNET_TRANSPORT_TESTING_PeerContext
56 * Next element in the DLL
58 struct GNUNET_TRANSPORT_TESTING_PeerContext *next;
61 * Previous element in the DLL
63 struct GNUNET_TRANSPORT_TESTING_PeerContext *prev;
66 * Transport testing handle this peer belongs to
68 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
71 * Peer's configuration
73 struct GNUNET_CONFIGURATION_Handle *cfg;
76 * Peer's transport service handle
78 struct GNUNET_TRANSPORT_CoreHandle *th;
81 * Peer's transport service manipulation handle
83 struct GNUNET_TRANSPORT_ManipulationHandle *tmh;
88 struct GNUNET_ATS_ConnectivityHandle *ats;
91 * Peer's transport get hello handle to retrieve peer's HELLO message
93 struct GNUNET_TRANSPORT_HelloGetHandle *ghh;
96 * Peer's testing handle
98 struct GNUNET_TESTING_Peer *peer;
103 struct GNUNET_PeerIdentity id;
106 * Handle for the peer's ARM process
108 struct GNUNET_OS_Process *arm_proc;
113 struct GNUNET_MQ_MessageHandler *handlers;
116 * Notify connect callback
118 GNUNET_TRANSPORT_NotifyConnecT nc;
121 * Notify disconnect callback
123 GNUNET_TRANSPORT_NotifyDisconnecT nd;
126 * Startup completed callback
128 GNUNET_SCHEDULER_TaskCallback start_cb;
131 * Peers HELLO Message
133 struct GNUNET_HELLO_Message *hello;
136 * Closure for the @a nc and @a nd callbacks
141 * Closure for @e start_cb.
146 * An unique number to identify the peer
153 * Handle for a request to connect two peers.
155 struct GNUNET_TRANSPORT_TESTING_ConnectRequest
160 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *next;
165 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *prev;
168 * Peer we want to connect.
170 struct GNUNET_TRANSPORT_TESTING_PeerContext *p1;
173 * Peer we want to connect.
175 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2;
178 * Task by which we accomplish the connection.
180 struct GNUNET_SCHEDULER_Task *tct;
183 * Handle by which we ask ATS to faciliate the connection.
185 struct GNUNET_ATS_ConnectivitySuggestHandle *ats_sh;
188 * Handle by which we inform the peer about the HELLO of
191 struct GNUNET_TRANSPORT_OfferHelloHandle *oh;
194 * Function to call upon completion.
196 GNUNET_SCHEDULER_TaskCallback cb;
204 * Message queue for sending from @a p1 to @a p2.
206 struct GNUNET_MQ_Handle *mq;
209 * Set if peer1 says the connection is up to peer2.
214 * Set if peer2 says the connection is up to peer1.
219 * #GNUNET_YES if both @e p1_c and @e p2_c are #GNUNET_YES.
226 * Handle for a test run.
228 struct GNUNET_TRANSPORT_TESTING_Handle
231 * Testing library system handle
233 struct GNUNET_TESTING_System *tl_system;
236 * head DLL of connect contexts
238 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_head;
241 * head DLL of connect contexts
243 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_tail;
248 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_head;
253 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_tail;
258 * Initialize the transport testing
260 * @return transport testing handle
262 struct GNUNET_TRANSPORT_TESTING_Handle *
263 GNUNET_TRANSPORT_TESTING_init (void);
267 * Clean up the transport testing
269 * @param tth transport testing handle
272 GNUNET_TRANSPORT_TESTING_done (struct GNUNET_TRANSPORT_TESTING_Handle *tth);
276 * Start a peer with the given configuration
278 * @param tth the testing handle
279 * @param cfgname configuration file
280 * @param peer_id the peer_id
281 * @param handlers functions for receiving messages
282 * @param nc connect callback
283 * @param nd disconnect callback
284 * @param cb_cls closure for @a nc and @a nd callback
285 * @param start_cb start callback
286 * @param start_cb_cls closure for @a start_cb
287 * @return the peer context
289 struct GNUNET_TRANSPORT_TESTING_PeerContext *
290 GNUNET_TRANSPORT_TESTING_start_peer (struct GNUNET_TRANSPORT_TESTING_Handle *tth,
293 const struct GNUNET_MQ_MessageHandler *handlers,
294 GNUNET_TRANSPORT_NotifyConnecT nc,
295 GNUNET_TRANSPORT_NotifyDisconnecT nd,
297 GNUNET_SCHEDULER_TaskCallback start_cb,
302 * Shutdown the given peer
307 GNUNET_TRANSPORT_TESTING_stop_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *pc);
311 * Stops and restarts the given peer, sleeping (!) for 5s in between.
314 * @param restart_cb restart callback
315 * @param restart_cb_cls callback closure
316 * @return #GNUNET_OK in success otherwise #GNUNET_SYSERR
319 GNUNET_TRANSPORT_TESTING_restart_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
320 GNUNET_SCHEDULER_TaskCallback restart_cb,
321 void *restart_cb_cls);
326 * Connect the given peers and call the callback when both peers
327 * report the inbound connection. Remarks: start_peer's notify_connect
328 * callback can be called before.
332 * @param cb the callback to call when both peers notified that they are connected
333 * @param cls callback cls
334 * @return a connect request handle
336 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *
337 GNUNET_TRANSPORT_TESTING_connect_peers (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
338 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
339 GNUNET_SCHEDULER_TaskCallback cb,
344 * Cancel the request to connect two peers. You MUST cancel the
345 * request if you stop the peers before the peers connected
348 * @param cc a connect request handle
351 GNUNET_TRANSPORT_TESTING_connect_peers_cancel (struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
355 * Function called on matching connect requests.
358 * @param cc request matching the query
361 (*GNUNET_TRANSPORT_TESTING_ConnectContextCallback)(void *cls,
362 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
366 * Find any connecting context matching the given pair of peers.
368 * @param p1 first peer
369 * @param p2 second peer
370 * @param cb function to call
371 * @param cb_cls closure for @a cb
374 GNUNET_TRANSPORT_TESTING_find_connecting_context (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
375 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
376 GNUNET_TRANSPORT_TESTING_ConnectContextCallback cb,
380 /* ********************** high-level process functions *************** */
384 * Function called once the peers have been launched and
385 * connected by #GNUNET_TRANSPORT_TESTING_connect_check().
388 * @param num_peers size of the @a p array
389 * @param p the peers that were launched
392 (*GNUNET_TRANSPORT_TESTING_ConnectContinuation)(void *cls,
393 unsigned int num_peers,
394 struct GNUNET_TRANSPORT_TESTING_PeerContext *p[]);
398 * Internal data structure.
400 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList;
403 * Internal data structure.
405 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext;
408 GNUNET_NETWORK_STRUCT_BEGIN
409 struct GNUNET_TRANSPORT_TESTING_TestMessage
412 * Type is (usually) #GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE.
414 struct GNUNET_MessageHeader header;
417 * Monotonically increasing counter throughout the test.
419 uint32_t num GNUNET_PACKED;
421 GNUNET_NETWORK_STRUCT_END
426 * Function called by the transport for each received message.
429 * @param receiver receiver of the message
430 * @param sender sender of the message
431 * @param message the message
434 (*GNUNET_TRANSPORT_TESTING_ReceiveCallback) (void *cls,
435 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
436 const struct GNUNET_PeerIdentity *sender,
437 const struct GNUNET_TRANSPORT_TESTING_TestMessage *message);
441 * Function called to notify transport users that another
442 * peer connected to us.
445 * @param me peer experiencing the event
446 * @param other peer that connected to @a me
449 (*GNUNET_TRANSPORT_TESTING_NotifyConnect) (void *cls,
450 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
451 const struct GNUNET_PeerIdentity *other);
455 * Function called to notify transport users that another
456 * peer disconnected from us.
459 * @param me peer experiencing the event
460 * @param other peer that disconnected from @a me
463 (*GNUNET_TRANSPORT_TESTING_NotifyDisconnect) (void *cls,
464 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
465 const struct GNUNET_PeerIdentity *other);
469 * Closure that must be passed to
470 * #GNUNET_TRANSPORT_TESTING_connect_check.
472 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext
476 * How should we continue after the connect?
478 GNUNET_SCHEDULER_TaskCallback connect_continuation;
481 * Closure for @e connect_continuation.
483 void *connect_continuation_cls;
486 * Which configuration file should we pass to the
487 * #GNUNET_PROGRAM_run() of the testcase?
489 const char *config_file;
492 * Receiver argument to give for peers we start.
494 GNUNET_TRANSPORT_TESTING_ReceiveCallback rec;
497 * Notify connect argument to give for peers we start.
499 GNUNET_TRANSPORT_TESTING_NotifyConnect nc;
502 * Notify disconnect argument to give for peers we start.
504 GNUNET_TRANSPORT_TESTING_NotifyDisconnect nd;
507 * Closure for @e rec, @e nc and @e nd.
512 * Custom task to run on shutdown.
514 GNUNET_SCHEDULER_TaskCallback shutdown_task;
517 * Closure for @e shutdown_task.
519 void *shutdown_task_cls;
522 * Custom task to run after peers were started but before we try to
523 * connect them. If this function is set, we wait ONE second after
524 * running this function until we continue with connecting the
527 GNUNET_SCHEDULER_TaskCallback pre_connect_task;
530 * Closure for @e shutdown_task.
532 void *pre_connect_task_cls;
535 * When should the testcase time out?
537 struct GNUNET_TIME_Relative timeout;
540 * Should we try to create connections in both directions?
544 /* ******* fields set by #GNUNET_TRANSPORT_TESTING_connect_check **** */
547 * Number of peers involved in the test.
549 unsigned int num_peers;
552 * Configuration files we have, array with @e num_peers entries.
557 * Array with @e num_peers entries.
559 struct GNUNET_TRANSPORT_TESTING_PeerContext **p;
562 * Name of the plugin.
564 const char *test_plugin;
567 * Name of the testcase.
569 const char *test_name;
572 * Configuration object for the testcase.
574 const struct GNUNET_CONFIGURATION_Handle *cfg;
577 * Main testing handle.
579 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
582 * Result from the main function, set to #GNUNET_OK on success.
583 * Clients should set to #GNUNET_SYSERR to indicate test failure.
588 * Generator for the `num` field in test messages. Incremented each
589 * time #GNUNET_TRANSPORT_TESTING_simple_send or
590 * #GNUNET_TRANSPORT_TESTING_large_send are used to transmit a
593 uint32_t send_num_gen;
595 /* ******* internal state, clients should not mess with this **** */
598 * Task run on timeout.
600 struct GNUNET_SCHEDULER_Task *timeout_task;
603 * Task run to connect peers.
605 struct GNUNET_SCHEDULER_Task *connect_task;
608 * Number of peers that have been started.
610 unsigned int started;
613 * DLL of active connect requests.
615 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_head;
618 * DLL of active connect requests.
620 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_tail;
623 * Array with @e num_peers entries.
625 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext *ip;
631 * Find peer by peer ID.
633 * @param ccc context to search
634 * @param peer peer to look for
635 * @return NULL if @a peer was not found
637 struct GNUNET_TRANSPORT_TESTING_PeerContext *
638 GNUNET_TRANSPORT_TESTING_find_peer (struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc,
639 const struct GNUNET_PeerIdentity *peer);
643 * Common implementation of the #GNUNET_TRANSPORT_TESTING_CheckCallback.
644 * Starts and connects the two peers, then invokes the
645 * `connect_continuation` from @a cls. Sets up a timeout to
646 * abort the test, and a shutdown handler to clean up properly
649 * @param cls closure of type `struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext`
650 * @param tth_ initialized testing handle
651 * @param test_plugin_ name of the plugin
652 * @param test_name_ name of the test
653 * @param num_peers number of entries in the @a cfg_file array
654 * @param cfg_files array of names of configuration files for the peers
655 * @return #GNUNET_SYSERR on error
658 GNUNET_TRANSPORT_TESTING_connect_check (void *cls,
659 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
660 const char *test_plugin_,
661 const char *test_name_,
662 unsigned int num_peers,
667 * Main function of a testcase. Called with the initial setup data
668 * for the test as derived from the source name and the binary name.
671 * @param tth_ initialized testing handle
672 * @param test_plugin_ name of the plugin
673 * @param test_name_ name of the test
674 * @param num_peers number of entries in the @a cfg_file array
675 * @param cfg_files array of names of configuration files for the peers
676 * @return #GNUNET_SYSERR on error
679 (*GNUNET_TRANSPORT_TESTING_CheckCallback)(void *cls,
680 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
681 const char *test_plugin_,
682 const char *test_name_,
683 unsigned int num_peers,
688 * Setup testcase. Calls @a check with the data the test needs.
690 * @param argv0 binary name (argv[0])
691 * @param filename source file name (__FILE__)
692 * @param num_peers number of peers to start
693 * @param check main function to run
694 * @param check_cls closure for @a check
695 * @return #GNUNET_OK on success
698 GNUNET_TRANSPORT_TESTING_main_ (const char *argv0,
699 const char *filename,
700 unsigned int num_peers,
701 GNUNET_TRANSPORT_TESTING_CheckCallback check,
706 * Setup testcase. Calls @a check with the data the test needs.
708 * @param num_peers number of peers to start
709 * @param check main function to run
710 * @param check_cls closure for @a check
711 * @return #GNUNET_OK on success
713 #define GNUNET_TRANSPORT_TESTING_main(num_peers,check,check_cls) \
714 GNUNET_TRANSPORT_TESTING_main_ (argv[0], __FILE__, num_peers, check, check_cls)
716 /* ***************** Convenience functions for sending ********* */
719 * Send a test message of type @a mtype and size @a msize from
720 * peer @a sender to peer @a receiver. The peers should be
721 * connected when this function is called.
723 * @param sender the sending peer
724 * @param receiver the receiving peer
725 * @param mtype message type to use
726 * @param msize size of the message, at least `sizeof (struct GNUNET_TRANSPORT_TESTING_TestMessage)`
727 * @param num unique message number
728 * @param cont continuation to call after transmission
729 * @param cont_cls closure for @a cont
730 * @return #GNUNET_OK if message was queued,
731 * #GNUNET_NO if peers are not connected
732 * #GNUNET_SYSERR if @a msize is illegal
735 GNUNET_TRANSPORT_TESTING_send (struct GNUNET_TRANSPORT_TESTING_PeerContext *sender,
736 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
740 GNUNET_SCHEDULER_TaskCallback cont,
745 * Message type used by #GNUNET_TRANSPORT_TESTING_simple_send().
747 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE 12345
750 * Alternative message type for tests.
752 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE2 12346
756 * Type of the closure argument to pass to
757 * #GNUNET_TRANSPORT_TESTING_simple_send() and
758 * #GNUNET_TRANSPORT_TESTING_large_send().
760 struct GNUNET_TRANSPORT_TESTING_SendClosure
763 * Context for the transmission.
765 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc;
768 * Function that returns the desired message size. Overrides
769 * the message size, can be NULL in which case the message
770 * size is the default.
772 size_t (*get_size_cb)(unsigned int n);
775 * Number of messages to be transmitted in a loop.
776 * Use zero for "forever" (until external shutdown).
778 unsigned int num_messages;
781 * Function to call after all transmissions, can be NULL.
783 GNUNET_SCHEDULER_TaskCallback cont;
786 * Closure for @e cont.
794 * Task that sends a minimalistic test message from the
795 * first peer to the second peer.
797 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
798 * which should contain at least two peers, the first two
799 * of which should be currently connected
802 GNUNET_TRANSPORT_TESTING_simple_send (void *cls);
805 * Size of a message sent with
806 * #GNUNET_TRANSPORT_TESTING_large_send(). Big enough
807 * to usually force defragmentation.
809 #define GNUNET_TRANSPORT_TESTING_LARGE_MESSAGE_SIZE 2600
812 * Task that sends a large test message from the
813 * first peer to the second peer.
815 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
816 * which should contain at least two peers, the first two
817 * of which should be currently connected
820 GNUNET_TRANSPORT_TESTING_large_send (void *cls);
823 /* ********************** log-only convenience functions ************* */
827 * Log a connect event.
830 * @param me peer that had the event
831 * @param other peer that connected.
834 GNUNET_TRANSPORT_TESTING_log_connect (void *cls,
835 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
836 const struct GNUNET_PeerIdentity *other);
840 * Log a disconnect event.
843 * @param me peer that had the event
844 * @param other peer that disconnected.
847 GNUNET_TRANSPORT_TESTING_log_disconnect (void *cls,
848 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
849 const struct GNUNET_PeerIdentity *other);
853 /* ********************** low-level filename functions *************** */
857 * Extracts the test filename from an absolute file name and removes
860 * @param file absolute file name
861 * @return resulting test name
864 GNUNET_TRANSPORT_TESTING_get_test_name (const char *file);
868 * This function takes the filename (e.g. argv[0), removes a "lt-"-prefix and
869 * if existing ".exe"-prefix and adds the peer-number
871 * @param file filename of the test, e.g. argv[0]
872 * @param count peer number
873 * @return configuration name to use
876 GNUNET_TRANSPORT_TESTING_get_config_name (const char *file,
881 * Extracts the plugin anme from an absolute file name and the test name
882 * @param file absolute file name
883 * @param test test name
884 * @return the plugin name
887 GNUNET_TRANSPORT_TESTING_get_test_plugin_name (const char *executable,
888 const char *testname);
892 * Extracts the filename from an absolute file name and removes the
895 * @param file absolute file name
896 * @return the source name
899 GNUNET_TRANSPORT_TESTING_get_test_source_name (const char *file);
902 /* end of transport_testing.h */