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 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.
17 * @file transport-testing.h
18 * @brief testing lib for transport service
19 * @author Matthias Wachs
20 * @author Christian Grothoff
22 #ifndef TRANSPORT_TESTING_H
23 #define TRANSPORT_TESTING_H
25 #include "gnunet_util_lib.h"
26 #include "gnunet_hello_lib.h"
27 #include "gnunet_transport_service.h"
28 #include "gnunet_transport_core_service.h"
29 #include "gnunet_transport_hello_service.h"
30 #include "gnunet_transport_manipulation_service.h"
31 #include "gnunet_testing_lib.h"
34 /* ************* Basic functions for starting/stopping/connecting *********** */
37 * Context for a single peer
39 struct GNUNET_TRANSPORT_TESTING_PeerContext;
42 * Definition for a transport testing handle
44 struct GNUNET_TRANSPORT_TESTING_Handle;
48 * Context for a single peer
50 struct GNUNET_TRANSPORT_TESTING_PeerContext
53 * Next element in the DLL
55 struct GNUNET_TRANSPORT_TESTING_PeerContext *next;
58 * Previous element in the DLL
60 struct GNUNET_TRANSPORT_TESTING_PeerContext *prev;
63 * Transport testing handle this peer belongs to
65 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
68 * Peer's configuration
70 struct GNUNET_CONFIGURATION_Handle *cfg;
73 * Peer's transport service handle
75 struct GNUNET_TRANSPORT_CoreHandle *th;
78 * Peer's transport service manipulation handle
80 struct GNUNET_TRANSPORT_ManipulationHandle *tmh;
85 struct GNUNET_ATS_ConnectivityHandle *ats;
88 * Peer's transport get hello handle to retrieve peer's HELLO message
90 struct GNUNET_TRANSPORT_HelloGetHandle *ghh;
93 * Peer's testing handle
95 struct GNUNET_TESTING_Peer *peer;
100 struct GNUNET_PeerIdentity id;
103 * Handle for the peer's ARM process
105 struct GNUNET_OS_Process *arm_proc;
110 struct GNUNET_MQ_MessageHandler *handlers;
113 * Notify connect callback
115 GNUNET_TRANSPORT_NotifyConnecT nc;
118 * Notify disconnect callback
120 GNUNET_TRANSPORT_NotifyDisconnecT nd;
123 * Startup completed callback
125 GNUNET_SCHEDULER_TaskCallback start_cb;
128 * Peers HELLO Message
130 struct GNUNET_HELLO_Message *hello;
133 * Closure for the @a nc and @a nd callbacks
138 * Closure for @e start_cb.
143 * An unique number to identify the peer
150 * Handle for a request to connect two peers.
152 struct GNUNET_TRANSPORT_TESTING_ConnectRequest
157 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *next;
162 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *prev;
165 * Peer we want to connect.
167 struct GNUNET_TRANSPORT_TESTING_PeerContext *p1;
170 * Peer we want to connect.
172 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2;
175 * Task by which we accomplish the connection.
177 struct GNUNET_SCHEDULER_Task *tct;
180 * Handle by which we ask ATS to faciliate the connection.
182 struct GNUNET_ATS_ConnectivitySuggestHandle *ats_sh;
185 * Handle by which we inform the peer about the HELLO of
188 struct GNUNET_TRANSPORT_OfferHelloHandle *oh;
191 * Function to call upon completion.
193 GNUNET_SCHEDULER_TaskCallback cb;
201 * Message queue for sending from @a p1 to @a p2.
203 struct GNUNET_MQ_Handle *mq;
206 * Set if peer1 says the connection is up to peer2.
211 * Set if peer2 says the connection is up to peer1.
216 * #GNUNET_YES if both @e p1_c and @e p2_c are #GNUNET_YES.
223 * Handle for a test run.
225 struct GNUNET_TRANSPORT_TESTING_Handle
228 * Testing library system handle
230 struct GNUNET_TESTING_System *tl_system;
233 * head DLL of connect contexts
235 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_head;
238 * head DLL of connect contexts
240 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_tail;
245 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_head;
250 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_tail;
255 * Initialize the transport testing
257 * @return transport testing handle
259 struct GNUNET_TRANSPORT_TESTING_Handle *
260 GNUNET_TRANSPORT_TESTING_init (void);
264 * Clean up the transport testing
266 * @param tth transport testing handle
269 GNUNET_TRANSPORT_TESTING_done (struct GNUNET_TRANSPORT_TESTING_Handle *tth);
273 * Start a peer with the given configuration
275 * @param tth the testing handle
276 * @param cfgname configuration file
277 * @param peer_id the peer_id
278 * @param handlers functions for receiving messages
279 * @param nc connect callback
280 * @param nd disconnect callback
281 * @param cb_cls closure for @a nc and @a nd callback
282 * @param start_cb start callback
283 * @param start_cb_cls closure for @a start_cb
284 * @return the peer context
286 struct GNUNET_TRANSPORT_TESTING_PeerContext *
287 GNUNET_TRANSPORT_TESTING_start_peer (struct GNUNET_TRANSPORT_TESTING_Handle *tth,
290 const struct GNUNET_MQ_MessageHandler *handlers,
291 GNUNET_TRANSPORT_NotifyConnecT nc,
292 GNUNET_TRANSPORT_NotifyDisconnecT nd,
294 GNUNET_SCHEDULER_TaskCallback start_cb,
299 * Shutdown the given peer
304 GNUNET_TRANSPORT_TESTING_stop_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *pc);
308 * Stops and restarts the given peer, sleeping (!) for 5s in between.
311 * @param restart_cb restart callback
312 * @param restart_cb_cls callback closure
313 * @return #GNUNET_OK in success otherwise #GNUNET_SYSERR
316 GNUNET_TRANSPORT_TESTING_restart_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
317 GNUNET_SCHEDULER_TaskCallback restart_cb,
318 void *restart_cb_cls);
323 * Connect the given peers and call the callback when both peers
324 * report the inbound connection. Remarks: start_peer's notify_connect
325 * callback can be called before.
329 * @param cb the callback to call when both peers notified that they are connected
330 * @param cls callback cls
331 * @return a connect request handle
333 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *
334 GNUNET_TRANSPORT_TESTING_connect_peers (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
335 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
336 GNUNET_SCHEDULER_TaskCallback cb,
341 * Cancel the request to connect two peers. You MUST cancel the
342 * request if you stop the peers before the peers connected
345 * @param cc a connect request handle
348 GNUNET_TRANSPORT_TESTING_connect_peers_cancel (struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
352 * Function called on matching connect requests.
355 * @param cc request matching the query
358 (*GNUNET_TRANSPORT_TESTING_ConnectContextCallback)(void *cls,
359 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
363 * Find any connecting context matching the given pair of peers.
365 * @param p1 first peer
366 * @param p2 second peer
367 * @param cb function to call
368 * @param cb_cls closure for @a cb
371 GNUNET_TRANSPORT_TESTING_find_connecting_context (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
372 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
373 GNUNET_TRANSPORT_TESTING_ConnectContextCallback cb,
377 /* ********************** high-level process functions *************** */
381 * Function called once the peers have been launched and
382 * connected by #GNUNET_TRANSPORT_TESTING_connect_check().
385 * @param num_peers size of the @a p array
386 * @param p the peers that were launched
389 (*GNUNET_TRANSPORT_TESTING_ConnectContinuation)(void *cls,
390 unsigned int num_peers,
391 struct GNUNET_TRANSPORT_TESTING_PeerContext *p[]);
395 * Internal data structure.
397 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList;
400 * Internal data structure.
402 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext;
405 GNUNET_NETWORK_STRUCT_BEGIN
406 struct GNUNET_TRANSPORT_TESTING_TestMessage
409 * Type is (usually) #GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE.
411 struct GNUNET_MessageHeader header;
414 * Monotonically increasing counter throughout the test.
416 uint32_t num GNUNET_PACKED;
418 GNUNET_NETWORK_STRUCT_END
423 * Function called by the transport for each received message.
426 * @param receiver receiver of the message
427 * @param sender sender of the message
428 * @param message the message
431 (*GNUNET_TRANSPORT_TESTING_ReceiveCallback) (void *cls,
432 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
433 const struct GNUNET_PeerIdentity *sender,
434 const struct GNUNET_TRANSPORT_TESTING_TestMessage *message);
438 * Function called to notify transport users that another
439 * peer connected to us.
442 * @param me peer experiencing the event
443 * @param other peer that connected to @a me
446 (*GNUNET_TRANSPORT_TESTING_NotifyConnect) (void *cls,
447 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
448 const struct GNUNET_PeerIdentity *other);
452 * Function called to notify transport users that another
453 * peer disconnected from us.
456 * @param me peer experiencing the event
457 * @param other peer that disconnected from @a me
460 (*GNUNET_TRANSPORT_TESTING_NotifyDisconnect) (void *cls,
461 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
462 const struct GNUNET_PeerIdentity *other);
466 * Closure that must be passed to
467 * #GNUNET_TRANSPORT_TESTING_connect_check.
469 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext
473 * How should we continue after the connect?
475 GNUNET_SCHEDULER_TaskCallback connect_continuation;
478 * Closure for @e connect_continuation.
480 void *connect_continuation_cls;
483 * Which configuration file should we pass to the
484 * #GNUNET_PROGRAM_run() of the testcase?
486 const char *config_file;
489 * Receiver argument to give for peers we start.
491 GNUNET_TRANSPORT_TESTING_ReceiveCallback rec;
494 * Notify connect argument to give for peers we start.
496 GNUNET_TRANSPORT_TESTING_NotifyConnect nc;
499 * Notify disconnect argument to give for peers we start.
501 GNUNET_TRANSPORT_TESTING_NotifyDisconnect nd;
504 * Closure for @e rec, @e nc and @e nd.
509 * Custom task to run on shutdown.
511 GNUNET_SCHEDULER_TaskCallback shutdown_task;
514 * Closure for @e shutdown_task.
516 void *shutdown_task_cls;
519 * Custom task to run after peers were started but before we try to
520 * connect them. If this function is set, we wait ONE second after
521 * running this function until we continue with connecting the
524 GNUNET_SCHEDULER_TaskCallback pre_connect_task;
527 * Closure for @e shutdown_task.
529 void *pre_connect_task_cls;
532 * When should the testcase time out?
534 struct GNUNET_TIME_Relative timeout;
537 * Should we try to create connections in both directions?
541 /* ******* fields set by #GNUNET_TRANSPORT_TESTING_connect_check **** */
544 * Number of peers involved in the test.
546 unsigned int num_peers;
549 * Configuration files we have, array with @e num_peers entries.
554 * Array with @e num_peers entries.
556 struct GNUNET_TRANSPORT_TESTING_PeerContext **p;
559 * Name of the plugin.
561 const char *test_plugin;
564 * Name of the testcase.
566 const char *test_name;
569 * Configuration object for the testcase.
571 const struct GNUNET_CONFIGURATION_Handle *cfg;
574 * Main testing handle.
576 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
579 * Result from the main function, set to #GNUNET_OK on success.
580 * Clients should set to #GNUNET_SYSERR to indicate test failure.
585 * Generator for the `num` field in test messages. Incremented each
586 * time #GNUNET_TRANSPORT_TESTING_simple_send or
587 * #GNUNET_TRANSPORT_TESTING_large_send are used to transmit a
590 uint32_t send_num_gen;
592 /* ******* internal state, clients should not mess with this **** */
595 * Task run on timeout.
597 struct GNUNET_SCHEDULER_Task *timeout_task;
600 * Task run to connect peers.
602 struct GNUNET_SCHEDULER_Task *connect_task;
605 * Number of peers that have been started.
607 unsigned int started;
610 * DLL of active connect requests.
612 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_head;
615 * DLL of active connect requests.
617 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_tail;
620 * Array with @e num_peers entries.
622 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext *ip;
628 * Find peer by peer ID.
630 * @param ccc context to search
631 * @param peer peer to look for
632 * @return NULL if @a peer was not found
634 struct GNUNET_TRANSPORT_TESTING_PeerContext *
635 GNUNET_TRANSPORT_TESTING_find_peer (struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc,
636 const struct GNUNET_PeerIdentity *peer);
640 * Common implementation of the #GNUNET_TRANSPORT_TESTING_CheckCallback.
641 * Starts and connects the two peers, then invokes the
642 * `connect_continuation` from @a cls. Sets up a timeout to
643 * abort the test, and a shutdown handler to clean up properly
646 * @param cls closure of type `struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext`
647 * @param tth_ initialized testing handle
648 * @param test_plugin_ name of the plugin
649 * @param test_name_ name of the test
650 * @param num_peers number of entries in the @a cfg_file array
651 * @param cfg_files array of names of configuration files for the peers
652 * @return #GNUNET_SYSERR on error
655 GNUNET_TRANSPORT_TESTING_connect_check (void *cls,
656 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
657 const char *test_plugin_,
658 const char *test_name_,
659 unsigned int num_peers,
664 * Main function of a testcase. Called with the initial setup data
665 * for the test as derived from the source name and the binary name.
668 * @param tth_ initialized testing handle
669 * @param test_plugin_ name of the plugin
670 * @param test_name_ name of the test
671 * @param num_peers number of entries in the @a cfg_file array
672 * @param cfg_files array of names of configuration files for the peers
673 * @return #GNUNET_SYSERR on error
676 (*GNUNET_TRANSPORT_TESTING_CheckCallback)(void *cls,
677 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
678 const char *test_plugin_,
679 const char *test_name_,
680 unsigned int num_peers,
685 * Setup testcase. Calls @a check with the data the test needs.
687 * @param argv0 binary name (argv[0])
688 * @param filename source file name (__FILE__)
689 * @param num_peers number of peers to start
690 * @param check main function to run
691 * @param check_cls closure for @a check
692 * @return #GNUNET_OK on success
695 GNUNET_TRANSPORT_TESTING_main_ (const char *argv0,
696 const char *filename,
697 unsigned int num_peers,
698 GNUNET_TRANSPORT_TESTING_CheckCallback check,
703 * Setup testcase. Calls @a check with the data the test needs.
705 * @param num_peers number of peers to start
706 * @param check main function to run
707 * @param check_cls closure for @a check
708 * @return #GNUNET_OK on success
710 #define GNUNET_TRANSPORT_TESTING_main(num_peers,check,check_cls) \
711 GNUNET_TRANSPORT_TESTING_main_ (argv[0], __FILE__, num_peers, check, check_cls)
713 /* ***************** Convenience functions for sending ********* */
716 * Send a test message of type @a mtype and size @a msize from
717 * peer @a sender to peer @a receiver. The peers should be
718 * connected when this function is called.
720 * @param sender the sending peer
721 * @param receiver the receiving peer
722 * @param mtype message type to use
723 * @param msize size of the message, at least `sizeof (struct GNUNET_TRANSPORT_TESTING_TestMessage)`
724 * @param num unique message number
725 * @param cont continuation to call after transmission
726 * @param cont_cls closure for @a cont
727 * @return #GNUNET_OK if message was queued,
728 * #GNUNET_NO if peers are not connected
729 * #GNUNET_SYSERR if @a msize is illegal
732 GNUNET_TRANSPORT_TESTING_send (struct GNUNET_TRANSPORT_TESTING_PeerContext *sender,
733 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
737 GNUNET_SCHEDULER_TaskCallback cont,
742 * Message type used by #GNUNET_TRANSPORT_TESTING_simple_send().
744 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE 12345
747 * Alternative message type for tests.
749 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE2 12346
753 * Type of the closure argument to pass to
754 * #GNUNET_TRANSPORT_TESTING_simple_send() and
755 * #GNUNET_TRANSPORT_TESTING_large_send().
757 struct GNUNET_TRANSPORT_TESTING_SendClosure
760 * Context for the transmission.
762 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc;
765 * Function that returns the desired message size. Overrides
766 * the message size, can be NULL in which case the message
767 * size is the default.
769 size_t (*get_size_cb)(unsigned int n);
772 * Number of messages to be transmitted in a loop.
773 * Use zero for "forever" (until external shutdown).
775 unsigned int num_messages;
778 * Function to call after all transmissions, can be NULL.
780 GNUNET_SCHEDULER_TaskCallback cont;
783 * Closure for @e cont.
791 * Task that sends a minimalistic test message from the
792 * first peer to the second peer.
794 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
795 * which should contain at least two peers, the first two
796 * of which should be currently connected
799 GNUNET_TRANSPORT_TESTING_simple_send (void *cls);
802 * Size of a message sent with
803 * #GNUNET_TRANSPORT_TESTING_large_send(). Big enough
804 * to usually force defragmentation.
806 #define GNUNET_TRANSPORT_TESTING_LARGE_MESSAGE_SIZE 2600
809 * Task that sends a large test message from the
810 * first peer to the second peer.
812 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
813 * which should contain at least two peers, the first two
814 * of which should be currently connected
817 GNUNET_TRANSPORT_TESTING_large_send (void *cls);
820 /* ********************** log-only convenience functions ************* */
824 * Log a connect event.
827 * @param me peer that had the event
828 * @param other peer that connected.
831 GNUNET_TRANSPORT_TESTING_log_connect (void *cls,
832 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
833 const struct GNUNET_PeerIdentity *other);
837 * Log a disconnect event.
840 * @param me peer that had the event
841 * @param other peer that disconnected.
844 GNUNET_TRANSPORT_TESTING_log_disconnect (void *cls,
845 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
846 const struct GNUNET_PeerIdentity *other);
850 /* ********************** low-level filename functions *************** */
854 * Extracts the test filename from an absolute file name and removes
857 * @param file absolute file name
858 * @return resulting test name
861 GNUNET_TRANSPORT_TESTING_get_test_name (const char *file);
865 * This function takes the filename (e.g. argv[0), removes a "lt-"-prefix and
866 * if existing ".exe"-prefix and adds the peer-number
868 * @param file filename of the test, e.g. argv[0]
869 * @param count peer number
870 * @return configuration name to use
873 GNUNET_TRANSPORT_TESTING_get_config_name (const char *file,
878 * Extracts the plugin anme from an absolute file name and the test name
879 * @param file absolute file name
880 * @param test test name
881 * @return the plugin name
884 GNUNET_TRANSPORT_TESTING_get_test_plugin_name (const char *executable,
885 const char *testname);
889 * Extracts the filename from an absolute file name and removes the
892 * @param file absolute file name
893 * @return the source name
896 GNUNET_TRANSPORT_TESTING_get_test_source_name (const char *file);
899 /* end of transport_testing.h */