From: Christian Grothoff Date: Sat, 5 May 2012 15:49:25 +0000 (+0000) Subject: -renaming new testing code to testbed X-Git-Tag: initial-import-from-subversion-38251~13667 X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=b042203d5a4f8729bbde84447841e8531010d1aa;p=oweals%2Fgnunet.git -renaming new testing code to testbed --- diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 626aae0ec..115eb51d7 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am @@ -75,6 +75,7 @@ gnunetinclude_HEADERS = \ gnunet_statistics_service.h \ gnunet_stream_lib.h \ gnunet_strings_lib.h \ + gnunet_testbed_service.h \ gnunet_testing_lib.h \ gnunet_time_lib.h \ gnunet_transport_service.h \ diff --git a/src/include/gnunet_testbed_service.h b/src/include/gnunet_testbed_service.h new file mode 100644 index 000000000..a13c2bb10 --- /dev/null +++ b/src/include/gnunet_testbed_service.h @@ -0,0 +1,1029 @@ +/* + This file is part of GNUnet + (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file include/gnunet_testbed_service.h + * @brief API for writing tests and creating large-scale + * emulation testbeds for GNUnet. + * @author Christian Grothoff + */ + +#ifndef GNUNET_TESTBED_SERVICE_H +#define GNUNET_TESTBED_SERVICE_H + +#include "gnunet_util_lib.h" + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + + +/** + * Opaque handle to a host running experiments managed by the testbed framework. + * The master process must be able to SSH to this host without password (via + * ssh-agent). + */ +struct GNUNET_TESTBED_Host; + +/** + * Opaque handle to a peer controlled by the testbed framework. A peer runs + * at a particular host. + */ +struct GNUNET_TESTBED_Peer; + +/** + * Opaque handle to an abstract operation to be executed by the testbed framework. + */ +struct GNUNET_TESTBED_Operation; + +/** + * Handle to interact with a GNUnet testbed controller. Each controller has at + * least one master handle which is created when the controller is created; this + * master handle interacts with the controller via stdin/stdout of the controller + * process. Additionally, controllers can interact with each other (in a P2P + * fashion); those links are established via TCP/IP on the controller's service + * port. + */ +struct GNUNET_TESTBED_Controller; + +/** + * Handle to a large-scale testbed that is managed at a high level. + */ +struct GNUNET_TESTBED_Testbed; + + +/** + * Create a host to run peers and controllers on. + * + * @param hostname name of the host, use "NULL" for localhost + * @param username username to use for the login; may be NULL + * @param port port number to use for ssh; use 0 to let ssh decide + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create (const char *hostname, + const char *username, + uint16_t port); + + +/** + * Load a set of hosts from a configuration file. + * + * @param filename file with the host specification + * @param hosts set to the hosts found in the file + * @return number of hosts returned in 'hosts', 0 on error + */ +unsigned int +GNUNET_TESTBED_hosts_load_from_file (const char *filename, + struct GNUNET_TESTBED_Host **hosts); + + +/** + * Destroy a host handle. Must only be called once everything + * running on that host has been stopped. + * + * @param host handle to destroy + */ +void +GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host); + + +/** + * Enumeration with (at most 64) possible event types that + * can be monitored using the testbed framework. + */ +enum GNUNET_TESTBED_EventType +{ + /** + * A peer has been started. + */ + GNUNET_TESTBED_ET_PEER_START = 0, + + /** + * A peer has been stopped. + */ + GNUNET_TESTBED_ET_PEER_STOP = 1, + + /** + * A connection between two peers was established. + */ + GNUNET_TESTBED_ET_CONNECT = 2, + + /** + * A connection between two peers was torn down. + */ + GNUNET_TESTBED_ET_DISCONNECT = 3, + + /** + * A requested testbed operation has been completed. + */ + GNUNET_TESTBED_ET_OPERATION_FINISHED = 4, + + /** + * The 'GNUNET_TESTBED_run' operation has been completed + */ + GNUNET_TESTBED_ET_TESTBED_ONLINE = 5 + +}; + + +/** + * Types of information that can be requested about a peer. + */ +enum GNUNET_TESTBED_PeerInformationType +{ + + /** + * Special value (not valid for requesting information) + * that is used in the event struct if a 'generic' pointer + * is returned (for other operations not related to this + * enumeration). + */ + GNUNET_TESTBED_PIT_GENERIC = 0, + + /** + * What host is the peer running on? Returns a 'const struct + * GNUNET_TESTBED_Host *'. Valid until + * 'GNUNET_TESTBED_operation_done' is called. + */ + GNUNET_TESTBED_PIT_HOST, + + /** + * What configuration is the peer using? Returns a 'const struct + * GNUNET_CONFIGURATION_Handle *'. Valid until + * 'GNUNET_TESTNIG_operation_done' is called. However, the + * values may be inaccurate if the peer is reconfigured in + * the meantime. + */ + GNUNET_TESTBED_PIT_CONFIGURATION, + + /** + * What is the identity of the peer? Returns a + * 'const struct GNUNET_PeerIdentity *'. Valid until + * 'GNUNET_TESTNIG_operation_done' is called. + */ + GNUNET_TESTBED_PIT_IDENTITY + +}; + + +/** + * Argument to GNUNET_TESTBED_ControllerCallback with details about + * the event. + */ +struct GNUNET_TESTBED_EventInformation +{ + + /** + * Type of the event. + */ + enum GNUNET_TESTBED_EventType type; + + /** + * Details about the event. + */ + union + { + + /** + * Details about peer start event. + */ + struct + { + /** + * Handle for the host where the peer + * was started. + */ + struct GNUNET_TESTBED_Host *host; + + /** + * Handle for the peer that was started. + */ + struct GNUNET_TESTBED_Peer *peer; + + } peer_start; + + /** + * Details about peer stop event. + */ + struct + { + + /** + * Handle for the peer that was started. + */ + struct GNUNET_TESTBED_Peer *peer; + + } peer_stop; + + /** + * Details about connect event. + */ + struct + { + /** + * Handle for one of the connected peers. + */ + struct GNUNET_TESTBED_Peer *peer1; + + /** + * Handle for one of the connected peers. + */ + struct GNUNET_TESTBED_Peer *peer2; + + } peer_connect; + + /** + * Details about disconnect event. + */ + struct + { + /** + * Handle for one of the disconnected peers. + */ + struct GNUNET_TESTBED_Peer *peer1; + + /** + * Handle for one of the disconnected peers. + */ + struct GNUNET_TESTBED_Peer *peer2; + + } peer_disconnect; + + /** + * Details about an operation finished event. + */ + struct + { + + /** + * Handle for the operation that was finished. + */ + struct GNUNET_TESTBED_Operation *operation; + + /** + * Closure that was passed in when the event was + * requested. + */ + void *op_cls; + + /** + * Error message for the operation, NULL on success. + */ + const char *emsg; + + /** + * Peer information type; captures which of the types + * in the 'op_result' is actually in use. + */ + enum GNUNET_TESTBED_PeerInformationType pit; + + /** + * Pointer to an operation-specific return value; NULL on error; + * can be NULL for certain operations. Valid until + * 'GNUNET_TESTBED_operation_done' is called. + */ + union + { + /** + * No result (NULL pointer) or generic result + * (whatever the GNUNET_TESTBED_ConnectAdapter returned). + */ + void *generic; + + /** + * Identity of host running the peer. + */ + struct GNUNET_TESTBED_Host *host; + + /** + * Identity of the peer. + */ + const struct GNUNET_PeerIdentity *pid; + + /** + * Configuration of the peer. + */ + const struct GNUNET_CONFIGURATION_Handle *cfg; + + } op_result; + + } operation_finished; + + + /** + * Details about an testbed run completed event. + */ + struct + { + + /** + * Error message for the operation, NULL on success. + */ + const char *emsg; + + /** + * Array of peers now running (valid until + * 'GNUNET_TESTBED_testbed_stop' is called). Note that it is + * not allowed to call 'GNUNET_TESTBED_peer_destroy' on peers + * from this array. + */ + struct GNUNET_TESTBED_Peer **peers; + + /** + * Size of the 'peers' array. + */ + unsigned int num_peers; + + } testbed_run_finished; + + } details; + +}; + + +/** + * Signature of the event handler function called by the + * respective event controller. + * + * @param cls closure + * @param event information about the event + */ +typedef void (*GNUNET_TESTBED_ControllerCallback)(void *cls, + const struct GNUNET_TESTBED_EventInformation *event); + + +/** + * Start a controller process using the given configuration at the + * given host. + * + * @param cfg configuration to use + * @param host host to run the controller on, NULL for 'localhost' + * @param event_mask bit mask with set of events to call 'cc' for; + * or-ed values of "1LL" shifted by the + * respective 'enum GNUNET_TESTBED_EventType' + * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...") + * @param cc controller callback to invoke on events + * @param cc_cls closure for cc + * @return handle to the controller + */ +struct GNUNET_TESTBED_Controller * +GNUNET_TESTBED_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + struct GNUNET_TESTBED_Host *host, + uint64_t event_mask, + GNUNET_TESTBED_ControllerCallback cc, + void *cc_cls); + + +/** + * Configure shared services at a controller. Using this function, + * you can specify that certain services (such as "resolver") + * should not be run for each peer but instead be shared + * across N peers on the specified host. This function + * must be called before any peers are created at the host. + * + * @param controller controller to configure + * @param service_name name of the service to share + * @param num_peers number of peers that should share one instance + * of the specified service (1 for no sharing is the default), + * use 0 to disable the service + */ +void +GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller, + const char *service_name, + uint32_t num_peers); + + +/** + * Stop the given controller (also will terminate all peers and + * controllers dependent on this controller). This function + * blocks until the testbed has been fully terminated (!). + * + * @param controller handle to controller to stop + */ +void +GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_Controller *controller); + + +/** + * Create a link from a 'master' controller to a slave controller. + * Whenever the master controller is asked to start a peer at the + * given 'delegated_host', it will delegate the request to the + * specified slave controller. Note that the slave controller runs at + * the 'slave_host', which may or may not be the same host as the + * 'delegated_host' (for hierarchical delegations). The configuration + * of the slave controller is given and to be used to either create + * the slave controller or to connect to an existing slave controller + * process. 'is_subordinate' specifies if the given slave controller + * should be started and managed by the master controller, or if the + * slave already has a master and this is just a secondary master that + * is also allowed to use the existing slave. + * + * @param master handle to the master controller who creates the association + * @param delegated_host requests to which host should be delegated + * @param slave_host which host is used to run the slave controller + * @param slave_cfg configuration to use for the slave controller + * @param is_subordinate GNUNET_YES if the slave should be started (and stopped) + * by the master controller; GNUNET_NO if we are just + * allowed to use the slave via TCP/IP + */ +void +GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master, + struct GNUNET_TESTBED_Host *delegated_host, + struct GNUNET_TESTBED_Host *slave_host, + const struct GNUNET_CONFIGURATION_Handle *slave_cfg, + int is_subordinate); + + +/** + * Create the given peer at the specified host using the given + * controller. If the given controller is not running on the target + * host, it should find or create a controller at the target host and + * delegate creating the peer. Explicit delegation paths can be setup + * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation + * path exists, a direct link with a subordinate controller is setup + * for the first delegated peer to a particular host; the subordinate + * controller is then destroyed once the last peer that was delegated + * to the remote host is stopped. + * + * Creating the peer only creates the handle to manipulate and further + * configure the peer; use "GNUNET_TESTBED_peer_start" and + * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's + * processes. + * + * Note that the given configuration will be adjusted by the + * controller to avoid port/path conflicts with other peers. + * The "final" configuration can be obtained using + * 'GNUNET_TESTBED_peer_get_information'. + * + * @param controller controller process to use + * @param host host to run the peer on + * @param cfg configuration to use for the peer + * @return handle to the peer (actual startup will happen asynchronously) + */ +struct GNUNET_TESTBED_Peer * +GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller, + struct GNUNET_TESTBED_Host *host, + const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Start the given peer. + * + * @param peer peer to start + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer); + + +/** + * Stop the given peer. The handle remains valid (use + * "GNUNET_TESTBED_peer_destroy" to fully clean up the + * state of the peer). + * + * @param peer peer to stop + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer); + + +/** + * Request information about a peer. + * + * @param peer peer to request information about + * @param pit desired information + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, + enum GNUNET_TESTBED_PeerInformationType pit); + + +/** + * Change peer configuration. Must only be called while the + * peer is stopped. Ports and paths cannot be changed this + * way. + * + * @param peer peer to change configuration for + * @param cfg new configuration (differences to existing + * configuration only) + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer, + const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Destroy the given peer; the peer should have been + * stopped first (if it was started). + * + * @param peer peer to stop + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_destroy (struct GNUNET_TESTBED_Peer *peer); + + +/** + * Options for peer connections. + */ +enum GNUNET_TESTBED_ConnectOption +{ + /** + * No option (not valid as an argument). + */ + GNUNET_TESTBED_CO_NONE = 0, + + /** + * Allow or disallow a connection between the specified peers. + * Followed by GNUNET_NO (int) if a connection is disallowed + * or GNUNET_YES if a connection is allowed. Note that the + * default (all connections allowed or disallowed) is + * specified in the configuration of the controller. + */ + GNUNET_TESTBED_CO_ALLOW = 1, + + /** + * FIXME: add (and implement) options to limit connection to + * particular transports, force simulation of particular latencies + * or message loss rates, or set bandwidth limitations. + */ + +}; + + +/** + * Manipulate the P2P underlay topology by configuring a link + * between two peers. + * + * @param op_cls closure argument to give with the operation event + * @param p1 first peer + * @param p2 second peer + * @param co option to change + * @param ... option-specific values + * @return handle to the operation, NULL if configuring the link at this + * time is not allowed + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_link_va (void *op_cls, + struct GNUNET_TESTBED_Peer *p1, + struct GNUNET_TESTBED_Peer *p2, + enum GNUNET_TESTBED_ConnectOption co, + va_list ap); + + +/** + * Manipulate the P2P underlay topology by configuring a link + * between two peers. + * + * @param op_cls closure argument to give with the operation event + * @param p1 first peer + * @param p2 second peer + * @param co option to change + * @param ... option-specific values + * @return handle to the operation, NULL if configuring the link at this + * time is not allowed + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_link (void *op_cls, + struct GNUNET_TESTBED_Peer *p1, + struct GNUNET_TESTBED_Peer *p2, + enum GNUNET_TESTBED_ConnectOption co, ...); + + + +/** + * Topologies supported for testbeds. + */ +enum GNUNET_TESTBED_TopologyOption +{ + /** + * A clique (everyone connected to everyone else). No options. + */ + GNUNET_TESTBED_TOPOLOGY_CLIQUE, + + /** + * Small-world network (2d torus plus random links). Followed + * by the number of random links to add (unsigned int). + */ + GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD, + + /** + * Small-world network (ring plus random links). Followed + * by the number of random links to add (unsigned int). + */ + GNUNET_TESTBED_TOPOLOGY_SMALL_WORLD_RING, + + /** + * Ring topology. No options. + */ + GNUNET_TESTBED_TOPOLOGY_RING, + + /** + * 2-d torus. No options. + */ + GNUNET_TESTBED_TOPOLOGY_2D_TORUS, + + /** + * Random graph. Followed by the link density, that is the + * percentage of links present in relation to a clique + * (float). + */ + GNUNET_TESTBED_TOPOLOGY_ERDOS_RENYI, + + /** + * Certain percentage of peers are unable to communicate directly + * replicating NAT conditions. Followed by the fraction of + * NAT'ed peers (float). + */ + GNUNET_TESTBED_TOPOLOGY_INTERNAT, + + /** + * Scale free topology. FIXME: options? + */ + GNUNET_TESTBED_TOPOLOGY_SCALE_FREE, + + /** + * Straight line topology. No options. + */ + GNUNET_TESTBED_TOPOLOGY_LINE, + + /** + * All peers are disconnected. No options. + */ + GNUNET_TESTBED_TOPOLOGY_NONE, + + /** + * Read a topology from a given file. Followed by the name of the file (const char *). + */ + GNUNET_TESTBED_TOPOLOGY_FROM_FILE +}; + + +/** + * Configure overall network topology to have a particular shape. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ap topology-specific options + * @return handle to the operation, NULL if configuring the topology + * is not allowed at this time + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer **peers, + enum GNUNET_TESTBED_TopologyOption topo, + va_list ap); + + +/** + * Configure overall network topology to have a particular shape. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ... topology-specific options + * @return handle to the operation, NULL if configuring the topology + * is not allowed at this time + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_topology (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer **peers, + enum GNUNET_TESTBED_TopologyOption topo, + ...); + + +/** + * Both peers must have been started before calling this function. + * This function then obtains a HELLO from 'p1', gives it to 'p2' + * and asks 'p2' to connect to 'p1'. + * + * @param op_cls closure argument to give with the operation event + * @param p1 first peer + * @param p2 second peer + * @return handle to the operation, NULL if connecting these two + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_connect (void *op_cls, + struct GNUNET_TESTBED_Peer *p1, + struct GNUNET_TESTBED_Peer *p2); + + +/** + * All peers must have been started before calling this function. + * This function then connects the given peers in the P2P overlay + * using the given topology. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param va topology-specific options + * @return handle to the operation, NULL if connecting these + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer *peers, + enum GNUNET_TESTBED_TopologyOption topo, + va_list va); + + +/** + * All peers must have been started before calling this function. + * This function then connects the given peers in the P2P overlay + * using the given topology. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ... topology-specific options + * @return handle to the operation, NULL if connecting these + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_configure_topology (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer *peers, + enum GNUNET_TESTBED_TopologyOption topo, + ...); + + + +/** + * Ask the testbed controller to write the current overlay topology to + * a file. Naturally, the file will only contain a snapshot as the + * topology may evolve all the time. + * + * @param controller overlay controller to inspect + * @param filename name of the file the topology should + * be written to. + */ +void +GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller, + const char *filename); + + +/** + * Adapter function called to establish a connection to + * a service. + * + * @param cls closure + * @param cfg configuration of the peer to connect to + * @return service handle to return in 'op_result', NULL on error + */ +typedef void * (*GNUNET_TESTBED_ConnectAdapter)(void *cls, + const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Adapter function called to destroy a connection to + * a service. + * + * @param cls closure + * @param op_result service handle returned from the connect adapter + */ +typedef void (*GNUNET_TESTBED_DisconnectAdapter)(void *cls, + void *op_result); + + +/** + * Connect to a service offered by the given peer. Will ensure that + * the request is queued to not overwhelm our ability to create and + * maintain connections with other systems. The actual service + * handle is then returned via the 'op_result' member in the event + * callback. The 'ca' callback is used to create the connection + * when the time is right; the 'da' callback will be used to + * destroy the connection (upon 'GNUNET_TESTBED_operation_done'). + * 'GNUNET_TESTBED_operation_cancel' can be used to abort this + * operation until the event callback has been called. + * + * @param op_cls closure to pass in operation event + * @param peer peer that runs the service + * @param service_name name of the service to connect to + * @param ca helper function to establish the connection + * @param da helper function to close the connection + * @param cada_cls closure for ca and da + * @return handle for the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_service_connect (void *op_cls, + struct GNUNET_TESTBED_Peer *peer, + const char *service_name, + GNUNET_TESTBED_ConnectAdapter ca, + GNUNET_TESTBED_DisconnectAdapter da, + void *cada_cls); + + +/** + * Cancel a pending operation. Releases all resources + * of the operation and will ensure that no event + * is generated for the operation. Does NOT guarantee + * that the operation will be fully undone (or that + * nothing ever happened). + * + * @param operation operation to cancel + */ +void +GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation); + + +/** + * Signal that the information from an operation has been fully + * processed. This function MUST be called for each event + * of type 'operation_finished' to fully remove the operation + * from the operation queue. After calling this function, the + * 'op_result' becomes invalid (!). + * + * @param operation operation to signal completion for + */ +void +GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation); + + +/** + * Configure and run a testbed using the given + * master controller on 'num_hosts' starting + * 'num_peers' using the given peer configuration. + * + * @param controller master controller for the testbed + * (must not be destroyed until after the + * testbed is destroyed). + * @param num_hosts number of hosts in 'hosts', 0 to only + * use 'localhost' + * @param hosts list of hosts to use for the testbed + * @param num_peers number of peers to start + * @param peer_cfg peer configuration template to use + * @param underlay_topology underlay topology to create + * @param va topology-specific options + * @return handle to the testbed + */ +struct GNUNET_TESTBED_Testbed * +GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller, + unsigned int num_hosts, + struct GNUNET_TESTBED_Host **hosts, + unsigned int num_peers, + const struct GNUNET_CONFIGURATION_Handle *peer_cfg, + enum GNUNET_TESTBED_TopologyOption underlay_topology, + va_list va); + + +/** + * Configure and run a testbed using the given + * master controller on 'num_hosts' starting + * 'num_peers' using the given peer configuration. + * + * @param controller master controller for the testbed + * (must not be destroyed until after the + * testbed is destroyed). + * @param num_hosts number of hosts in 'hosts', 0 to only + * use 'localhost' + * @param hosts list of hosts to use for the testbed + * @param num_peers number of peers to start + * @param peer_cfg peer configuration template to use + * @param underlay_topology underlay topology to create + * @param ... topology-specific options + */ +struct GNUNET_TESTBED_Testbed * +GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller, + unsigned int num_hosts, + struct GNUNET_TESTBED_Host **hosts, + unsigned int num_peers, + const struct GNUNET_CONFIGURATION_Handle *peer_cfg, + enum GNUNET_TESTBED_TopologyOption underlay_topology, + ...); + + +/** + * Destroy a testbed. Stops all running peers and then + * destroys all peers. Does NOT destroy the master controller. + * + * @param testbed testbed to destroy + */ +void +GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed); + + +/** + * Convenience method for running a testbed with + * a single call. Underlay and overlay topology + * are configured using the "UNDERLAY" and "OVERLAY" + * options in the "[testbed]" section of the configuration\ + * (with possible options given in "UNDERLAY_XXX" and/or + * "OVERLAY_XXX"). + * + * The testbed is to be terminated using a call to + * "GNUNET_SCHEDULER_shutdown". + * + * @param host_filename name of the file with the 'hosts', NULL + * to run everything on 'localhost' + * @param cfg configuration to use (for testbed, controller and peers) + * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg? + * @param event_mask bit mask with set of events to call 'cc' for; + * or-ed values of "1LL" shifted by the + * respective 'enum GNUNET_TESTBED_EventType' + * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") + * @param cc controller callback to invoke on events + * @param cc_cls closure for cc + * @param master task to run once the testbed is ready + * @param master_cls closure for 'task'. + */ +void +GNUNET_TESTBED_run (const char *host_filename, + const struct GNUNET_CONFIGURATION_Handle *cfg, + unsigned int num_peers, + uint64_t event_mask, + GNUNET_TESTBED_ControllerCallback cc, + void *cc_cls, + GNUNET_SCHEDULER_Task master, + void *master_cls); + + +/** + * Signature of a main function for a testcase. + * + * @param cls closure + * @param num_peers number of peers in 'peers' + * @param peers handle to peers run in the testbed + */ +typedef void (*GNUNET_TESTBED_TestMaster)(void *cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer **peers); + + +/** + * Convenience method for running a "simple" test on the local system + * with a single call from 'main'. Underlay and overlay topology are + * configured using the "UNDERLAY" and "OVERLAY" options in the + * "[testbed]" section of the configuration (with possible options + * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). + * + * The test is to be terminated using a call to + * "GNUNET_SCHEDULER_shutdown". If starting the test fails, + * the program is stopped without 'master' ever being run. + * + * NOTE: this function should be called from 'main', NOT from + * within a GNUNET_SCHEDULER-loop. This function will initialze + * the scheduler loop, the testbed and then pass control to + * 'master'. + * + * @param testname name of the testcase (to configure logging, etc.) + * @param cfg_filename configuration filename to use + * (for testbed, controller and peers) + * @param num_peers number of peers to start + * @param test_master task to run once the test is ready + * @param test_master_cls closure for 'task'. + */ +void +GNUNET_TESTBED_test_run (const char *testname, + const char *cfg_filename, + unsigned int num_peers, + GNUNET_TESTBED_TestMaster test_master, + void *test_master_cls); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif + + +#ifdef __cplusplus +} +#endif + +#endif diff --git a/src/include/gnunet_testing_service.h b/src/include/gnunet_testing_service.h deleted file mode 100644 index 6e56093e5..000000000 --- a/src/include/gnunet_testing_service.h +++ /dev/null @@ -1,1009 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file include/gnunet_testing_service.h - * @brief API for writing tests and creating large-scale - * emulation testbeds for GNUnet. - * @author Christian Grothoff - */ - -#ifndef GNUNET_TESTING_SERVICE_H -#define GNUNET_TESTING_SERVICE_H - -#include "gnunet_util_lib.h" - -#ifdef __cplusplus -extern "C" -{ -#if 0 /* keep Emacsens' auto-indent happy */ -} -#endif -#endif - - -/** - * Opaque handle to a host running experiments managed by the testing framework. - * The master process must be able to SSH to this host without password (via - * ssh-agent). - */ -struct GNUNET_TESTING_Host; - -/** - * Opaque handle to a peer controlled by the testing framework. A peer runs - * at a particular host. - */ -struct GNUNET_TESTING_Peer; - -/** - * Opaque handle to an abstract operation to be executed by the testing framework. - */ -struct GNUNET_TESTING_Operation; - -/** - * Handle to interact with a GNUnet testing controller. Each controller has at - * least one master handle which is created when the controller is created; this - * master handle interacts with the controller via stdin/stdout of the controller - * process. Additionally, controllers can interact with each other (in a P2P - * fashion); those links are established via TCP/IP on the controller's service - * port. - */ -struct GNUNET_TESTING_Controller; - -/** - * Handle to a large-scale testbed that is managed at a high level. - */ -struct GNUNET_TESTING_Testbed; - - -/** - * Create a host to run peers and controllers on. - * - * @param hostname name of the host, use "NULL" for localhost - * @param username username to use for the login; may be NULL - * @param port port number to use for ssh; use 0 to let ssh decide - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create (const char *hostname, - const char *username, - uint16_t port); - - -/** - * Load a set of hosts from a configuration file. - * - * @param filename file with the host specification - * @param hosts set to the hosts found in the file - * @return number of hosts returned in 'hosts', 0 on error - */ -unsigned int -GNUNET_TESTING_hosts_load_from_file (const char *filename, - struct GNUNET_TESTING_Host **hosts); - - -/** - * Destroy a host handle. Must only be called once everything - * running on that host has been stopped. - * - * @param host handle to destroy - */ -void -GNUNET_TESTING_host_destroy (struct GNUNET_TESTING_Host *host); - - -/** - * Enumeration with (at most 64) possible event types that - * can be monitored using the testing framework. - */ -enum GNUNET_TESTING_EventType -{ - /** - * A peer has been started. - */ - GNUNET_TESTING_ET_PEER_START = 0, - - /** - * A peer has been stopped. - */ - GNUNET_TESTING_ET_PEER_STOP = 1, - - /** - * A connection between two peers was established. - */ - GNUNET_TESTING_ET_CONNECT = 2, - - /** - * A connection between two peers was torn down. - */ - GNUNET_TESTING_ET_DISCONNECT = 3, - - /** - * A requested testing operation has been completed. - */ - GNUNET_TESTING_ET_OPERATION_FINISHED = 4, - - /** - * The 'GNUNET_TESTING_run' operation has been completed - */ - GNUNET_TESTING_ET_TESTBED_ONLINE = 5 - -}; - - -/** - * Types of information that can be requested about a peer. - */ -enum GNUNET_TESTING_PeerInformationType -{ - - /** - * Special value (not valid for requesting information) - * that is used in the event struct if a 'generic' pointer - * is returned (for other operations not related to this - * enumeration). - */ - GNUNET_TESTING_PIT_GENERIC = 0, - - /** - * What host is the peer running on? Returns a 'const struct - * GNUNET_TESTING_Host *'. Valid until - * 'GNUNET_TESTING_operation_done' is called. - */ - GNUNET_TESTING_PIT_HOST, - - /** - * What configuration is the peer using? Returns a 'const struct - * GNUNET_CONFIGURATION_Handle *'. Valid until - * 'GNUNET_TESTNIG_operation_done' is called. However, the - * values may be inaccurate if the peer is reconfigured in - * the meantime. - */ - GNUNET_TESTING_PIT_CONFIGURATION, - - /** - * What is the identity of the peer? Returns a - * 'const struct GNUNET_PeerIdentity *'. Valid until - * 'GNUNET_TESTNIG_operation_done' is called. - */ - GNUNET_TESTING_PIT_IDENTITY - -}; - - -/** - * Argument to GNUNET_TESTING_ControllerCallback with details about - * the event. - */ -struct GNUNET_TESTING_EventInformation -{ - - /** - * Type of the event. - */ - enum GNUNET_TESTING_EventType type; - - /** - * Details about the event. - */ - union - { - - /** - * Details about peer start event. - */ - struct - { - /** - * Handle for the host where the peer - * was started. - */ - struct GNUNET_TESTING_Host *host; - - /** - * Handle for the peer that was started. - */ - struct GNUNET_TESTING_Peer *peer; - - } peer_start; - - /** - * Details about peer stop event. - */ - struct - { - - /** - * Handle for the peer that was started. - */ - struct GNUNET_TESTING_Peer *peer; - - } peer_stop; - - /** - * Details about connect event. - */ - struct - { - /** - * Handle for one of the connected peers. - */ - struct GNUNET_TESTING_Peer *peer1; - - /** - * Handle for one of the connected peers. - */ - struct GNUNET_TESTING_Peer *peer2; - - } peer_connect; - - /** - * Details about disconnect event. - */ - struct - { - /** - * Handle for one of the disconnected peers. - */ - struct GNUNET_TESTING_Peer *peer1; - - /** - * Handle for one of the disconnected peers. - */ - struct GNUNET_TESTING_Peer *peer2; - - } peer_disconnect; - - /** - * Details about an operation finished event. - */ - struct - { - - /** - * Handle for the operation that was finished. - */ - struct GNUNET_TESTING_Operation *operation; - - /** - * Closure that was passed in when the event was - * requested. - */ - void *op_cls; - - /** - * Error message for the operation, NULL on success. - */ - const char *emsg; - - /** - * Peer information type; captures which of the types - * in the 'op_result' is actually in use. - */ - enum GNUNET_TESTING_PeerInformationType pit; - - /** - * Pointer to an operation-specific return value; NULL on error; - * can be NULL for certain operations. Valid until - * 'GNUNET_TESTING_operation_done' is called. - */ - union - { - /** - * No result (NULL pointer) or generic result - * (whatever the GNUNET_TESTING_ConnectAdapter returned). - */ - void *generic; - - /** - * Identity of host running the peer. - */ - struct GNUNET_TESTING_Host *host; - - /** - * Identity of the peer. - */ - const struct GNUNET_PeerIdentity *pid; - - /** - * Configuration of the peer. - */ - const struct GNUNET_CONFIGURATION_Handle *cfg; - - } op_result; - - } operation_finished; - - - /** - * Details about an testbed run completed event. - */ - struct - { - - /** - * Error message for the operation, NULL on success. - */ - const char *emsg; - - /** - * Array of peers now running (valid until - * 'GNUNET_TESTING_testbed_stop' is called). Note that it is - * not allowed to call 'GNUNET_TESTING_peer_destroy' on peers - * from this array. - */ - struct GNUNET_TESTING_Peer **peers; - - /** - * Size of the 'peers' array. - */ - unsigned int num_peers; - - } testbed_run_finished; - - } details; - -}; - - -/** - * Signature of the event handler function called by the - * respective event controller. - * - * @param cls closure - * @param event information about the event - */ -typedef void (*GNUNET_TESTING_ControllerCallback)(void *cls, - const struct GNUNET_TESTING_EventInformation *event); - - -/** - * Start a controller process using the given configuration at the - * given host. - * - * @param cfg configuration to use - * @param host host to run the controller on, NULL for 'localhost' - * @param event_mask bit mask with set of events to call 'cc' for; - * or-ed values of "1LL" shifted by the - * respective 'enum GNUNET_TESTING_EventType' - * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) | ...") - * @param cc controller callback to invoke on events - * @param cc_cls closure for cc - * @return handle to the controller - */ -struct GNUNET_TESTING_Controller * -GNUNET_TESTING_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_TESTING_Host *host, - uint64_t event_mask, - GNUNET_TESTING_ControllerCallback cc, - void *cc_cls); - - -/** - * Configure shared services at a controller. Using this function, - * you can specify that certain services (such as "resolver") - * should not be run for each peer but instead be shared - * across N peers on the specified host. This function - * must be called before any peers are created at the host. - * - * @param controller controller to configure - * @param service_name name of the service to share - * @param num_peers number of peers that should share one instance - * of the specified service (1 for no sharing is the default), - * use 0 to disable the service - */ -void -GNUNET_TESTING_controller_configure_sharing (struct GNUNET_TESTING_Controller *controller, - const char *service_name, - uint32_t num_peers); - - -/** - * Stop the given controller (also will terminate all peers and - * controllers dependent on this controller). This function - * blocks until the testbed has been fully terminated (!). - * - * @param controller handle to controller to stop - */ -void -GNUNET_TESTING_controller_stop (struct GNUNET_TESTING_Controller *controller); - - -/** - * Create a link from a 'master' controller to a slave controller. - * Whenever the master controller is asked to start a peer at the - * given 'delegated_host', it will delegate the request to the - * specified slave controller. Note that the slave controller runs at - * the 'slave_host', which may or may not be the same host as the - * 'delegated_host' (for hierarchical delegations). The configuration - * of the slave controller is given and to be used to either create - * the slave controller or to connect to an existing slave controller - * process. 'is_subordinate' specifies if the given slave controller - * should be started and managed by the master controller, or if the - * slave already has a master and this is just a secondary master that - * is also allowed to use the existing slave. - * - * @param master handle to the master controller who creates the association - * @param delegated_host requests to which host should be delegated - * @param slave_host which host is used to run the slave controller - * @param slave_cfg configuration to use for the slave controller - * @param is_subordinate GNUNET_YES if the slave should be started (and stopped) - * by the master controller; GNUNET_NO if we are just - * allowed to use the slave via TCP/IP - */ -void -GNUNET_TESTING_controller_link (struct GNUNET_TESTING_Controller *master, - struct GNUNET_TESTING_Host *delegated_host, - struct GNUNET_TESTING_Host *slave_host, - const struct GNUNET_CONFIGURATION_Handle *slave_cfg, - int is_subordinate); - - -/** - * Create the given peer at the specified host using the given - * controller. If the given controller is not running on the target - * host, it should find or create a controller at the target host and - * delegate creating the peer. Explicit delegation paths can be setup - * using 'GNUNET_TESTING_controller_link'. If no explicit delegation - * path exists, a direct link with a subordinate controller is setup - * for the first delegated peer to a particular host; the subordinate - * controller is then destroyed once the last peer that was delegated - * to the remote host is stopped. - * - * Creating the peer only creates the handle to manipulate and further - * configure the peer; use "GNUNET_TESTING_peer_start" and - * "GNUNET_TESTING_peer_stop" to actually start/stop the peer's - * processes. - * - * Note that the given configuration will be adjusted by the - * controller to avoid port/path conflicts with other peers. - * The "final" configuration can be obtained using - * 'GNUNET_TESTING_peer_get_information'. - * - * @param controller controller process to use - * @param host host to run the peer on - * @param cfg configuration to use for the peer - * @return handle to the peer (actual startup will happen asynchronously) - */ -struct GNUNET_TESTING_Peer * -GNUNET_TESTING_peer_create (struct GNUNET_TESTING_Controller *controller, - struct GNUNET_TESTING_Host *host, - const struct GNUNET_CONFIGURATION_Handle *cfg); - - -/** - * Start the given peer. - * - * @param peer peer to start - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_start (struct GNUNET_TESTING_Peer *peer); - - -/** - * Stop the given peer. The handle remains valid (use - * "GNUNET_TESTING_peer_destroy" to fully clean up the - * state of the peer). - * - * @param peer peer to stop - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_stop (struct GNUNET_TESTING_Peer *peer); - - -/** - * Request information about a peer. - * - * @param peer peer to request information about - * @param pit desired information - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_get_information (struct GNUNET_TESTING_Peer *peer, - enum GNUNET_TESTING_PeerInformationType pit); - - -/** - * Change peer configuration. Must only be called while the - * peer is stopped. Ports and paths cannot be changed this - * way. - * - * @param peer peer to change configuration for - * @param cfg new configuration (differences to existing - * configuration only) - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_update_configuration (struct GNUNET_TESTING_Peer *peer, - const struct GNUNET_CONFIGURATION_Handle *cfg); - - -/** - * Destroy the given peer; the peer should have been - * stopped first (if it was started). - * - * @param peer peer to stop - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_destroy (struct GNUNET_TESTING_Peer *peer); - - -/** - * Options for peer connections. - */ -enum GNUNET_TESTING_ConnectOption -{ - /** - * No option (not valid as an argument). - */ - GNUNET_TESTING_CO_NONE = 0, - - /** - * Allow or disallow a connection between the specified peers. - * Followed by GNUNET_NO (int) if a connection is disallowed - * or GNUNET_YES if a connection is allowed. Note that the - * default (all connections allowed or disallowed) is - * specified in the configuration of the controller. - */ - GNUNET_TESTING_CO_ALLOW = 1, - - /** - * FIXME: add (and implement) options to limit connection to - * particular transports, force simulation of particular latencies - * or message loss rates, or set bandwidth limitations. - */ - -}; - - -/** - * Manipulate the P2P underlay topology by configuring a link - * between two peers. - * - * @param op_cls closure argument to give with the operation event - * @param p1 first peer - * @param p2 second peer - * @param co option to change - * @param ... option-specific values - * @return handle to the operation, NULL if configuring the link at this - * time is not allowed - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_link (void *op_cls, - struct GNUNET_TESTING_Peer *p1, - struct GNUNET_TESTING_Peer *p2, - enum GNUNET_TESTING_ConnectOption co, ...); - - - -/** - * Topologies supported for testbeds. - */ -enum GNUNET_TESTING_TopologyOption -{ - /** - * A clique (everyone connected to everyone else). No options. - */ - GNUNET_TESTING_TOPOLOGY_CLIQUE, - - /** - * Small-world network (2d torus plus random links). Followed - * by the number of random links to add (unsigned int). - */ - GNUNET_TESTING_TOPOLOGY_SMALL_WORLD, - - /** - * Small-world network (ring plus random links). Followed - * by the number of random links to add (unsigned int). - */ - GNUNET_TESTING_TOPOLOGY_SMALL_WORLD_RING, - - /** - * Ring topology. No options. - */ - GNUNET_TESTING_TOPOLOGY_RING, - - /** - * 2-d torus. No options. - */ - GNUNET_TESTING_TOPOLOGY_2D_TORUS, - - /** - * Random graph. Followed by the link density, that is the - * percentage of links present in relation to a clique - * (float). - */ - GNUNET_TESTING_TOPOLOGY_ERDOS_RENYI, - - /** - * Certain percentage of peers are unable to communicate directly - * replicating NAT conditions. Followed by the fraction of - * NAT'ed peers (float). - */ - GNUNET_TESTING_TOPOLOGY_INTERNAT, - - /** - * Scale free topology. FIXME: options? - */ - GNUNET_TESTING_TOPOLOGY_SCALE_FREE, - - /** - * Straight line topology. No options. - */ - GNUNET_TESTING_TOPOLOGY_LINE, - - /** - * All peers are disconnected. No options. - */ - GNUNET_TESTING_TOPOLOGY_NONE, - - /** - * Read a topology from a given file. Followed by the name of the file (const char *). - */ - GNUNET_TESTING_TOPOLOGY_FROM_FILE -}; - - -/** - * Configure overall network topology to have a particular shape. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ap topology-specific options - * @return handle to the operation, NULL if configuring the topology - * is not allowed at this time - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_topology_va (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer **peers, - enum GNUNET_TESTING_TopologyOption topo, - va_list ap); - - -/** - * Configure overall network topology to have a particular shape. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ... topology-specific options - * @return handle to the operation, NULL if configuring the topology - * is not allowed at this time - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_topology (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer **peers, - enum GNUNET_TESTING_TopologyOption topo, - ...); - - -/** - * Both peers must have been started before calling this function. - * This function then obtains a HELLO from 'p1', gives it to 'p2' - * and asks 'p2' to connect to 'p1'. - * - * @param op_cls closure argument to give with the operation event - * @param p1 first peer - * @param p2 second peer - * @return handle to the operation, NULL if connecting these two - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_connect (void *op_cls, - struct GNUNET_TESTING_Peer *p1, - struct GNUNET_TESTING_Peer *p2); - - -/** - * All peers must have been started before calling this function. - * This function then connects the given peers in the P2P overlay - * using the given topology. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param va topology-specific options - * @return handle to the operation, NULL if connecting these - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_configure_topology_va (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer *peers, - enum GNUNET_TESTING_TopologyOption topo, - va_list va); - - -/** - * All peers must have been started before calling this function. - * This function then connects the given peers in the P2P overlay - * using the given topology. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ... topology-specific options - * @return handle to the operation, NULL if connecting these - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_configure_topology (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer *peers, - enum GNUNET_TESTING_TopologyOption topo, - ...); - - - -/** - * Ask the testbed controller to write the current overlay topology to - * a file. Naturally, the file will only contain a snapshot as the - * topology may evolve all the time. - * - * @param controller overlay controller to inspect - * @param filename name of the file the topology should - * be written to. - */ -void -GNUNET_TESTING_overlay_write_topology_to_file (struct GNUNET_TESTING_Controller *controller, - const char *filename); - - -/** - * Adapter function called to establish a connection to - * a service. - * - * @param cls closure - * @param cfg configuration of the peer to connect to - * @return service handle to return in 'op_result', NULL on error - */ -typedef void * (*GNUNET_TESTING_ConnectAdapter)(void *cls, - const struct GNUNET_CONFIGURATION_Handle *cfg); - - -/** - * Adapter function called to destroy a connection to - * a service. - * - * @param cls closure - * @param op_result service handle returned from the connect adapter - */ -typedef void (*GNUNET_TESTING_DisconnectAdapter)(void *cls, - void *op_result); - - -/** - * Connect to a service offered by the given peer. Will ensure that - * the request is queued to not overwhelm our ability to create and - * maintain connections with other systems. The actual service - * handle is then returned via the 'op_result' member in the event - * callback. The 'ca' callback is used to create the connection - * when the time is right; the 'da' callback will be used to - * destroy the connection (upon 'GNUNET_TESTING_operation_done'). - * 'GNUNET_TESTING_operation_cancel' can be used to abort this - * operation until the event callback has been called. - * - * @param op_cls closure to pass in operation event - * @param peer peer that runs the service - * @param service_name name of the service to connect to - * @param ca helper function to establish the connection - * @param da helper function to close the connection - * @param cada_cls closure for ca and da - * @return handle for the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_service_connect (void *op_cls, - struct GNUNET_TESTING_Peer *peer, - const char *service_name, - GNUNET_TESTING_ConnectAdapter ca, - GNUNET_TESTING_DisconnectAdapter da, - void *cada_cls); - - -/** - * Cancel a pending operation. Releases all resources - * of the operation and will ensure that no event - * is generated for the operation. Does NOT guarantee - * that the operation will be fully undone (or that - * nothing ever happened). - * - * @param operation operation to cancel - */ -void -GNUNET_TESTING_operation_cancel (struct GNUNET_TESTING_Operation *operation); - - -/** - * Signal that the information from an operation has been fully - * processed. This function MUST be called for each event - * of type 'operation_finished' to fully remove the operation - * from the operation queue. After calling this function, the - * 'op_result' becomes invalid (!). - * - * @param operation operation to signal completion for - */ -void -GNUNET_TESTING_operation_done (struct GNUNET_TESTING_Operation *operation); - - -/** - * Configure and run a testbed using the given - * master controller on 'num_hosts' starting - * 'num_peers' using the given peer configuration. - * - * @param controller master controller for the testbed - * (must not be destroyed until after the - * testbed is destroyed). - * @param num_hosts number of hosts in 'hosts', 0 to only - * use 'localhost' - * @param hosts list of hosts to use for the testbed - * @param num_peers number of peers to start - * @param peer_cfg peer configuration template to use - * @param underlay_topology underlay topology to create - * @param va topology-specific options - * @return handle to the testbed - */ -struct GNUNET_TESTING_Testbed * -GNUNET_TESTING_testbed_create_va (struct GNUNET_TESTING_Controller *controller, - unsigned int num_hosts, - struct GNUNET_TESTING_Host **hosts, - unsigned int num_peers, - const struct GNUNET_CONFIGURATION_Handle *peer_cfg, - enum GNUNET_TESTING_TopologyOption underlay_topology, - va_list va); - - -/** - * Configure and run a testbed using the given - * master controller on 'num_hosts' starting - * 'num_peers' using the given peer configuration. - * - * @param controller master controller for the testbed - * (must not be destroyed until after the - * testbed is destroyed). - * @param num_hosts number of hosts in 'hosts', 0 to only - * use 'localhost' - * @param hosts list of hosts to use for the testbed - * @param num_peers number of peers to start - * @param peer_cfg peer configuration template to use - * @param underlay_topology underlay topology to create - * @param ... topology-specific options - */ -struct GNUNET_TESTING_Testbed * -GNUNET_TESTING_testbed_create (struct GNUNET_TESTING_Controller *controller, - unsigned int num_hosts, - struct GNUNET_TESTING_Host **hosts, - unsigned int num_peers, - const struct GNUNET_CONFIGURATION_Handle *peer_cfg, - enum GNUNET_TESTING_TopologyOption underlay_topology, - ...); - - -/** - * Destroy a testbed. Stops all running peers and then - * destroys all peers. Does NOT destroy the master controller. - * - * @param testbed testbed to destroy - */ -void -GNUNET_TESTING_testbed_destroy (struct GNUNET_TESTING_Testbed *testbed); - - -/** - * Convenience method for running a testbed with - * a single call. Underlay and overlay topology - * are configured using the "UNDERLAY" and "OVERLAY" - * options in the "[testbed]" section of the configuration\ - * (with possible options given in "UNDERLAY_XXX" and/or - * "OVERLAY_XXX"). - * - * The testbed is to be terminated using a call to - * "GNUNET_SCHEDULER_shutdown". - * - * @param host_filename name of the file with the 'hosts', NULL - * to run everything on 'localhost' - * @param cfg configuration to use (for testbed, controller and peers) - * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg? - * @param event_mask bit mask with set of events to call 'cc' for; - * or-ed values of "1LL" shifted by the - * respective 'enum GNUNET_TESTING_EventType' - * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) || ...") - * @param cc controller callback to invoke on events - * @param cc_cls closure for cc - * @param master task to run once the testbed is ready - * @param master_cls closure for 'task'. - */ -void -GNUNET_TESTING_testbed_run (const char *host_filename, - const struct GNUNET_CONFIGURATION_Handle *cfg, - unsigned int num_peers, - uint64_t event_mask, - GNUNET_TESTING_ControllerCallback cc, - void *cc_cls, - GNUNET_SCHEDULER_Task master, - void *master_cls); - - -/** - * Signature of a main function for a testcase. - * - * @param cls closure - * @param num_peers number of peers in 'peers' - * @param peers handle to peers run in the testbed - */ -typedef void (*GNUNET_TESTING_TestMaster)(void *cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer **peers); - - -/** - * Convenience method for running a "simple" test on the local system - * with a single call from 'main'. Underlay and overlay topology are - * configured using the "UNDERLAY" and "OVERLAY" options in the - * "[testbed]" section of the configuration (with possible options - * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). - * - * The test is to be terminated using a call to - * "GNUNET_SCHEDULER_shutdown". If starting the test fails, - * the program is stopped without 'master' ever being run. - * - * NOTE: this function should be called from 'main', NOT from - * within a GNUNET_SCHEDULER-loop. This function will initialze - * the scheduler loop, the testbed and then pass control to - * 'master'. - * - * @param testname name of the testcase (to configure logging, etc.) - * @param cfg_filename configuration filename to use - * (for testbed, controller and peers) - * @param num_peers number of peers to start - * @param test_master task to run once the test is ready - * @param test_master_cls closure for 'task'. - */ -void -GNUNET_TESTING_test_run (const char *testname, - const char *cfg_filename, - unsigned int num_peers, - GNUNET_TESTING_TestMaster test_master, - void *test_master_cls); - - -#if 0 /* keep Emacsens' auto-indent happy */ -{ -#endif - - -#ifdef __cplusplus -} -#endif - -#endif diff --git a/src/testbed/Makefile.am b/src/testbed/Makefile.am new file mode 100644 index 000000000..b7b936004 --- /dev/null +++ b/src/testbed/Makefile.am @@ -0,0 +1,39 @@ +INCLUDES = -I$(top_srcdir)/src/include + +if MINGW + WINFLAGS = -Wl,--no-undefined -Wl,--export-all-symbols +endif + +if USE_COVERAGE + AM_CFLAGS = --coverage -O0 + XLIB = -lgcov +endif + +pkgcfgdir= $(pkgdatadir)/config.d/ + +dist_pkgcfg_DATA = \ + testbed.conf + +lib_LTLIBRARIES = \ + libgnunettestbed.la + +libgnunettestbed_la_SOURCES = \ + testbed_api.c testbed.h \ + testbed_api_hosts.c testbed_api_hosts.h \ + testbed_api_operations.c testbed_api_operations.h \ + testbed_api_peers.c testbed_api_peers.h \ + testbed_api_services.c \ + testbed_api_testbed.c \ + testbed_api_test.c \ + testbed_api_topology.c +libgnunettestbed_la_LIBADD = $(XLIB) \ + $(top_builddir)/src/core/libgnunetcore.la \ + $(top_builddir)/src/statistics/libgnunetstatistics.la \ + $(top_builddir)/src/transport/libgnunettransport.la \ + $(top_builddir)/src/hello/libgnunethello.la \ + -lm \ + $(top_builddir)/src/util/libgnunetutil.la +libgnunettestbed_la_LDFLAGS = \ + $(GN_LIB_LDFLAGS) \ + -version-info 0:0:0 + diff --git a/src/testbed/testbed.conf b/src/testbed/testbed.conf new file mode 100644 index 000000000..e69de29bb diff --git a/src/testbed/testbed.h b/src/testbed/testbed.h new file mode 100644 index 000000000..4e4e490f0 --- /dev/null +++ b/src/testbed/testbed.h @@ -0,0 +1,535 @@ +/* + This file is part of GNUnet + (C) 2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing.h + * @brief IPC messages between testing API and service ("controller") + * @author Christian Grothoff + */ + +#ifndef NEW_TESTING_H +#define NEW_TESTING_H + +#include "gnunet_util_lib.h" + + +/** + * Initial message from a client to a testing control service. + */ +struct GNUNET_TESTBED_Message +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Host ID that the controller is either given + * (if this is the dominating client communicating + * via stdin) or assumed to have (for peer-connections + * between controllers). + */ + uint32_t host_id GNUNET_PACKED; + + /** + * Event mask that specifies which events this client + * is interested in. In NBO. + */ + uint64_t event_mask GNUNET_PACKED; + +}; + + +/** + * Notify the service about a host that we intend to use. + */ +struct GNUNET_TESTBED_AddHostMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the host (in NBO). + */ + uint32_t host_id GNUNET_PACKED; + + /** + * SSH port to use, 0 for default (in NBO). + */ + uint16_t ssh_port GNUNET_PACKED; + + /** + * Number of bytes in the user name that follows; + * 0 to use no user name; otherwise 'strlen (username)', + * excluding 0-termination! + */ + uint16_t user_name_length GNUNET_PACKED; + + /* followed by 0-terminated user name */ + + /* followed by 0-terminated host name */ + +}; + + +/** + * Confirmation from the service that adding a host + * worked (or failed). + */ +struct GNUNET_TESTBED_HostConfirmedMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the host (in NBO). + */ + uint32_t host_id GNUNET_PACKED; + + /* followed by the 0-terminated error message (on failure) + (typical errors include failure to login and + host-id already in use) */ + +}; + + +/** + * Message to testing service: configure service sharing + * at a host. + */ +struct GNUNET_TESTBED_ConfigureSharedServiceMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Host that is being configured. + */ + uint32_t host_id GNUNET_PACKED; + + /** + * Number of peers that should share a service instance; + * 1 for no sharing, 0 to forcefully disable the service. + */ + uint32_t num_peers GNUNET_PACKED; + + /* followed by 0-terminated name of the service */ + +}; + + +/** + * Client notifies controller that it should delegate + * requests for a particular client to a particular + * sub-controller. + */ +struct GNUNET_TESTBED_ControllerLinkMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * For which host should requests be delegated? NBO. + */ + uint32_t delegated_host_id GNUNET_PACKED; + + /** + * Which host is responsible for managing the delegation? NBO + */ + uint32_t slave_host_id GNUNET_PACKED; + + /** + * Is the receiving controller the master controller for + * the slave host (and thus responsible for starting it?). NBO. + */ + int32_t is_subordinate GNUNET_PACKED; + + /* followed by serialized slave configuration; + gzip'ed configuration file in INI format */ + +}; + + +/** + * Message sent from client to testing service to + * create (configure, but not start) a peer. + */ +struct GNUNET_TESTBED_PeerCreateMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * On which host should the peer be started? + */ + uint32_t host_id GNUNET_PACKED; + + /** + * Unique ID for the peer. + */ + uint32_t peer_id GNUNET_PACKED; + + /* followed by serialized peer configuration; + gzip'ed configuration file in INI format */ + +}; + + +/** + * Message sent from client to testing service to + * reconfigure a (stopped) a peer. + */ +struct GNUNET_TESTBED_PeerReconfigureMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the peer. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + + /* followed by serialized peer configuration; + gzip'ed configuration file in INI format */ + +}; + + +/** + * Message sent from client to testing service to + * start a peer. + */ +struct GNUNET_TESTBED_PeerStartMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the peer. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + + +/** + * Message sent from client to testing service to + * stop a peer. + */ +struct GNUNET_TESTBED_PeerStopMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the peer. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + + +/** + * Message sent from client to testing service to + * destroy a (stopped) peer. + */ +struct GNUNET_TESTBED_PeerDestroyMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the peer. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + + +/** + * Message sent from client to testing service to + * (re)configure a "physical" link between two peers. + */ +struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * 'enum GNUNET_TESTBED_ConnectOption' of the option to change + */ + int32_t connect_option GNUNET_PACKED; + + /** + * Unique ID for the first peer. + */ + uint32_t peer1 GNUNET_PACKED; + + /** + * Unique ID for the second peer. + */ + uint32_t peer2 GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + + /* followed by option-dependent variable-size values */ + +}; + + +/** + * Message sent from client to testing service to + * connect two peers. + */ +struct GNUNET_TESTBED_OverlayConnectMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Unique ID for the first peer. + */ + uint32_t peer1 GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + + /** + * Unique ID for the second peer. + */ + uint32_t peer2 GNUNET_PACKED; + +}; + + +/** + * Event notification from a controller to a client. + */ +struct GNUNET_TESTBED_PeerEventMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * 'enum GNUNET_TESTBED_EventType' (in NBO); + * either GNUNET_TESTBED_ET_PEER_START or GNUNET_TESTBED_ET_PEER_STOP. + */ + int32_t event_type GNUNET_PACKED; + + /** + * Host where the peer is running. + */ + uint32_t host_id GNUNET_PACKED; + + /** + * Peer that was started or stopped. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + + +/** + * Event notification from a controller to a client. + */ +struct GNUNET_TESTBED_ConnectionEventMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * 'enum GNUNET_TESTBED_EventType' (in NBO); + * either GNUNET_TESTBED_ET_PEER_CONNECT or GNUNET_TESTBED_ET_PEER_DISCONNECT. + */ + int32_t event_type GNUNET_PACKED; + + /** + * First peer. + */ + uint32_t peer1 GNUNET_PACKED; + + /** + * Second peer. + */ + uint32_t peer2 GNUNET_PACKED; + + /** + * Operation ID that is used to identify this operation. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + + +/** + * Event notification from a controller to a client. + */ +struct GNUNET_TESTBED_OperationFailureEventMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * 'enum GNUNET_TESTBED_EventType' (in NBO); + * GNUNET_TESTBED_ET_OPERATION_FINISHED. + */ + int32_t event_type GNUNET_PACKED; + + /** + * Operation ID of the operation that created this event. + */ + uint64_t operation_id GNUNET_PACKED; + + /* followed by 0-terminated error message */ + +}; + + +/** + * Event notification from a controller to a client. + */ +struct GNUNET_TESTBED_PeerCreateSuccessEventMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * Peer identity of the peer that was created. + */ + uint32_t peer_id GNUNET_PACKED; + + /** + * Operation ID of the operation that created this event. + */ + uint64_t operation_id GNUNET_PACKED; + + /** + * Identity of the peer. + */ + struct GNUNET_PeerIdentity peer_id; + + /* followed by gzip-compressed configuration of the peer */ + +}; + + +/** + * Event notification from a controller to a client for + * a generic operational success where the operation does + * not return any data. + */ +struct GNUNET_TESTBED_GenericOperationSuccessEventMessage +{ + + /** + * Type is + */ + struct GNUNET_MessageHeader header; + + /** + * 'enum GNUNET_TESTBED_EventType' (in NBO); + * GNUNET_TESTBED_ET_OPERATION_FINISHED. + */ + int32_t event_type GNUNET_PACKED; + + /** + * Operation ID of the operation that created this event. + */ + uint64_t operation_id GNUNET_PACKED; + +}; + +#endif diff --git a/src/testbed/testbed_api.c b/src/testbed/testbed_api.c new file mode 100644 index 000000000..bffe8162f --- /dev/null +++ b/src/testbed/testbed_api.c @@ -0,0 +1,150 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api.c + * @brief API for accessing the GNUnet testing service. + * This library is supposed to make it easier to write + * testcases and script large-scale benchmarks. + * @author Christian Grothoff + */ +#include "platform.h" +#include "gnunet_testing_service.h" +#include "gnunet_core_service.h" +#include "gnunet_constants.h" +#include "gnunet_transport_service.h" +#include "gnunet_hello_lib.h" + + + + +/** + * Start a controller process using the given configuration at the + * given host. + * + * @param cfg configuration to use + * @param host host to run the controller on, NULL for 'localhost' + * @param event_mask bit mask with set of events to call 'cc' for; + * or-ed values of "1LL" shifted by the + * respective 'enum GNUNET_TESTBED_EventType' + * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) | ...") + * @param cc controller callback to invoke on events + * @param cc_cls closure for cc + * @return handle to the controller + */ +struct GNUNET_TESTBED_Controller * +GNUNET_TESTBED_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg, + struct GNUNET_TESTBED_Host *host, + uint64_t event_mask, + GNUNET_TESTBED_ControllerCallback cc, + void *cc_cls) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Configure shared services at a controller. Using this function, + * you can specify that certain services (such as "resolver") + * should not be run for each peer but instead be shared + * across N peers on the specified host. This function + * must be called before any peers are created at the host. + * + * @param controller controller to configure + * @param service_name name of the service to share + * @param num_peers number of peers that should share one instance + * of the specified service (1 for no sharing is the default), + * use 0 to disable the service + */ +void +GNUNET_TESTBED_controller_configure_sharing (struct GNUNET_TESTBED_Controller *controller, + const char *service_name, + uint32_t num_peers) +{ + GNUNET_break (0); +} + + +/** + * Stop the given controller (also will terminate all peers and + * controllers dependent on this controller). This function + * blocks until the testbed has been fully terminated (!). + * + * @param controller handle to controller to stop + */ +void +GNUNET_TESTBED_controller_stop (struct GNUNET_TESTBED_Controller *controller) +{ + GNUNET_break (0); +} + + +/** + * Create a link from a 'master' controller to a slave controller. + * Whenever the master controller is asked to start a peer at the + * given 'delegated_host', it will delegate the request to the + * specified slave controller. Note that the slave controller runs at + * the 'slave_host', which may or may not be the same host as the + * 'delegated_host' (for hierarchical delegations). The configuration + * of the slave controller is given and to be used to either create + * the slave controller or to connect to an existing slave controller + * process. 'is_subordinate' specifies if the given slave controller + * should be started and managed by the master controller, or if the + * slave already has a master and this is just a secondary master that + * is also allowed to use the existing slave. + * + * @param master handle to the master controller who creates the association + * @param delegated_host requests to which host should be delegated + * @param slave_host which host is used to run the slave controller + * @param slave_cfg configuration to use for the slave controller + * @param is_subordinate GNUNET_YES if the slave should be started (and stopped) + * by the master controller; GNUNET_NO if we are just + * allowed to use the slave via TCP/IP + */ +void +GNUNET_TESTBED_controller_link (struct GNUNET_TESTBED_Controller *master, + struct GNUNET_TESTBED_Host *delegated_host, + struct GNUNET_TESTBED_Host *slave_host, + const struct GNUNET_CONFIGURATION_Handle *slave_cfg, + int is_subordinate) +{ + GNUNET_break (0); +} + + +/** + * Ask the testbed controller to write the current overlay topology to + * a file. Naturally, the file will only contain a snapshot as the + * topology may evolve all the time. + * + * @param controller overlay controller to inspect + * @param filename name of the file the topology should + * be written to. + */ +void +GNUNET_TESTBED_overlay_write_topology_to_file (struct GNUNET_TESTBED_Controller *controller, + const char *filename) +{ +} + + + +/* end of new_testing_api.c */ diff --git a/src/testbed/testbed_api_hosts.c b/src/testbed/testbed_api_hosts.c new file mode 100644 index 000000000..f9ddfdc07 --- /dev/null +++ b/src/testbed/testbed_api_hosts.c @@ -0,0 +1,200 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_hosts.c + * @brief API for manipulating 'hosts' controlled by the GNUnet testing service; + * allows parsing hosts files, starting, stopping and communicating (via + * SSH/stdin/stdout) with the remote (or local) processes + * @author Christian Grothoff + */ +#include "platform.h" +#include "gnunet_testing_service.h" +#include "gnunet_core_service.h" +#include "gnunet_constants.h" +#include "gnunet_transport_service.h" +#include "gnunet_hello_lib.h" + + + +/** + * Opaque handle to a host running experiments managed by the testing framework. + * The master process must be able to SSH to this host without password (via + * ssh-agent). + */ +struct GNUNET_TESTBED_Host +{ + + + const char *hostname; + + const char *username; + + /** + * Global ID we use to refer to a host on the network + */ + uint32_t unique_id; + + uint16_t port; +}; + + +/** + * Lookup a host by ID. + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_lookup_by_id_ (uint32_t id) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Create a host by ID; given this host handle, we could not + * run peers at the host, but we can talk about the host + * internally. + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create_by_id_ (uint32_t id) +{ + return NULL; +} + + +/** + * Obtain a host's unique global ID. + * + * @param host handle to the host, NULL means 'localhost' + * @return id global host ID assigned to the host (0 is + * 'localhost', but then obviously not globally unique) + */ +uint32_t +GNUNET_TESTBED_host_get_id_ (struct GNUNET_TESTBED_Host *host) +{ + GNUNET_break (0); + return 0; +} + + +/** + * Create a host to run peers and controllers on. + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @param hostname name of the host, use "NULL" for localhost + * @param username username to use for the login; may be NULL + * @param port port number to use for ssh; use 0 to let ssh decide + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create_with_id_ (uint32_t id, + const char *hostname, + const char *username, + uint16_t port) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Create a host to run peers and controllers on. + * + * @param hostname name of the host, use "NULL" for localhost + * @param username username to use for the login; may be NULL + * @param port port number to use for ssh; use 0 to let ssh decide + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create (const char *hostname, + const char *username, + uint16_t port) +{ + static uint32_t uid_generator; + + return GNUNET_TESTBED_host_create_with_id_ (++uid_generator, + hostname, username, + port); +} + + +/** + * Load a set of hosts from a configuration file. + * + * @param filename file with the host specification + * @param hosts set to the hosts found in the file + * @return number of hosts returned in 'hosts', 0 on error + */ +unsigned int +GNUNET_TESTBED_hosts_load_from_file (const char *filename, + struct GNUNET_TESTBED_Host **hosts) +{ + GNUNET_break (0); + return 0; +} + + +/** + * Destroy a host handle. Must only be called once everything + * running on that host has been stopped. + * + * @param host handle to destroy + */ +void +GNUNET_TESTBED_host_destroy (struct GNUNET_TESTBED_Host *host) +{ + GNUNET_break (0); +} + + +/** + * Run a given helper process at the given host. Communication + * with the helper will be via GNUnet messages on stdin/stdout. + * Runs the process via 'ssh' at the specified host, or locally. + * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API. + * + * @param host host to use, use "NULL" for localhost + * @param binary_argv binary name and command-line arguments to give to the binary + * @param cb function to call for messages received from the binary + * @param cb_cls closure for cb + * @return handle to terminate the command, NULL on error + */ +struct GNUNET_HELPER_Handle * +GNUNET_TESTBED_host_run_ (struct GNUNET_TESTBED_Host *host, + char *const binary_argv[], + GNUNET_SERVER_MessageTokenizerCallback cb, void *cb_cls) +{ + /* FIXME: decide on the SSH command line, prepend it and + run GNUNET_HELPER_start with the modified binary_name and binary_argv! */ + GNUNET_break (0); + return NULL; +} + + +/* end of new_testing_api_hosts.c */ diff --git a/src/testbed/testbed_api_hosts.h b/src/testbed/testbed_api_hosts.h new file mode 100644 index 000000000..269b3f2af --- /dev/null +++ b/src/testbed/testbed_api_hosts.h @@ -0,0 +1,105 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_hosts.h + * @brief internal API to access the 'hosts' subsystem + * @author Christian Grothoff + */ +#ifndef NEW_TESTING_API_HOSTS_H +#define NEW_TESTING_API_HOSTS_H + +#include "gnunet_testing_service.h" +#include "gnunet_helper_lib.h" + + +/** + * Lookup a host by ID. + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_lookup_by_id_ (uint32_t id); + + +/** + * Create a host by ID; given this host handle, we could not + * run peers at the host, but we can talk about the host + * internally. + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create_by_id_ (uint32_t id); + + +/** + * Create a host to run peers and controllers on. This function is used + * if a peer learns about a host via IPC between controllers (and thus + * some higher-level controller has already determined the unique IDs). + * + * @param id global host ID assigned to the host; 0 is + * reserved to always mean 'localhost' + * @param hostname name of the host, use "NULL" for localhost + * @param username username to use for the login; may be NULL + * @param port port number to use for ssh; use 0 to let ssh decide + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Host * +GNUNET_TESTBED_host_create_with_id_ (uint32_t id, + const char *hostname, + const char *username, + uint16_t port); + + +/** + * Obtain a host's unique global ID. + * + * @param host handle to the host, NULL means 'localhost' + * @return id global host ID assigned to the host (0 is + * 'localhost', but then obviously not globally unique) + */ +uint32_t +GNUNET_TESTBED_host_get_id_ (struct GNUNET_TESTBED_Host *host); + + +/** + * Run a given helper process at the given host. Communication + * with the helper will be via GNUnet messages on stdin/stdout. + * Runs the process via 'ssh' at the specified host, or locally. + * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API. + * + * @param host host to use, use "NULL" for localhost + * @param binary_argv binary name and command-line arguments to give to the binary + * @param cb function to call for messages received from the binary + * @param cb_cls closure for cb + * @return handle to terminate the command, NULL on error + */ +struct GNUNET_HELPER_Handle * +GNUNET_TESTBED_host_run_ (struct GNUNET_TESTBED_Host *host, + char *const binary_argv[], + GNUNET_SERVER_MessageTokenizerCallback cb, void *cb_cls); + +#endif +/* end of new_testing_api_hosts.h */ diff --git a/src/testbed/testbed_api_operations.c b/src/testbed/testbed_api_operations.c new file mode 100644 index 000000000..fa75cf435 --- /dev/null +++ b/src/testbed/testbed_api_operations.c @@ -0,0 +1,74 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_operations.c + * @brief functions to manage operation queues + * @author Christian Grothoff + */ +#include "platform.h" +#include "new_testing_api_operations.h" + + +/** + * Opaque handle to an abstract operation to be executed by the testing framework. + */ +struct GNUNET_TESTBED_Operation +{ + // FIXME! +}; + + + +/** + * Cancel a pending operation. Releases all resources + * of the operation and will ensure that no event + * is generated for the operation. Does NOT guarantee + * that the operation will be fully undone (or that + * nothing ever happened). + * + * @param operation operation to cancel + */ +void +GNUNET_TESTBED_operation_cancel (struct GNUNET_TESTBED_Operation *operation) +{ + GNUNET_break (0); + +} + + +/** + * Signal that the information from an operation has been fully + * processed. This function MUST be called for each event + * of type 'operation_finished' to fully remove the operation + * from the operation queue. After calling this function, the + * 'op_result' becomes invalid (!). + * + * @param operation operation to signal completion for + */ +void +GNUNET_TESTBED_operation_done (struct GNUNET_TESTBED_Operation *operation) +{ + GNUNET_break (0); +} + + + +/* end of new_testing_api_operations.c */ diff --git a/src/testbed/testbed_api_operations.h b/src/testbed/testbed_api_operations.h new file mode 100644 index 000000000..3636fa421 --- /dev/null +++ b/src/testbed/testbed_api_operations.h @@ -0,0 +1,34 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_operations.h + * @brief internal API to access the 'operations' subsystem + * @author Christian Grothoff + */ +#ifndef NEW_TESTING_API_OPERATIONS_H +#define NEW_TESTING_API_OPERATIONS_H + +#include "gnunet_testing_service.h" +#include "gnunet_helper_lib.h" + + +#endif +/* end of new_testing_api_operations.h */ diff --git a/src/testbed/testbed_api_peers.c b/src/testbed/testbed_api_peers.c new file mode 100644 index 000000000..c73a0958a --- /dev/null +++ b/src/testbed/testbed_api_peers.c @@ -0,0 +1,297 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_peers.c + * @brief management of the knowledge about peers in this library + * (we know the peer ID, its host, pending operations, etc.) + * @author Christian Grothoff + */ +#include "platform.h" +#include "new_testing_api_peers.h" + + +/** + * Details about a peer; kept in a separate struct to avoid bloating + * memory consumption everywhere... + */ +struct PeerDetails +{ + /** + * Configuration of the peer; NULL if we are not sure what the peer's correct + * configuration actually is; non-NULL if this peer is controlled by this + * process. + */ + struct GNUNET_CONFIGURATION_Handle *cfg; + + /** + * If this process has started this peer's ARM process, this is the handle + * to the 'gnunet-service-arm' process of the peer. + */ + struct GNUNET_OS_Process *arm; + + // ... + +}; + + +/** + * A peer controlled by the testing framework. A peer runs + * at a particular host. + */ +struct GNUNET_TESTBED_Peer +{ + /** + * Our controller context (not necessarily the controller + * that is responsible for starting/running the peer!). + */ + struct GNUNET_TESTBED_Controller *controller; + + /** + * Which host does this peer run on? + */ + struct GNUENT_TESTING_Host *host; + + /** + * Globally unique ID of the peer. + */ + uint32_t unique_id; + + /** + * Internals of the peer for the controlling process; NULL if + * this process is not controlling this peer. + */ + struct PeerDetails *details; + +}; + + +/** + * Lookup a peer by ID. + * + * @param id global peer ID assigned to the peer + * @return handle to the host, NULL on error + */ +struct GNUNET_TESTBED_Peer * +GNUNET_TESTBED_peer_lookup_by_id_ (uint32_t id) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Create the given peer at the specified host using the given + * controller. If the given controller is not running on the target + * host, it should find or create a controller at the target host and + * delegate creating the peer. Explicit delegation paths can be setup + * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation + * path exists, a direct link with a subordinate controller is setup + * for the first delegated peer to a particular host; the subordinate + * controller is then destroyed once the last peer that was delegated + * to the remote host is stopped. This function is used in particular + * if some other controller has already assigned a unique ID to the + * peer. + * + * Creating the peer only creates the handle to manipulate and further + * configure the peer; use "GNUNET_TESTBED_peer_start" and + * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's + * processes. + * + * Note that the given configuration will be adjusted by the + * controller to avoid port/path conflicts with other peers. + * The "final" configuration can be obtained using + * 'GNUNET_TESTBED_peer_get_information'. + * + * @param unique_id unique ID for this peer + * @param controller controller process to use + * @param host host to run the peer on + * @param cfg configuration to use for the peer + * @return handle to the peer (actual startup will happen asynchronously) + */ +struct GNUNET_TESTBED_Peer * +GNUNET_TESTBED_peer_create_with_id_ (uint32_t unique_id, + struct GNUNET_TESTBED_Controller *controller, + struct GNUNET_TESTBED_Host *host, + const struct GNUNET_CONFIGURATION_Handle *cfg) +{ + // FIXME: create locally or delegate... + GNUNET_break (0); + return NULL; +} + + +/** + * Create the given peer at the specified host using the given + * controller. If the given controller is not running on the target + * host, it should find or create a controller at the target host and + * delegate creating the peer. Explicit delegation paths can be setup + * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation + * path exists, a direct link with a subordinate controller is setup + * for the first delegated peer to a particular host; the subordinate + * controller is then destroyed once the last peer that was delegated + * to the remote host is stopped. + * + * Creating the peer only creates the handle to manipulate and further + * configure the peer; use "GNUNET_TESTBED_peer_start" and + * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's + * processes. + * + * Note that the given configuration will be adjusted by the + * controller to avoid port/path conflicts with other peers. + * The "final" configuration can be obtained using + * 'GNUNET_TESTBED_peer_get_information'. + * + * @param controller controller process to use + * @param host host to run the peer on + * @param cfg configuration to use for the peer + * @return handle to the peer (actual startup will happen asynchronously) + */ +struct GNUNET_TESTBED_Peer * +GNUNET_TESTBED_peer_create (struct GNUNET_TESTBED_Controller *controller, + struct GNUNET_TESTBED_Host *host, + const struct GNUNET_CONFIGURATION_Handle *cfg) +{ + static uint32_t id_gen; + + return GNUNET_TESTBED_peer_create_with_id_ (++id_gen, + controller, + host, + cfg); +} + + +/** + * Start the given peer. + * + * @param peer peer to start + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_start (struct GNUNET_TESTBED_Peer *peer) +{ + // FIXME: start locally or delegate... + GNUNET_break (0); + return NULL; +} + + +/** + * Stop the given peer. The handle remains valid (use + * "GNUNET_TESTBED_peer_destroy" to fully clean up the + * state of the peer). + * + * @param peer peer to stop + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_stop (struct GNUNET_TESTBED_Peer *peer) +{ + // FIXME: stop locally or delegate... + GNUNET_break (0); + return NULL; +} + + +/** + * Request information about a peer. + * + * @param peer peer to request information about + * @param pit desired information + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_get_information (struct GNUNET_TESTBED_Peer *peer, + enum GNUNET_TESTBED_PeerInformationType pit) +{ + // FIXME: handle locally or delegate... + GNUNET_break (0); + return NULL; +} + + +/** + * Change peer configuration. Must only be called while the + * peer is stopped. Ports and paths cannot be changed this + * way. + * + * @param peer peer to change configuration for + * @param cfg new configuration (differences to existing + * configuration only) + * @return handle to the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_peer_update_configuration (struct GNUNET_TESTBED_Peer *peer, + const struct GNUNET_CONFIGURATION_Handle *cfg) +{ + // FIXME: handle locally or delegate... + GNUNET_break (0); + return NULL; +} + + +/** + * Manipulate the P2P underlay topology by configuring a link + * between two peers. + * + * @param op_cls closure argument to give with the operation event + * @param p1 first peer + * @param p2 second peer + * @param co option to change + * @param ... option-specific values + * @return handle to the operation, NULL if configuring the link at this + * time is not allowed + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_link (void *op_cls, + struct GNUNET_TESTBED_Peer *p1, + struct GNUNET_TESTBED_Peer *p2, + enum GNUNET_TESTBED_ConnectOption co, ...) +{ + GNUNET_break (0); + return NULL; +} + + + +/** + * Both peers must have been started before calling this function. + * This function then obtains a HELLO from 'p1', gives it to 'p2' + * and asks 'p2' to connect to 'p1'. + * + * @param op_cls closure argument to give with the operation event + * @param p1 first peer + * @param p2 second peer + * @return handle to the operation, NULL if connecting these two + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_connect (void *op_cls, + struct GNUNET_TESTBED_Peer *p1, + struct GNUNET_TESTBED_Peer *p2) +{ + GNUNET_break (0); + return NULL; +} + + + +/* end of new_testing_api_peers.c */ diff --git a/src/testbed/testbed_api_peers.h b/src/testbed/testbed_api_peers.h new file mode 100644 index 000000000..6b2ed7c8b --- /dev/null +++ b/src/testbed/testbed_api_peers.h @@ -0,0 +1,71 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_peers.h + * @brief internal API to access the 'peers' subsystem + * @author Christian Grothoff + */ +#ifndef NEW_TESTING_API_PEERS_H +#define NEW_TESTING_API_PEERS_H + +#include "gnunet_testing_service.h" +#include "gnunet_helper_lib.h" + + +/** + * Create the given peer at the specified host using the given + * controller. If the given controller is not running on the target + * host, it should find or create a controller at the target host and + * delegate creating the peer. Explicit delegation paths can be setup + * using 'GNUNET_TESTBED_controller_link'. If no explicit delegation + * path exists, a direct link with a subordinate controller is setup + * for the first delegated peer to a particular host; the subordinate + * controller is then destroyed once the last peer that was delegated + * to the remote host is stopped. This function is used in particular + * if some other controller has already assigned a unique ID to the + * peer. + * + * Creating the peer only creates the handle to manipulate and further + * configure the peer; use "GNUNET_TESTBED_peer_start" and + * "GNUNET_TESTBED_peer_stop" to actually start/stop the peer's + * processes. + * + * Note that the given configuration will be adjusted by the + * controller to avoid port/path conflicts with other peers. + * The "final" configuration can be obtained using + * 'GNUNET_TESTBED_peer_get_information'. + * + * @param unique_id unique ID for this peer + * @param controller controller process to use + * @param host host to run the peer on + * @param cfg configuration to use for the peer + * @return handle to the peer (actual startup will happen asynchronously) + */ +struct GNUNET_TESTBED_Peer * +GNUNET_TESTBED_peer_create_with_id_ (uint32_t unique_id, + struct GNUNET_TESTBED_Controller *controller, + struct GNUNET_TESTBED_Host *host, + const struct GNUNET_CONFIGURATION_Handle *cfg); + + + +#endif +/* end of new_testing_api_peers.h */ diff --git a/src/testbed/testbed_api_services.c b/src/testbed/testbed_api_services.c new file mode 100644 index 000000000..524ec35e3 --- /dev/null +++ b/src/testbed/testbed_api_services.c @@ -0,0 +1,61 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_services.c + * @brief convenience functions for accessing services + * @author Christian Grothoff + */ +#include "platform.h" +#include "new_testing_api_peers.h" + + +/** + * Connect to a service offered by the given peer. Will ensure that + * the request is queued to not overwhelm our ability to create and + * maintain connections with other systems. The actual service + * handle is then returned via the 'op_result' member in the event + * callback. The 'ca' callback is used to create the connection + * when the time is right; the 'da' callback will be used to + * destroy the connection (upon 'GNUNET_TESTBED_operation_done'). + * 'GNUNET_TESTBED_operation_cancel' can be used to abort this + * operation until the event callback has been called. + * + * @param op_cls closure to pass in operation event + * @param peer peer that runs the service + * @param service_name name of the service to connect to + * @param ca helper function to establish the connection + * @param da helper function to close the connection + * @param cada_cls closure for ca and da + * @return handle for the operation + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_service_connect (void *op_cls, + struct GNUNET_TESTBED_Peer *peer, + const char *service_name, + GNUNET_TESTBED_ConnectAdapter ca, + GNUNET_TESTBED_DisconnectAdapter da, + void *cada_cls) +{ + GNUNET_break (0); + return NULL; +} + +/* end of new_testing_api_services.c */ diff --git a/src/testbed/testbed_api_test.c b/src/testbed/testbed_api_test.c new file mode 100644 index 000000000..ed5e2e8e3 --- /dev/null +++ b/src/testbed/testbed_api_test.c @@ -0,0 +1,67 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_test.c + * @brief high-level test function + * @author Christian Grothoff + */ +#include "platform.h" +#include "gnunet_testing_service.h" + + + + +/** + * Convenience method for running a "simple" test on the local system + * with a single call from 'main'. Underlay and overlay topology are + * configured using the "UNDERLAY" and "OVERLAY" options in the + * "[testbed]" section of the configuration (with possible options + * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). + * + * The test is to be terminated using a call to + * "GNUNET_SCHEDULER_shutdown". If starting the test fails, + * the program is stopped without 'master' ever being run. + * + * NOTE: this function should be called from 'main', NOT from + * within a GNUNET_SCHEDULER-loop. This function will initialze + * the scheduler loop, the testbed and then pass control to + * 'master'. + * + * @param testname name of the testcase (to configure logging, etc.) + * @param cfg_filename configuration filename to use + * (for testbed, controller and peers) + * @param num_peers number of peers to start + * @param test_master task to run once the test is ready + * @param test_master_cls closure for 'task'. + */ +void +GNUNET_TESTBED_test_run (const char *testname, + const char *cfg_filename, + unsigned int num_peers, + GNUNET_TESTBED_TestMaster test_master, + void *test_master_cls) +{ + GNUNET_break (0); +} + + + +/* end of new_testing_api_test.c */ diff --git a/src/testbed/testbed_api_testbed.c b/src/testbed/testbed_api_testbed.c new file mode 100644 index 000000000..8c917db81 --- /dev/null +++ b/src/testbed/testbed_api_testbed.c @@ -0,0 +1,153 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_testbed.c + * @brief high-level testbed management + * @author Christian Grothoff + */ +#include "platform.h" +#include "gnunet_testing_service.h" + + +/** + * Opaque handle to an abstract operation to be executed by the testing framework. + */ +struct GNUNET_TESTBED_Testbed +{ + // FIXME! +}; + + +/** + * Configure and run a testbed using the given + * master controller on 'num_hosts' starting + * 'num_peers' using the given peer configuration. + * + * @param controller master controller for the testbed + * (must not be destroyed until after the + * testbed is destroyed). + * @param num_hosts number of hosts in 'hosts', 0 to only + * use 'localhost' + * @param hosts list of hosts to use for the testbed + * @param num_peers number of peers to start + * @param peer_cfg peer configuration template to use + * @param underlay_topology underlay topology to create + * @param va topology-specific options + * @return handle to the testbed + */ +struct GNUNET_TESTBED_Testbed * +GNUNET_TESTBED_create_va (struct GNUNET_TESTBED_Controller *controller, + unsigned int num_hosts, + struct GNUNET_TESTBED_Host **hosts, + unsigned int num_peers, + const struct GNUNET_CONFIGURATION_Handle *peer_cfg, + enum GNUNET_TESTBED_TopologyOption underlay_topology, + va_list va) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Configure and run a testbed using the given + * master controller on 'num_hosts' starting + * 'num_peers' using the given peer configuration. + * + * @param controller master controller for the testbed + * (must not be destroyed until after the + * testbed is destroyed). + * @param num_hosts number of hosts in 'hosts', 0 to only + * use 'localhost' + * @param hosts list of hosts to use for the testbed + * @param num_peers number of peers to start + * @param peer_cfg peer configuration template to use + * @param underlay_topology underlay topology to create + * @param ... topology-specific options + */ +struct GNUNET_TESTBED_Testbed * +GNUNET_TESTBED_create (struct GNUNET_TESTBED_Controller *controller, + unsigned int num_hosts, + struct GNUNET_TESTBED_Host **hosts, + unsigned int num_peers, + const struct GNUNET_CONFIGURATION_Handle *peer_cfg, + enum GNUNET_TESTBED_TopologyOption underlay_topology, + ...) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Destroy a testbed. Stops all running peers and then + * destroys all peers. Does NOT destroy the master controller. + * + * @param testbed testbed to destroy + */ +void +GNUNET_TESTBED_destroy (struct GNUNET_TESTBED_Testbed *testbed) +{ + GNUNET_break (0); +} + + + +/** + * Convenience method for running a testbed with + * a single call. Underlay and overlay topology + * are configured using the "UNDERLAY" and "OVERLAY" + * options in the "[testbed]" section of the configuration\ + * (with possible options given in "UNDERLAY_XXX" and/or + * "OVERLAY_XXX"). + * + * The testbed is to be terminated using a call to + * "GNUNET_SCHEDULER_shutdown". + * + * @param host_filename name of the file with the 'hosts', NULL + * to run everything on 'localhost' + * @param cfg configuration to use (for testbed, controller and peers) + * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg? + * @param event_mask bit mask with set of events to call 'cc' for; + * or-ed values of "1LL" shifted by the + * respective 'enum GNUNET_TESTBED_EventType' + * (i.e. "(1LL << GNUNET_TESTBED_ET_CONNECT) || ...") + * @param cc controller callback to invoke on events + * @param cc_cls closure for cc + * @param master task to run once the testbed is ready + * @param master_cls closure for 'task'. + */ +void +GNUNET_TESTBED_run (const char *host_filename, + const struct GNUNET_CONFIGURATION_Handle *cfg, + unsigned int num_peers, + uint64_t event_mask, + GNUNET_TESTBED_ControllerCallback cc, + void *cc_cls, + GNUNET_SCHEDULER_Task master, + void *master_cls) +{ + GNUNET_break (0); +} + + + +/* end of new_testing_api_testbed.c */ diff --git a/src/testbed/testbed_api_topology.c b/src/testbed/testbed_api_topology.c new file mode 100644 index 000000000..12def3a1f --- /dev/null +++ b/src/testbed/testbed_api_topology.c @@ -0,0 +1,127 @@ +/* + This file is part of GNUnet + (C) 2008--2012 Christian Grothoff (and other contributing authors) + + GNUnet is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published + by the Free Software Foundation; either version 3, or (at your + option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with GNUnet; see the file COPYING. If not, write to the + Free Software Foundation, Inc., 59 Temple Place - Suite 330, + Boston, MA 02111-1307, USA. + */ + +/** + * @file testing/new_testing_api_topology.c + * @brief topology-generation functions + * @author Christian Grothoff + */ +#include "platform.h" +#include "gnunet_testing_service.h" + + +/** + * Configure overall network topology to have a particular shape. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ap topology-specific options + * @return handle to the operation, NULL if configuring the topology + * is not allowed at this time + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_topology_va (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer **peers, + enum GNUNET_TESTBED_TopologyOption topo, + va_list ap) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * Configure overall network topology to have a particular shape. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ... topology-specific options + * @return handle to the operation, NULL if configuring the topology + * is not allowed at this time + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_underlay_configure_topology (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer **peers, + enum GNUNET_TESTBED_TopologyOption topo, + ...) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * All peers must have been started before calling this function. + * This function then connects the given peers in the P2P overlay + * using the given topology. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param va topology-specific options + * @return handle to the operation, NULL if connecting these + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_configure_topology_va (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer *peers, + enum GNUNET_TESTBED_TopologyOption topo, + va_list va) +{ + GNUNET_break (0); + return NULL; +} + + +/** + * All peers must have been started before calling this function. + * This function then connects the given peers in the P2P overlay + * using the given topology. + * + * @param op_cls closure argument to give with the operation event + * @param num_peers number of peers in 'peers' + * @param peers array of 'num_peers' with the peers to configure + * @param topo desired underlay topology to use + * @param ... topology-specific options + * @return handle to the operation, NULL if connecting these + * peers is fundamentally not possible at this time (peers + * not running or underlay disallows) + */ +struct GNUNET_TESTBED_Operation * +GNUNET_TESTBED_overlay_configure_topology (void *op_cls, + unsigned int num_peers, + struct GNUNET_TESTBED_Peer *peers, + enum GNUNET_TESTBED_TopologyOption topo, + ...) +{ + GNUNET_break (0); + return NULL; +} + +/* end of new_testing_api_topology.c */ diff --git a/src/testing/new_testing.h b/src/testing/new_testing.h deleted file mode 100644 index 850c7f403..000000000 --- a/src/testing/new_testing.h +++ /dev/null @@ -1,535 +0,0 @@ -/* - This file is part of GNUnet - (C) 2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing.h - * @brief IPC messages between testing API and service ("controller") - * @author Christian Grothoff - */ - -#ifndef NEW_TESTING_H -#define NEW_TESTING_H - -#include "gnunet_util_lib.h" - - -/** - * Initial message from a client to a testing control service. - */ -struct GNUNET_TESTING_Message -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Host ID that the controller is either given - * (if this is the dominating client communicating - * via stdin) or assumed to have (for peer-connections - * between controllers). - */ - uint32_t host_id GNUNET_PACKED; - - /** - * Event mask that specifies which events this client - * is interested in. In NBO. - */ - uint64_t event_mask GNUNET_PACKED; - -}; - - -/** - * Notify the service about a host that we intend to use. - */ -struct GNUNET_TESTING_AddHostMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the host (in NBO). - */ - uint32_t host_id GNUNET_PACKED; - - /** - * SSH port to use, 0 for default (in NBO). - */ - uint16_t ssh_port GNUNET_PACKED; - - /** - * Number of bytes in the user name that follows; - * 0 to use no user name; otherwise 'strlen (username)', - * excluding 0-termination! - */ - uint16_t user_name_length GNUNET_PACKED; - - /* followed by 0-terminated user name */ - - /* followed by 0-terminated host name */ - -}; - - -/** - * Confirmation from the service that adding a host - * worked (or failed). - */ -struct GNUNET_TESTING_HostConfirmedMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the host (in NBO). - */ - uint32_t host_id GNUNET_PACKED; - - /* followed by the 0-terminated error message (on failure) - (typical errors include failure to login and - host-id already in use) */ - -}; - - -/** - * Message to testing service: configure service sharing - * at a host. - */ -struct GNUNET_TESTING_ConfigureSharedServiceMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Host that is being configured. - */ - uint32_t host_id GNUNET_PACKED; - - /** - * Number of peers that should share a service instance; - * 1 for no sharing, 0 to forcefully disable the service. - */ - uint32_t num_peers GNUNET_PACKED; - - /* followed by 0-terminated name of the service */ - -}; - - -/** - * Client notifies controller that it should delegate - * requests for a particular client to a particular - * sub-controller. - */ -struct GNUNET_TESTING_ControllerLinkMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * For which host should requests be delegated? NBO. - */ - uint32_t delegated_host_id GNUNET_PACKED; - - /** - * Which host is responsible for managing the delegation? NBO - */ - uint32_t slave_host_id GNUNET_PACKED; - - /** - * Is the receiving controller the master controller for - * the slave host (and thus responsible for starting it?). NBO. - */ - int32_t is_subordinate GNUNET_PACKED; - - /* followed by serialized slave configuration; - gzip'ed configuration file in INI format */ - -}; - - -/** - * Message sent from client to testing service to - * create (configure, but not start) a peer. - */ -struct GNUNET_TESTING_PeerCreateMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * On which host should the peer be started? - */ - uint32_t host_id GNUNET_PACKED; - - /** - * Unique ID for the peer. - */ - uint32_t peer_id GNUNET_PACKED; - - /* followed by serialized peer configuration; - gzip'ed configuration file in INI format */ - -}; - - -/** - * Message sent from client to testing service to - * reconfigure a (stopped) a peer. - */ -struct GNUNET_TESTING_PeerReconfigureMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the peer. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - - /* followed by serialized peer configuration; - gzip'ed configuration file in INI format */ - -}; - - -/** - * Message sent from client to testing service to - * start a peer. - */ -struct GNUNET_TESTING_PeerStartMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the peer. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - - -/** - * Message sent from client to testing service to - * stop a peer. - */ -struct GNUNET_TESTING_PeerStopMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the peer. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - - -/** - * Message sent from client to testing service to - * destroy a (stopped) peer. - */ -struct GNUNET_TESTING_PeerDestroyMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the peer. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - - -/** - * Message sent from client to testing service to - * (re)configure a "physical" link between two peers. - */ -struct GNUNET_TESTING_ConfigureUnderlayLinkMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * 'enum GNUNET_TESTING_ConnectOption' of the option to change - */ - int32_t connect_option GNUNET_PACKED; - - /** - * Unique ID for the first peer. - */ - uint32_t peer1 GNUNET_PACKED; - - /** - * Unique ID for the second peer. - */ - uint32_t peer2 GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - - /* followed by option-dependent variable-size values */ - -}; - - -/** - * Message sent from client to testing service to - * connect two peers. - */ -struct GNUNET_TESTING_OverlayConnectMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Unique ID for the first peer. - */ - uint32_t peer1 GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - - /** - * Unique ID for the second peer. - */ - uint32_t peer2 GNUNET_PACKED; - -}; - - -/** - * Event notification from a controller to a client. - */ -struct GNUNET_TESTING_PeerEventMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * 'enum GNUNET_TESTING_EventType' (in NBO); - * either GNUNET_TESTING_ET_PEER_START or GNUNET_TESTING_ET_PEER_STOP. - */ - int32_t event_type GNUNET_PACKED; - - /** - * Host where the peer is running. - */ - uint32_t host_id GNUNET_PACKED; - - /** - * Peer that was started or stopped. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - - -/** - * Event notification from a controller to a client. - */ -struct GNUNET_TESTING_ConnectionEventMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * 'enum GNUNET_TESTING_EventType' (in NBO); - * either GNUNET_TESTING_ET_PEER_CONNECT or GNUNET_TESTING_ET_PEER_DISCONNECT. - */ - int32_t event_type GNUNET_PACKED; - - /** - * First peer. - */ - uint32_t peer1 GNUNET_PACKED; - - /** - * Second peer. - */ - uint32_t peer2 GNUNET_PACKED; - - /** - * Operation ID that is used to identify this operation. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - - -/** - * Event notification from a controller to a client. - */ -struct GNUNET_TESTING_OperationFailureEventMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * 'enum GNUNET_TESTING_EventType' (in NBO); - * GNUNET_TESTING_ET_OPERATION_FINISHED. - */ - int32_t event_type GNUNET_PACKED; - - /** - * Operation ID of the operation that created this event. - */ - uint64_t operation_id GNUNET_PACKED; - - /* followed by 0-terminated error message */ - -}; - - -/** - * Event notification from a controller to a client. - */ -struct GNUNET_TESTING_PeerCreateSuccessEventMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * Peer identity of the peer that was created. - */ - uint32_t peer_id GNUNET_PACKED; - - /** - * Operation ID of the operation that created this event. - */ - uint64_t operation_id GNUNET_PACKED; - - /** - * Identity of the peer. - */ - struct GNUNET_PeerIdentity peer_id; - - /* followed by gzip-compressed configuration of the peer */ - -}; - - -/** - * Event notification from a controller to a client for - * a generic operational success where the operation does - * not return any data. - */ -struct GNUNET_TESTING_GenericOperationSuccessEventMessage -{ - - /** - * Type is - */ - struct GNUNET_MessageHeader header; - - /** - * 'enum GNUNET_TESTING_EventType' (in NBO); - * GNUNET_TESTING_ET_OPERATION_FINISHED. - */ - int32_t event_type GNUNET_PACKED; - - /** - * Operation ID of the operation that created this event. - */ - uint64_t operation_id GNUNET_PACKED; - -}; - -#endif diff --git a/src/testing/new_testing_api.c b/src/testing/new_testing_api.c deleted file mode 100644 index bc65476ee..000000000 --- a/src/testing/new_testing_api.c +++ /dev/null @@ -1,150 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api.c - * @brief API for accessing the GNUnet testing service. - * This library is supposed to make it easier to write - * testcases and script large-scale benchmarks. - * @author Christian Grothoff - */ -#include "platform.h" -#include "gnunet_testing_service.h" -#include "gnunet_core_service.h" -#include "gnunet_constants.h" -#include "gnunet_transport_service.h" -#include "gnunet_hello_lib.h" - - - - -/** - * Start a controller process using the given configuration at the - * given host. - * - * @param cfg configuration to use - * @param host host to run the controller on, NULL for 'localhost' - * @param event_mask bit mask with set of events to call 'cc' for; - * or-ed values of "1LL" shifted by the - * respective 'enum GNUNET_TESTING_EventType' - * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) | ...") - * @param cc controller callback to invoke on events - * @param cc_cls closure for cc - * @return handle to the controller - */ -struct GNUNET_TESTING_Controller * -GNUNET_TESTING_controller_start (const struct GNUNET_CONFIGURATION_Handle *cfg, - struct GNUNET_TESTING_Host *host, - uint64_t event_mask, - GNUNET_TESTING_ControllerCallback cc, - void *cc_cls) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Configure shared services at a controller. Using this function, - * you can specify that certain services (such as "resolver") - * should not be run for each peer but instead be shared - * across N peers on the specified host. This function - * must be called before any peers are created at the host. - * - * @param controller controller to configure - * @param service_name name of the service to share - * @param num_peers number of peers that should share one instance - * of the specified service (1 for no sharing is the default), - * use 0 to disable the service - */ -void -GNUNET_TESTING_controller_configure_sharing (struct GNUNET_TESTING_Controller *controller, - const char *service_name, - uint32_t num_peers) -{ - GNUNET_break (0); -} - - -/** - * Stop the given controller (also will terminate all peers and - * controllers dependent on this controller). This function - * blocks until the testbed has been fully terminated (!). - * - * @param controller handle to controller to stop - */ -void -GNUNET_TESTING_controller_stop (struct GNUNET_TESTING_Controller *controller) -{ - GNUNET_break (0); -} - - -/** - * Create a link from a 'master' controller to a slave controller. - * Whenever the master controller is asked to start a peer at the - * given 'delegated_host', it will delegate the request to the - * specified slave controller. Note that the slave controller runs at - * the 'slave_host', which may or may not be the same host as the - * 'delegated_host' (for hierarchical delegations). The configuration - * of the slave controller is given and to be used to either create - * the slave controller or to connect to an existing slave controller - * process. 'is_subordinate' specifies if the given slave controller - * should be started and managed by the master controller, or if the - * slave already has a master and this is just a secondary master that - * is also allowed to use the existing slave. - * - * @param master handle to the master controller who creates the association - * @param delegated_host requests to which host should be delegated - * @param slave_host which host is used to run the slave controller - * @param slave_cfg configuration to use for the slave controller - * @param is_subordinate GNUNET_YES if the slave should be started (and stopped) - * by the master controller; GNUNET_NO if we are just - * allowed to use the slave via TCP/IP - */ -void -GNUNET_TESTING_controller_link (struct GNUNET_TESTING_Controller *master, - struct GNUNET_TESTING_Host *delegated_host, - struct GNUNET_TESTING_Host *slave_host, - const struct GNUNET_CONFIGURATION_Handle *slave_cfg, - int is_subordinate) -{ - GNUNET_break (0); -} - - -/** - * Ask the testbed controller to write the current overlay topology to - * a file. Naturally, the file will only contain a snapshot as the - * topology may evolve all the time. - * - * @param controller overlay controller to inspect - * @param filename name of the file the topology should - * be written to. - */ -void -GNUNET_TESTING_overlay_write_topology_to_file (struct GNUNET_TESTING_Controller *controller, - const char *filename) -{ -} - - - -/* end of new_testing_api.c */ diff --git a/src/testing/new_testing_api_hosts.c b/src/testing/new_testing_api_hosts.c deleted file mode 100644 index 047dc3f07..000000000 --- a/src/testing/new_testing_api_hosts.c +++ /dev/null @@ -1,200 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_hosts.c - * @brief API for manipulating 'hosts' controlled by the GNUnet testing service; - * allows parsing hosts files, starting, stopping and communicating (via - * SSH/stdin/stdout) with the remote (or local) processes - * @author Christian Grothoff - */ -#include "platform.h" -#include "gnunet_testing_service.h" -#include "gnunet_core_service.h" -#include "gnunet_constants.h" -#include "gnunet_transport_service.h" -#include "gnunet_hello_lib.h" - - - -/** - * Opaque handle to a host running experiments managed by the testing framework. - * The master process must be able to SSH to this host without password (via - * ssh-agent). - */ -struct GNUNET_TESTING_Host -{ - - - const char *hostname; - - const char *username; - - /** - * Global ID we use to refer to a host on the network - */ - uint32_t unique_id; - - uint16_t port; -}; - - -/** - * Lookup a host by ID. - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_lookup_by_id_ (uint32_t id) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Create a host by ID; given this host handle, we could not - * run peers at the host, but we can talk about the host - * internally. - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create_by_id_ (uint32_t id) -{ - return NULL; -} - - -/** - * Obtain a host's unique global ID. - * - * @param host handle to the host, NULL means 'localhost' - * @return id global host ID assigned to the host (0 is - * 'localhost', but then obviously not globally unique) - */ -uint32_t -GNUNET_TESTING_host_get_id_ (struct GNUNET_TESTING_Host *host) -{ - GNUNET_break (0); - return 0; -} - - -/** - * Create a host to run peers and controllers on. - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @param hostname name of the host, use "NULL" for localhost - * @param username username to use for the login; may be NULL - * @param port port number to use for ssh; use 0 to let ssh decide - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create_with_id_ (uint32_t id, - const char *hostname, - const char *username, - uint16_t port) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Create a host to run peers and controllers on. - * - * @param hostname name of the host, use "NULL" for localhost - * @param username username to use for the login; may be NULL - * @param port port number to use for ssh; use 0 to let ssh decide - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create (const char *hostname, - const char *username, - uint16_t port) -{ - static uint32_t uid_generator; - - return GNUNET_TESTING_host_create_with_id_ (++uid_generator, - hostname, username, - port); -} - - -/** - * Load a set of hosts from a configuration file. - * - * @param filename file with the host specification - * @param hosts set to the hosts found in the file - * @return number of hosts returned in 'hosts', 0 on error - */ -unsigned int -GNUNET_TESTING_hosts_load_from_file (const char *filename, - struct GNUNET_TESTING_Host **hosts) -{ - GNUNET_break (0); - return 0; -} - - -/** - * Destroy a host handle. Must only be called once everything - * running on that host has been stopped. - * - * @param host handle to destroy - */ -void -GNUNET_TESTING_host_destroy (struct GNUNET_TESTING_Host *host) -{ - GNUNET_break (0); -} - - -/** - * Run a given helper process at the given host. Communication - * with the helper will be via GNUnet messages on stdin/stdout. - * Runs the process via 'ssh' at the specified host, or locally. - * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API. - * - * @param host host to use, use "NULL" for localhost - * @param binary_arg binary name and command-line arguments to give to the binary - * @param cb function to call for messages received from the binary - * @param cb_cls closure for cb - * @return handle to terminate the command, NULL on error - */ -struct GNUNET_HELPER_Handle * -GNUNET_TESTING_host_run_ (struct GNUNET_TESTING_Host *host, - char *const binary_argv[], - GNUNET_SERVER_MessageTokenizerCallback cb, void *cb_cls) -{ - /* FIXME: decide on the SSH command line, prepend it and - run GNUNET_HELPER_start with the modified binary_name and binary_argv! */ - GNUNET_break (0); - return NULL; -} - - -/* end of new_testing_api_hosts.c */ diff --git a/src/testing/new_testing_api_hosts.h b/src/testing/new_testing_api_hosts.h deleted file mode 100644 index 395cbe138..000000000 --- a/src/testing/new_testing_api_hosts.h +++ /dev/null @@ -1,105 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_hosts.h - * @brief internal API to access the 'hosts' subsystem - * @author Christian Grothoff - */ -#ifndef NEW_TESTING_API_HOSTS_H -#define NEW_TESTING_API_HOSTS_H - -#include "gnunet_testing_service.h" -#include "gnunet_helper_lib.h" - - -/** - * Lookup a host by ID. - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_lookup_by_id_ (uint32_t id); - - -/** - * Create a host by ID; given this host handle, we could not - * run peers at the host, but we can talk about the host - * internally. - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create_by_id_ (uint32_t id); - - -/** - * Create a host to run peers and controllers on. This function is used - * if a peer learns about a host via IPC between controllers (and thus - * some higher-level controller has already determined the unique IDs). - * - * @param id global host ID assigned to the host; 0 is - * reserved to always mean 'localhost' - * @param hostname name of the host, use "NULL" for localhost - * @param username username to use for the login; may be NULL - * @param port port number to use for ssh; use 0 to let ssh decide - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Host * -GNUNET_TESTING_host_create_with_id_ (uint32_t id, - const char *hostname, - const char *username, - uint16_t port); - - -/** - * Obtain a host's unique global ID. - * - * @param host handle to the host, NULL means 'localhost' - * @return id global host ID assigned to the host (0 is - * 'localhost', but then obviously not globally unique) - */ -uint32_t -GNUNET_TESTING_host_get_id_ (struct GNUNET_TESTING_Host *host); - - -/** - * Run a given helper process at the given host. Communication - * with the helper will be via GNUnet messages on stdin/stdout. - * Runs the process via 'ssh' at the specified host, or locally. - * Essentially an SSH-wrapper around the 'gnunet_helper_lib.h' API. - * - * @param host host to use, use "NULL" for localhost - * @param binary_arg binary name and command-line arguments to give to the binary - * @param cb function to call for messages received from the binary - * @param cb_cls closure for cb - * @return handle to terminate the command, NULL on error - */ -struct GNUNET_HELPER_Handle * -GNUNET_TESTING_host_run_ (struct GNUNET_TESTING_Host *host, - char *const binary_argv[], - GNUNET_SERVER_MessageTokenizerCallback cb, void *cb_cls); - -#endif -/* end of new_testing_api_hosts.h */ diff --git a/src/testing/new_testing_api_operations.c b/src/testing/new_testing_api_operations.c deleted file mode 100644 index 533715b50..000000000 --- a/src/testing/new_testing_api_operations.c +++ /dev/null @@ -1,74 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_operations.c - * @brief functions to manage operation queues - * @author Christian Grothoff - */ -#include "platform.h" -#include "new_testing_api_operations.h" - - -/** - * Opaque handle to an abstract operation to be executed by the testing framework. - */ -struct GNUNET_TESTING_Operation -{ - // FIXME! -}; - - - -/** - * Cancel a pending operation. Releases all resources - * of the operation and will ensure that no event - * is generated for the operation. Does NOT guarantee - * that the operation will be fully undone (or that - * nothing ever happened). - * - * @param operation operation to cancel - */ -void -GNUNET_TESTING_operation_cancel (struct GNUNET_TESTING_Operation *operation) -{ - GNUNET_break (0); - -} - - -/** - * Signal that the information from an operation has been fully - * processed. This function MUST be called for each event - * of type 'operation_finished' to fully remove the operation - * from the operation queue. After calling this function, the - * 'op_result' becomes invalid (!). - * - * @param operation operation to signal completion for - */ -void -GNUNET_TESTING_operation_done (struct GNUNET_TESTING_Operation *operation) -{ - GNUNET_break (0); -} - - - -/* end of new_testing_api_operations.c */ diff --git a/src/testing/new_testing_api_operations.h b/src/testing/new_testing_api_operations.h deleted file mode 100644 index 3636fa421..000000000 --- a/src/testing/new_testing_api_operations.h +++ /dev/null @@ -1,34 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_operations.h - * @brief internal API to access the 'operations' subsystem - * @author Christian Grothoff - */ -#ifndef NEW_TESTING_API_OPERATIONS_H -#define NEW_TESTING_API_OPERATIONS_H - -#include "gnunet_testing_service.h" -#include "gnunet_helper_lib.h" - - -#endif -/* end of new_testing_api_operations.h */ diff --git a/src/testing/new_testing_api_peers.c b/src/testing/new_testing_api_peers.c deleted file mode 100644 index 305b86b17..000000000 --- a/src/testing/new_testing_api_peers.c +++ /dev/null @@ -1,297 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_peers.c - * @brief management of the knowledge about peers in this library - * (we know the peer ID, its host, pending operations, etc.) - * @author Christian Grothoff - */ -#include "platform.h" -#include "new_testing_api_peers.h" - - -/** - * Details about a peer; kept in a separate struct to avoid bloating - * memory consumption everywhere... - */ -struct PeerDetails -{ - /** - * Configuration of the peer; NULL if we are not sure what the peer's correct - * configuration actually is; non-NULL if this peer is controlled by this - * process. - */ - struct GNUNET_CONFIGURATION_Handle *cfg; - - /** - * If this process has started this peer's ARM process, this is the handle - * to the 'gnunet-service-arm' process of the peer. - */ - struct GNUNET_OS_Process *arm; - - // ... - -}; - - -/** - * A peer controlled by the testing framework. A peer runs - * at a particular host. - */ -struct GNUNET_TESTING_Peer -{ - /** - * Our controller context (not necessarily the controller - * that is responsible for starting/running the peer!). - */ - struct GNUNET_TESTING_Controller *controller; - - /** - * Which host does this peer run on? - */ - struct GNUENT_TESTING_Host *host; - - /** - * Globally unique ID of the peer. - */ - uint32_t unique_id; - - /** - * Internals of the peer for the controlling process; NULL if - * this process is not controlling this peer. - */ - struct PeerDetails *details; - -}; - - -/** - * Lookup a peer by ID. - * - * @param id global peer ID assigned to the peer - * @return handle to the host, NULL on error - */ -struct GNUNET_TESTING_Peer * -GNUNET_TESTING_peer_lookup_by_id_ (uint32_t id) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Create the given peer at the specified host using the given - * controller. If the given controller is not running on the target - * host, it should find or create a controller at the target host and - * delegate creating the peer. Explicit delegation paths can be setup - * using 'GNUNET_TESTING_controller_link'. If no explicit delegation - * path exists, a direct link with a subordinate controller is setup - * for the first delegated peer to a particular host; the subordinate - * controller is then destroyed once the last peer that was delegated - * to the remote host is stopped. This function is used in particular - * if some other controller has already assigned a unique ID to the - * peer. - * - * Creating the peer only creates the handle to manipulate and further - * configure the peer; use "GNUNET_TESTING_peer_start" and - * "GNUNET_TESTING_peer_stop" to actually start/stop the peer's - * processes. - * - * Note that the given configuration will be adjusted by the - * controller to avoid port/path conflicts with other peers. - * The "final" configuration can be obtained using - * 'GNUNET_TESTING_peer_get_information'. - * - * @param unique_id unique ID for this peer - * @param controller controller process to use - * @param host host to run the peer on - * @param cfg configuration to use for the peer - * @return handle to the peer (actual startup will happen asynchronously) - */ -struct GNUNET_TESTING_Peer * -GNUNET_TESTING_peer_create_with_id_ (uint32_t unique_id, - struct GNUNET_TESTING_Controller *controller, - struct GNUNET_TESTING_Host *host, - const struct GNUNET_CONFIGURATION_Handle *cfg) -{ - // FIXME: create locally or delegate... - GNUNET_break (0); - return NULL; -} - - -/** - * Create the given peer at the specified host using the given - * controller. If the given controller is not running on the target - * host, it should find or create a controller at the target host and - * delegate creating the peer. Explicit delegation paths can be setup - * using 'GNUNET_TESTING_controller_link'. If no explicit delegation - * path exists, a direct link with a subordinate controller is setup - * for the first delegated peer to a particular host; the subordinate - * controller is then destroyed once the last peer that was delegated - * to the remote host is stopped. - * - * Creating the peer only creates the handle to manipulate and further - * configure the peer; use "GNUNET_TESTING_peer_start" and - * "GNUNET_TESTING_peer_stop" to actually start/stop the peer's - * processes. - * - * Note that the given configuration will be adjusted by the - * controller to avoid port/path conflicts with other peers. - * The "final" configuration can be obtained using - * 'GNUNET_TESTING_peer_get_information'. - * - * @param controller controller process to use - * @param host host to run the peer on - * @param cfg configuration to use for the peer - * @return handle to the peer (actual startup will happen asynchronously) - */ -struct GNUNET_TESTING_Peer * -GNUNET_TESTING_peer_create (struct GNUNET_TESTING_Controller *controller, - struct GNUNET_TESTING_Host *host, - const struct GNUNET_CONFIGURATION_Handle *cfg) -{ - static uint32_t id_gen; - - return GNUNET_TESTING_peer_create_with_id_ (++id_gen, - controller, - host, - cfg); -} - - -/** - * Start the given peer. - * - * @param peer peer to start - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_start (struct GNUNET_TESTING_Peer *peer) -{ - // FIXME: start locally or delegate... - GNUNET_break (0); - return NULL; -} - - -/** - * Stop the given peer. The handle remains valid (use - * "GNUNET_TESTING_peer_destroy" to fully clean up the - * state of the peer). - * - * @param peer peer to stop - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_stop (struct GNUNET_TESTING_Peer *peer) -{ - // FIXME: stop locally or delegate... - GNUNET_break (0); - return NULL; -} - - -/** - * Request information about a peer. - * - * @param peer peer to request information about - * @param pit desired information - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_get_information (struct GNUNET_TESTING_Peer *peer, - enum GNUNET_TESTING_PeerInformationType pit) -{ - // FIXME: handle locally or delegate... - GNUNET_break (0); - return NULL; -} - - -/** - * Change peer configuration. Must only be called while the - * peer is stopped. Ports and paths cannot be changed this - * way. - * - * @param peer peer to change configuration for - * @param cfg new configuration (differences to existing - * configuration only) - * @return handle to the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_peer_update_configuration (struct GNUNET_TESTING_Peer *peer, - const struct GNUNET_CONFIGURATION_Handle *cfg) -{ - // FIXME: handle locally or delegate... - GNUNET_break (0); - return NULL; -} - - -/** - * Manipulate the P2P underlay topology by configuring a link - * between two peers. - * - * @param op_cls closure argument to give with the operation event - * @param p1 first peer - * @param p2 second peer - * @param co option to change - * @param ... option-specific values - * @return handle to the operation, NULL if configuring the link at this - * time is not allowed - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_link (void *op_cls, - struct GNUNET_TESTING_Peer *p1, - struct GNUNET_TESTING_Peer *p2, - enum GNUNET_TESTING_ConnectOption co, ...) -{ - GNUNET_break (0); - return NULL; -} - - - -/** - * Both peers must have been started before calling this function. - * This function then obtains a HELLO from 'p1', gives it to 'p2' - * and asks 'p2' to connect to 'p1'. - * - * @param op_cls closure argument to give with the operation event - * @param p1 first peer - * @param p2 second peer - * @return handle to the operation, NULL if connecting these two - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_connect (void *op_cls, - struct GNUNET_TESTING_Peer *p1, - struct GNUNET_TESTING_Peer *p2) -{ - GNUNET_break (0); - return NULL; -} - - - -/* end of new_testing_api_peers.c */ diff --git a/src/testing/new_testing_api_peers.h b/src/testing/new_testing_api_peers.h deleted file mode 100644 index 97c9e4fd9..000000000 --- a/src/testing/new_testing_api_peers.h +++ /dev/null @@ -1,71 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_peers.h - * @brief internal API to access the 'peers' subsystem - * @author Christian Grothoff - */ -#ifndef NEW_TESTING_API_PEERS_H -#define NEW_TESTING_API_PEERS_H - -#include "gnunet_testing_service.h" -#include "gnunet_helper_lib.h" - - -/** - * Create the given peer at the specified host using the given - * controller. If the given controller is not running on the target - * host, it should find or create a controller at the target host and - * delegate creating the peer. Explicit delegation paths can be setup - * using 'GNUNET_TESTING_controller_link'. If no explicit delegation - * path exists, a direct link with a subordinate controller is setup - * for the first delegated peer to a particular host; the subordinate - * controller is then destroyed once the last peer that was delegated - * to the remote host is stopped. This function is used in particular - * if some other controller has already assigned a unique ID to the - * peer. - * - * Creating the peer only creates the handle to manipulate and further - * configure the peer; use "GNUNET_TESTING_peer_start" and - * "GNUNET_TESTING_peer_stop" to actually start/stop the peer's - * processes. - * - * Note that the given configuration will be adjusted by the - * controller to avoid port/path conflicts with other peers. - * The "final" configuration can be obtained using - * 'GNUNET_TESTING_peer_get_information'. - * - * @param unique_id unique ID for this peer - * @param controller controller process to use - * @param host host to run the peer on - * @param cfg configuration to use for the peer - * @return handle to the peer (actual startup will happen asynchronously) - */ -struct GNUNET_TESTING_Peer * -GNUNET_TESTING_peer_create_with_id_ (uint32_t unique_id, - struct GNUNET_TESTING_Controller *controller, - struct GNUNET_TESTING_Host *host, - const struct GNUNET_CONFIGURATION_Handle *cfg); - - - -#endif -/* end of new_testing_api_peers.h */ diff --git a/src/testing/new_testing_api_services.c b/src/testing/new_testing_api_services.c deleted file mode 100644 index 67bc497f8..000000000 --- a/src/testing/new_testing_api_services.c +++ /dev/null @@ -1,61 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_services.c - * @brief convenience functions for accessing services - * @author Christian Grothoff - */ -#include "platform.h" -#include "new_testing_api_peers.h" - - -/** - * Connect to a service offered by the given peer. Will ensure that - * the request is queued to not overwhelm our ability to create and - * maintain connections with other systems. The actual service - * handle is then returned via the 'op_result' member in the event - * callback. The 'ca' callback is used to create the connection - * when the time is right; the 'da' callback will be used to - * destroy the connection (upon 'GNUNET_TESTING_operation_done'). - * 'GNUNET_TESTING_operation_cancel' can be used to abort this - * operation until the event callback has been called. - * - * @param op_cls closure to pass in operation event - * @param peer peer that runs the service - * @param service_name name of the service to connect to - * @param ca helper function to establish the connection - * @param da helper function to close the connection - * @param cada_cls closure for ca and da - * @return handle for the operation - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_service_connect (void *op_cls, - struct GNUNET_TESTING_Peer *peer, - const char *service_name, - GNUNET_TESTING_ConnectAdapter ca, - GNUNET_TESTING_DisconnectAdapter da, - void *cada_cls) -{ - GNUNET_break (0); - return NULL; -} - -/* end of new_testing_api_services.c */ diff --git a/src/testing/new_testing_api_test.c b/src/testing/new_testing_api_test.c deleted file mode 100644 index 7fa51af40..000000000 --- a/src/testing/new_testing_api_test.c +++ /dev/null @@ -1,67 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_test.c - * @brief high-level test function - * @author Christian Grothoff - */ -#include "platform.h" -#include "gnunet_testing_service.h" - - - - -/** - * Convenience method for running a "simple" test on the local system - * with a single call from 'main'. Underlay and overlay topology are - * configured using the "UNDERLAY" and "OVERLAY" options in the - * "[testbed]" section of the configuration (with possible options - * given in "UNDERLAY_XXX" and/or "OVERLAY_XXX"). - * - * The test is to be terminated using a call to - * "GNUNET_SCHEDULER_shutdown". If starting the test fails, - * the program is stopped without 'master' ever being run. - * - * NOTE: this function should be called from 'main', NOT from - * within a GNUNET_SCHEDULER-loop. This function will initialze - * the scheduler loop, the testbed and then pass control to - * 'master'. - * - * @param testname name of the testcase (to configure logging, etc.) - * @param cfg_filename configuration filename to use - * (for testbed, controller and peers) - * @param num_peers number of peers to start - * @param test_master task to run once the test is ready - * @param test_master_cls closure for 'task'. - */ -void -GNUNET_TESTING_test_run (const char *testname, - const char *cfg_filename, - unsigned int num_peers, - GNUNET_TESTING_TestMaster test_master, - void *test_master_cls) -{ - GNUNET_break (0); -} - - - -/* end of new_testing_api_test.c */ diff --git a/src/testing/new_testing_api_testbed.c b/src/testing/new_testing_api_testbed.c deleted file mode 100644 index e027043b9..000000000 --- a/src/testing/new_testing_api_testbed.c +++ /dev/null @@ -1,153 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_testbed.c - * @brief high-level testbed management - * @author Christian Grothoff - */ -#include "platform.h" -#include "gnunet_testing_service.h" - - -/** - * Opaque handle to an abstract operation to be executed by the testing framework. - */ -struct GNUNET_TESTING_Testbed -{ - // FIXME! -}; - - -/** - * Configure and run a testbed using the given - * master controller on 'num_hosts' starting - * 'num_peers' using the given peer configuration. - * - * @param controller master controller for the testbed - * (must not be destroyed until after the - * testbed is destroyed). - * @param num_hosts number of hosts in 'hosts', 0 to only - * use 'localhost' - * @param hosts list of hosts to use for the testbed - * @param num_peers number of peers to start - * @param peer_cfg peer configuration template to use - * @param underlay_topology underlay topology to create - * @param va topology-specific options - * @return handle to the testbed - */ -struct GNUNET_TESTING_Testbed * -GNUNET_TESTING_testbed_create_va (struct GNUNET_TESTING_Controller *controller, - unsigned int num_hosts, - struct GNUNET_TESTING_Host **hosts, - unsigned int num_peers, - const struct GNUNET_CONFIGURATION_Handle *peer_cfg, - enum GNUNET_TESTING_TopologyOption underlay_topology, - va_list va) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Configure and run a testbed using the given - * master controller on 'num_hosts' starting - * 'num_peers' using the given peer configuration. - * - * @param controller master controller for the testbed - * (must not be destroyed until after the - * testbed is destroyed). - * @param num_hosts number of hosts in 'hosts', 0 to only - * use 'localhost' - * @param hosts list of hosts to use for the testbed - * @param num_peers number of peers to start - * @param peer_cfg peer configuration template to use - * @param underlay_topology underlay topology to create - * @param ... topology-specific options - */ -struct GNUNET_TESTING_Testbed * -GNUNET_TESTING_testbed_create (struct GNUNET_TESTING_Controller *controller, - unsigned int num_hosts, - struct GNUNET_TESTING_Host **hosts, - unsigned int num_peers, - const struct GNUNET_CONFIGURATION_Handle *peer_cfg, - enum GNUNET_TESTING_TopologyOption underlay_topology, - ...) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Destroy a testbed. Stops all running peers and then - * destroys all peers. Does NOT destroy the master controller. - * - * @param testbed testbed to destroy - */ -void -GNUNET_TESTING_testbed_destroy (struct GNUNET_TESTING_Testbed *testbed) -{ - GNUNET_break (0); -} - - - -/** - * Convenience method for running a testbed with - * a single call. Underlay and overlay topology - * are configured using the "UNDERLAY" and "OVERLAY" - * options in the "[testbed]" section of the configuration\ - * (with possible options given in "UNDERLAY_XXX" and/or - * "OVERLAY_XXX"). - * - * The testbed is to be terminated using a call to - * "GNUNET_SCHEDULER_shutdown". - * - * @param host_filename name of the file with the 'hosts', NULL - * to run everything on 'localhost' - * @param cfg configuration to use (for testbed, controller and peers) - * @param num_peers number of peers to start; FIXME: maybe put that ALSO into cfg? - * @param event_mask bit mask with set of events to call 'cc' for; - * or-ed values of "1LL" shifted by the - * respective 'enum GNUNET_TESTING_EventType' - * (i.e. "(1LL << GNUNET_TESTING_ET_CONNECT) || ...") - * @param cc controller callback to invoke on events - * @param cc_cls closure for cc - * @param master task to run once the testbed is ready - * @param master_cls closure for 'task'. - */ -void -GNUNET_TESTING_testbed_run (const char *host_filename, - const struct GNUNET_CONFIGURATION_Handle *cfg, - unsigned int num_peers, - uint64_t event_mask, - GNUNET_TESTING_ControllerCallback cc, - void *cc_cls, - GNUNET_SCHEDULER_Task master, - void *master_cls) -{ - GNUNET_break (0); -} - - - -/* end of new_testing_api_testbed.c */ diff --git a/src/testing/new_testing_api_topology.c b/src/testing/new_testing_api_topology.c deleted file mode 100644 index 877e6733e..000000000 --- a/src/testing/new_testing_api_topology.c +++ /dev/null @@ -1,127 +0,0 @@ -/* - This file is part of GNUnet - (C) 2008--2012 Christian Grothoff (and other contributing authors) - - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. - - GNUnet is distributed in the hope that it will be useful, but - WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. - - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. - */ - -/** - * @file testing/new_testing_api_topology.c - * @brief topology-generation functions - * @author Christian Grothoff - */ -#include "platform.h" -#include "gnunet_testing_service.h" - - -/** - * Configure overall network topology to have a particular shape. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ap topology-specific options - * @return handle to the operation, NULL if configuring the topology - * is not allowed at this time - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_topology_va (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer **peers, - enum GNUNET_TESTING_TopologyOption topo, - va_list ap) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * Configure overall network topology to have a particular shape. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ... topology-specific options - * @return handle to the operation, NULL if configuring the topology - * is not allowed at this time - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_underlay_configure_topology (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer **peers, - enum GNUNET_TESTING_TopologyOption topo, - ...) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * All peers must have been started before calling this function. - * This function then connects the given peers in the P2P overlay - * using the given topology. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param va topology-specific options - * @return handle to the operation, NULL if connecting these - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_configure_topology_va (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer *peers, - enum GNUNET_TESTING_TopologyOption topo, - va_list va) -{ - GNUNET_break (0); - return NULL; -} - - -/** - * All peers must have been started before calling this function. - * This function then connects the given peers in the P2P overlay - * using the given topology. - * - * @param op_cls closure argument to give with the operation event - * @param num_peers number of peers in 'peers' - * @param peers array of 'num_peers' with the peers to configure - * @param topo desired underlay topology to use - * @param ... topology-specific options - * @return handle to the operation, NULL if connecting these - * peers is fundamentally not possible at this time (peers - * not running or underlay disallows) - */ -struct GNUNET_TESTING_Operation * -GNUNET_TESTING_overlay_configure_topology (void *op_cls, - unsigned int num_peers, - struct GNUNET_TESTING_Peer *peers, - enum GNUNET_TESTING_TopologyOption topo, - ...) -{ - GNUNET_break (0); - return NULL; -} - -/* end of new_testing_api_topology.c */