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
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 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 General Public License for more details.
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., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @file transport-testing.h
23 * @brief testing lib for transport service
24 * @author Matthias Wachs
25 * @author Christian Grothoff
27 #ifndef TRANSPORT_TESTING_H
28 #define TRANSPORT_TESTING_H
30 #include "gnunet_util_lib.h"
31 #include "gnunet_hello_lib.h"
32 #include "gnunet_transport_service.h"
33 #include "gnunet_transport_core_service.h"
34 #include "gnunet_transport_hello_service.h"
35 #include "gnunet_transport_manipulation_service.h"
36 #include "gnunet_testing_lib.h"
39 /* ************* Basic functions for starting/stopping/connecting *********** */
42 * Context for a single peer
44 struct GNUNET_TRANSPORT_TESTING_PeerContext;
47 * Definition for a transport testing handle
49 struct GNUNET_TRANSPORT_TESTING_Handle;
53 * Context for a single peer
55 struct GNUNET_TRANSPORT_TESTING_PeerContext
58 * Next element in the DLL
60 struct GNUNET_TRANSPORT_TESTING_PeerContext *next;
63 * Previous element in the DLL
65 struct GNUNET_TRANSPORT_TESTING_PeerContext *prev;
68 * Transport testing handle this peer belongs to
70 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
73 * Peer's configuration
75 struct GNUNET_CONFIGURATION_Handle *cfg;
78 * Peer's transport service handle
80 struct GNUNET_TRANSPORT_CoreHandle *th;
83 * Peer's transport service manipulation handle
85 struct GNUNET_TRANSPORT_ManipulationHandle *tmh;
90 struct GNUNET_ATS_ConnectivityHandle *ats;
93 * Peer's transport get hello handle to retrieve peer's HELLO message
95 struct GNUNET_TRANSPORT_HelloGetHandle *ghh;
98 * Peer's testing handle
100 struct GNUNET_TESTING_Peer *peer;
105 struct GNUNET_PeerIdentity id;
108 * Handle for the peer's ARM process
110 struct GNUNET_OS_Process *arm_proc;
115 struct GNUNET_MQ_MessageHandler *handlers;
118 * Notify connect callback
120 GNUNET_TRANSPORT_NotifyConnecT nc;
123 * Notify disconnect callback
125 GNUNET_TRANSPORT_NotifyDisconnecT nd;
128 * Startup completed callback
130 GNUNET_SCHEDULER_TaskCallback start_cb;
133 * Peers HELLO Message
135 struct GNUNET_HELLO_Message *hello;
138 * Closure for the @a nc and @a nd callbacks
143 * Closure for @e start_cb.
148 * An unique number to identify the peer
155 * Handle for a request to connect two peers.
157 struct GNUNET_TRANSPORT_TESTING_ConnectRequest
162 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *next;
167 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *prev;
170 * Peer we want to connect.
172 struct GNUNET_TRANSPORT_TESTING_PeerContext *p1;
175 * Peer we want to connect.
177 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2;
180 * Task by which we accomplish the connection.
182 struct GNUNET_SCHEDULER_Task *tct;
185 * Handle by which we ask ATS to faciliate the connection.
187 struct GNUNET_ATS_ConnectivitySuggestHandle *ats_sh;
190 * Handle by which we inform the peer about the HELLO of
193 struct GNUNET_TRANSPORT_OfferHelloHandle *oh;
196 * Function to call upon completion.
198 GNUNET_SCHEDULER_TaskCallback cb;
206 * Message queue for sending from @a p1 to @a p2.
208 struct GNUNET_MQ_Handle *mq;
211 * Set if peer1 says the connection is up to peer2.
216 * Set if peer2 says the connection is up to peer1.
221 * #GNUNET_YES if both @e p1_c and @e p2_c are #GNUNET_YES.
228 * Handle for a test run.
230 struct GNUNET_TRANSPORT_TESTING_Handle
233 * Testing library system handle
235 struct GNUNET_TESTING_System *tl_system;
238 * head DLL of connect contexts
240 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_head;
243 * head DLL of connect contexts
245 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc_tail;
250 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_head;
255 struct GNUNET_TRANSPORT_TESTING_PeerContext *p_tail;
260 * Initialize the transport testing
262 * @return transport testing handle
264 struct GNUNET_TRANSPORT_TESTING_Handle *
265 GNUNET_TRANSPORT_TESTING_init (void);
269 * Clean up the transport testing
271 * @param tth transport testing handle
274 GNUNET_TRANSPORT_TESTING_done (struct GNUNET_TRANSPORT_TESTING_Handle *tth);
278 * Start a peer with the given configuration
280 * @param tth the testing handle
281 * @param cfgname configuration file
282 * @param peer_id the peer_id
283 * @param handlers functions for receiving messages
284 * @param nc connect callback
285 * @param nd disconnect callback
286 * @param cb_cls closure for @a nc and @a nd callback
287 * @param start_cb start callback
288 * @param start_cb_cls closure for @a start_cb
289 * @return the peer context
291 struct GNUNET_TRANSPORT_TESTING_PeerContext *
292 GNUNET_TRANSPORT_TESTING_start_peer (struct GNUNET_TRANSPORT_TESTING_Handle *tth,
295 const struct GNUNET_MQ_MessageHandler *handlers,
296 GNUNET_TRANSPORT_NotifyConnecT nc,
297 GNUNET_TRANSPORT_NotifyDisconnecT nd,
299 GNUNET_SCHEDULER_TaskCallback start_cb,
304 * Shutdown the given peer
309 GNUNET_TRANSPORT_TESTING_stop_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *pc);
313 * Stops and restarts the given peer, sleeping (!) for 5s in between.
316 * @param restart_cb restart callback
317 * @param restart_cb_cls callback closure
318 * @return #GNUNET_OK in success otherwise #GNUNET_SYSERR
321 GNUNET_TRANSPORT_TESTING_restart_peer (struct GNUNET_TRANSPORT_TESTING_PeerContext *p,
322 GNUNET_SCHEDULER_TaskCallback restart_cb,
323 void *restart_cb_cls);
328 * Connect the given peers and call the callback when both peers
329 * report the inbound connection. Remarks: start_peer's notify_connect
330 * callback can be called before.
334 * @param cb the callback to call when both peers notified that they are connected
335 * @param cls callback cls
336 * @return a connect request handle
338 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *
339 GNUNET_TRANSPORT_TESTING_connect_peers (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
340 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
341 GNUNET_SCHEDULER_TaskCallback cb,
346 * Cancel the request to connect two peers. You MUST cancel the
347 * request if you stop the peers before the peers connected
350 * @param cc a connect request handle
353 GNUNET_TRANSPORT_TESTING_connect_peers_cancel (struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
357 * Function called on matching connect requests.
360 * @param cc request matching the query
363 (*GNUNET_TRANSPORT_TESTING_ConnectContextCallback)(void *cls,
364 struct GNUNET_TRANSPORT_TESTING_ConnectRequest *cc);
368 * Find any connecting context matching the given pair of peers.
370 * @param p1 first peer
371 * @param p2 second peer
372 * @param cb function to call
373 * @param cb_cls closure for @a cb
376 GNUNET_TRANSPORT_TESTING_find_connecting_context (struct GNUNET_TRANSPORT_TESTING_PeerContext *p1,
377 struct GNUNET_TRANSPORT_TESTING_PeerContext *p2,
378 GNUNET_TRANSPORT_TESTING_ConnectContextCallback cb,
382 /* ********************** high-level process functions *************** */
386 * Function called once the peers have been launched and
387 * connected by #GNUNET_TRANSPORT_TESTING_connect_check().
390 * @param num_peers size of the @a p array
391 * @param p the peers that were launched
394 (*GNUNET_TRANSPORT_TESTING_ConnectContinuation)(void *cls,
395 unsigned int num_peers,
396 struct GNUNET_TRANSPORT_TESTING_PeerContext *p[]);
400 * Internal data structure.
402 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList;
405 * Internal data structure.
407 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext;
410 GNUNET_NETWORK_STRUCT_BEGIN
411 struct GNUNET_TRANSPORT_TESTING_TestMessage
414 * Type is (usually) #GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE.
416 struct GNUNET_MessageHeader header;
419 * Monotonically increasing counter throughout the test.
421 uint32_t num GNUNET_PACKED;
423 GNUNET_NETWORK_STRUCT_END
428 * Function called by the transport for each received message.
431 * @param receiver receiver of the message
432 * @param sender sender of the message
433 * @param message the message
436 (*GNUNET_TRANSPORT_TESTING_ReceiveCallback) (void *cls,
437 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
438 const struct GNUNET_PeerIdentity *sender,
439 const struct GNUNET_TRANSPORT_TESTING_TestMessage *message);
443 * Function called to notify transport users that another
444 * peer connected to us.
447 * @param me peer experiencing the event
448 * @param other peer that connected to @a me
451 (*GNUNET_TRANSPORT_TESTING_NotifyConnect) (void *cls,
452 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
453 const struct GNUNET_PeerIdentity *other);
457 * Function called to notify transport users that another
458 * peer disconnected from us.
461 * @param me peer experiencing the event
462 * @param other peer that disconnected from @a me
465 (*GNUNET_TRANSPORT_TESTING_NotifyDisconnect) (void *cls,
466 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
467 const struct GNUNET_PeerIdentity *other);
471 * Closure that must be passed to
472 * #GNUNET_TRANSPORT_TESTING_connect_check.
474 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext
478 * How should we continue after the connect?
480 GNUNET_SCHEDULER_TaskCallback connect_continuation;
483 * Closure for @e connect_continuation.
485 void *connect_continuation_cls;
488 * Which configuration file should we pass to the
489 * #GNUNET_PROGRAM_run() of the testcase?
491 const char *config_file;
494 * Receiver argument to give for peers we start.
496 GNUNET_TRANSPORT_TESTING_ReceiveCallback rec;
499 * Notify connect argument to give for peers we start.
501 GNUNET_TRANSPORT_TESTING_NotifyConnect nc;
504 * Notify disconnect argument to give for peers we start.
506 GNUNET_TRANSPORT_TESTING_NotifyDisconnect nd;
509 * Closure for @e rec, @e nc and @e nd.
514 * Custom task to run on shutdown.
516 GNUNET_SCHEDULER_TaskCallback shutdown_task;
519 * Closure for @e shutdown_task.
521 void *shutdown_task_cls;
524 * Custom task to run after peers were started but before we try to
525 * connect them. If this function is set, we wait ONE second after
526 * running this function until we continue with connecting the
529 GNUNET_SCHEDULER_TaskCallback pre_connect_task;
532 * Closure for @e shutdown_task.
534 void *pre_connect_task_cls;
537 * When should the testcase time out?
539 struct GNUNET_TIME_Relative timeout;
542 * Should we try to create connections in both directions?
546 /* ******* fields set by #GNUNET_TRANSPORT_TESTING_connect_check **** */
549 * Number of peers involved in the test.
551 unsigned int num_peers;
554 * Configuration files we have, array with @e num_peers entries.
559 * Array with @e num_peers entries.
561 struct GNUNET_TRANSPORT_TESTING_PeerContext **p;
564 * Name of the plugin.
566 const char *test_plugin;
569 * Name of the testcase.
571 const char *test_name;
574 * Configuration object for the testcase.
576 const struct GNUNET_CONFIGURATION_Handle *cfg;
579 * Main testing handle.
581 struct GNUNET_TRANSPORT_TESTING_Handle *tth;
584 * Result from the main function, set to #GNUNET_OK on success.
585 * Clients should set to #GNUNET_SYSERR to indicate test failure.
590 * Generator for the `num` field in test messages. Incremented each
591 * time #GNUNET_TRANSPORT_TESTING_simple_send or
592 * #GNUNET_TRANSPORT_TESTING_large_send are used to transmit a
595 uint32_t send_num_gen;
597 /* ******* internal state, clients should not mess with this **** */
600 * Task run on timeout.
602 struct GNUNET_SCHEDULER_Task *timeout_task;
605 * Task run to connect peers.
607 struct GNUNET_SCHEDULER_Task *connect_task;
610 * Number of peers that have been started.
612 unsigned int started;
615 * DLL of active connect requests.
617 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_head;
620 * DLL of active connect requests.
622 struct GNUNET_TRANSPORT_TESTING_ConnectRequestList *crl_tail;
625 * Array with @e num_peers entries.
627 struct GNUNET_TRANSPORT_TESTING_InternalPeerContext *ip;
633 * Find peer by peer ID.
635 * @param ccc context to search
636 * @param peer peer to look for
637 * @return NULL if @a peer was not found
639 struct GNUNET_TRANSPORT_TESTING_PeerContext *
640 GNUNET_TRANSPORT_TESTING_find_peer (struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc,
641 const struct GNUNET_PeerIdentity *peer);
645 * Common implementation of the #GNUNET_TRANSPORT_TESTING_CheckCallback.
646 * Starts and connects the two peers, then invokes the
647 * `connect_continuation` from @a cls. Sets up a timeout to
648 * abort the test, and a shutdown handler to clean up properly
651 * @param cls closure of type `struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext`
652 * @param tth_ initialized testing handle
653 * @param test_plugin_ name of the plugin
654 * @param test_name_ name of the test
655 * @param num_peers number of entries in the @a cfg_file array
656 * @param cfg_files array of names of configuration files for the peers
657 * @return #GNUNET_SYSERR on error
660 GNUNET_TRANSPORT_TESTING_connect_check (void *cls,
661 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
662 const char *test_plugin_,
663 const char *test_name_,
664 unsigned int num_peers,
669 * Main function of a testcase. Called with the initial setup data
670 * for the test as derived from the source name and the binary name.
673 * @param tth_ initialized testing handle
674 * @param test_plugin_ name of the plugin
675 * @param test_name_ name of the test
676 * @param num_peers number of entries in the @a cfg_file array
677 * @param cfg_files array of names of configuration files for the peers
678 * @return #GNUNET_SYSERR on error
681 (*GNUNET_TRANSPORT_TESTING_CheckCallback)(void *cls,
682 struct GNUNET_TRANSPORT_TESTING_Handle *tth_,
683 const char *test_plugin_,
684 const char *test_name_,
685 unsigned int num_peers,
690 * Setup testcase. Calls @a check with the data the test needs.
692 * @param argv0 binary name (argv[0])
693 * @param filename source file name (__FILE__)
694 * @param num_peers number of peers to start
695 * @param check main function to run
696 * @param check_cls closure for @a check
697 * @return #GNUNET_OK on success
700 GNUNET_TRANSPORT_TESTING_main_ (const char *argv0,
701 const char *filename,
702 unsigned int num_peers,
703 GNUNET_TRANSPORT_TESTING_CheckCallback check,
708 * Setup testcase. Calls @a check with the data the test needs.
710 * @param num_peers number of peers to start
711 * @param check main function to run
712 * @param check_cls closure for @a check
713 * @return #GNUNET_OK on success
715 #define GNUNET_TRANSPORT_TESTING_main(num_peers,check,check_cls) \
716 GNUNET_TRANSPORT_TESTING_main_ (argv[0], __FILE__, num_peers, check, check_cls)
718 /* ***************** Convenience functions for sending ********* */
721 * Send a test message of type @a mtype and size @a msize from
722 * peer @a sender to peer @a receiver. The peers should be
723 * connected when this function is called.
725 * @param sender the sending peer
726 * @param receiver the receiving peer
727 * @param mtype message type to use
728 * @param msize size of the message, at least `sizeof (struct GNUNET_TRANSPORT_TESTING_TestMessage)`
729 * @param num unique message number
730 * @param cont continuation to call after transmission
731 * @param cont_cls closure for @a cont
732 * @return #GNUNET_OK if message was queued,
733 * #GNUNET_NO if peers are not connected
734 * #GNUNET_SYSERR if @a msize is illegal
737 GNUNET_TRANSPORT_TESTING_send (struct GNUNET_TRANSPORT_TESTING_PeerContext *sender,
738 struct GNUNET_TRANSPORT_TESTING_PeerContext *receiver,
742 GNUNET_SCHEDULER_TaskCallback cont,
747 * Message type used by #GNUNET_TRANSPORT_TESTING_simple_send().
749 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE 12345
752 * Alternative message type for tests.
754 #define GNUNET_TRANSPORT_TESTING_SIMPLE_MTYPE2 12346
758 * Type of the closure argument to pass to
759 * #GNUNET_TRANSPORT_TESTING_simple_send() and
760 * #GNUNET_TRANSPORT_TESTING_large_send().
762 struct GNUNET_TRANSPORT_TESTING_SendClosure
765 * Context for the transmission.
767 struct GNUNET_TRANSPORT_TESTING_ConnectCheckContext *ccc;
770 * Function that returns the desired message size. Overrides
771 * the message size, can be NULL in which case the message
772 * size is the default.
774 size_t (*get_size_cb)(unsigned int n);
777 * Number of messages to be transmitted in a loop.
778 * Use zero for "forever" (until external shutdown).
780 unsigned int num_messages;
783 * Function to call after all transmissions, can be NULL.
785 GNUNET_SCHEDULER_TaskCallback cont;
788 * Closure for @e cont.
796 * Task that sends a minimalistic test message from the
797 * first peer to the second peer.
799 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
800 * which should contain at least two peers, the first two
801 * of which should be currently connected
804 GNUNET_TRANSPORT_TESTING_simple_send (void *cls);
807 * Size of a message sent with
808 * #GNUNET_TRANSPORT_TESTING_large_send(). Big enough
809 * to usually force defragmentation.
811 #define GNUNET_TRANSPORT_TESTING_LARGE_MESSAGE_SIZE 2600
814 * Task that sends a large test message from the
815 * first peer to the second peer.
817 * @param cls the `struct GNUNET_TRANSPORT_TESTING_SendClosure`
818 * which should contain at least two peers, the first two
819 * of which should be currently connected
822 GNUNET_TRANSPORT_TESTING_large_send (void *cls);
825 /* ********************** log-only convenience functions ************* */
829 * Log a connect event.
832 * @param me peer that had the event
833 * @param other peer that connected.
836 GNUNET_TRANSPORT_TESTING_log_connect (void *cls,
837 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
838 const struct GNUNET_PeerIdentity *other);
842 * Log a disconnect event.
845 * @param me peer that had the event
846 * @param other peer that disconnected.
849 GNUNET_TRANSPORT_TESTING_log_disconnect (void *cls,
850 struct GNUNET_TRANSPORT_TESTING_PeerContext *me,
851 const struct GNUNET_PeerIdentity *other);
855 /* ********************** low-level filename functions *************** */
859 * Extracts the test filename from an absolute file name and removes
862 * @param file absolute file name
863 * @return resulting test name
866 GNUNET_TRANSPORT_TESTING_get_test_name (const char *file);
870 * This function takes the filename (e.g. argv[0), removes a "lt-"-prefix and
871 * if existing ".exe"-prefix and adds the peer-number
873 * @param file filename of the test, e.g. argv[0]
874 * @param count peer number
875 * @return configuration name to use
878 GNUNET_TRANSPORT_TESTING_get_config_name (const char *file,
883 * Extracts the plugin anme from an absolute file name and the test name
884 * @param file absolute file name
885 * @param test test name
886 * @return the plugin name
889 GNUNET_TRANSPORT_TESTING_get_test_plugin_name (const char *executable,
890 const char *testname);
894 * Extracts the filename from an absolute file name and removes the
897 * @param file absolute file name
898 * @return the source name
901 GNUNET_TRANSPORT_TESTING_get_test_source_name (const char *file);
904 /* end of transport_testing.h */