aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_testing_netjail_lib.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_testing_netjail_lib.h')
-rw-r--r--src/include/gnunet_testing_netjail_lib.h463
1 files changed, 463 insertions, 0 deletions
diff --git a/src/include/gnunet_testing_netjail_lib.h b/src/include/gnunet_testing_netjail_lib.h
new file mode 100644
index 000000000..3a5e9f749
--- /dev/null
+++ b/src/include/gnunet_testing_netjail_lib.h
@@ -0,0 +1,463 @@
1/*
2 This file is part of GNUnet
3 Copyright (C) 2021 GNUnet e.V.
4
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your option) any later version.
9
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Affero General Public License for more details.
14
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
17
18 SPDX-License-Identifier: AGPL3.0-or-later
19 */
20
21/**
22 * @brief API for writing an interpreter to test GNUnet components
23 * @author Christian Grothoff <christian@grothoff.org>
24 * @author Marcello Stanisci
25 * @author t3sserakt
26 */
27#ifndef GNUNET_TESTING_NG_LIB_H
28#define GNUNET_TESTING_NG_LIB_H
29
30#include "gnunet_util_lib.h"
31#include "gnunet_testing_plugin.h"
32#include "gnunet_testing_ng_lib.h"
33
34
35/**
36 * Router of a netjail subnet.
37 */
38struct GNUNET_TESTING_NetjailRouter
39{
40 /**
41 * Will tcp be forwarded?
42 */
43 unsigned int tcp_port;
44
45 /**
46 * Will udp be forwarded?
47 */
48 unsigned int udp_port;
49};
50
51
52/**
53 * Enum for the different types of nodes.
54 */
55enum GNUNET_TESTING_NODE_TYPE
56{
57 /**
58 * Node in a subnet.
59 */
60 GNUNET_TESTING_SUBNET_NODE,
61
62 /**
63 * Global known node.
64 */
65 GNUNET_TESTING_GLOBAL_NODE
66};
67
68/**
69 * Protocol address prefix für a connection between nodes.
70 */
71struct GNUNET_TESTING_AddressPrefix
72{
73 /**
74 * Pointer to the previous prefix in the DLL.
75 */
76 struct GNUNET_TESTING_AddressPrefix *prev;
77
78 /**
79 * Pointer to the next prefix in the DLL.
80 */
81 struct GNUNET_TESTING_AddressPrefix *next;
82
83 /**
84 * The address prefix.
85 */
86 char *address_prefix;
87};
88
89
90/**
91 * Node in a netjail topology.
92 */
93struct GNUNET_TESTING_NetjailNode;
94
95/**
96 * Connection to another node.
97 */
98struct GNUNET_TESTING_NodeConnection
99{
100 /**
101 * Pointer to the previous connection in the DLL.
102 */
103 struct GNUNET_TESTING_NodeConnection *prev;
104
105 /**
106 * Pointer to the next connection in the DLL.
107 */
108 struct GNUNET_TESTING_NodeConnection *next;
109
110 /**
111 * The number of the subnet of the node this connection points to. This is 0,
112 * if the node is a global known node.
113 */
114 unsigned int namespace_n;
115
116 /**
117 * The number of the node this connection points to.
118 */
119 unsigned int node_n;
120
121 /**
122 * The type of the node this connection points to.
123 */
124 enum GNUNET_TESTING_NODE_TYPE node_type;
125
126 /**
127 * The node which establish the connection
128 */
129 struct GNUNET_TESTING_NetjailNode *node;
130
131 /**
132 * Head of the DLL with the address prefixes for the protocolls this node is reachable.
133 */
134 struct GNUNET_TESTING_AddressPrefix *address_prefixes_head;
135
136 /**
137 * Tail of the DLL with the address prefixes for the protocolls this node is reachable.
138 */
139 struct GNUNET_TESTING_AddressPrefix *address_prefixes_tail;
140};
141
142/**
143 * Node in the netjail topology.
144 */
145struct GNUNET_TESTING_NetjailNode
146{
147 /**
148 * Plugin for the test case to be run on this node.
149 */
150 char *plugin;
151
152 /**
153 * Flag indicating if this node is a global known node.
154 */
155 unsigned int is_global;
156
157 /**
158 * The number of the subnet this node is running in.
159 */
160 unsigned int namespace_n;
161
162 /**
163 * The number of this node in the subnet.
164 */
165 unsigned int node_n;
166
167 /**
168 * Head of the DLL with the connections which shall be established to other nodes.
169 */
170 struct GNUNET_TESTING_NodeConnection *node_connections_head;
171
172 /**
173 * Tail of the DLL with the connections which shall be established to other nodes.
174 */
175 struct GNUNET_TESTING_NodeConnection *node_connections_tail;
176};
177
178
179/**
180 * Subnet in a topology.
181 */
182struct GNUNET_TESTING_NetjailNamespace
183{
184 /**
185 * The number of the subnet.
186 */
187 unsigned int namespace_n;
188
189 /**
190 * Router of the subnet.
191 */
192 struct GNUNET_TESTING_NetjailRouter *router;
193
194 /**
195 * Hash map containing the nodes in this subnet.
196 */
197 struct GNUNET_CONTAINER_MultiShortmap *nodes;
198};
199
200/**
201 * Toplogy of our netjail setup.
202 */
203struct GNUNET_TESTING_NetjailTopology
204{
205
206 /**
207 * Default plugin for the test case to be run on nodes.
208 */
209 char *plugin;
210
211 /**
212 * Number of subnets.
213 */
214 unsigned int namespaces_n;
215
216 /**
217 * Number of nodes per subnet.
218 */
219 unsigned int nodes_m;
220
221 /**
222 * Number of global known nodes.
223 */
224 unsigned int nodes_x;
225
226 /**
227 * Hash map containing the subnets (for natted nodes) of the topology.
228 */
229 struct GNUNET_CONTAINER_MultiShortmap *map_namespaces;
230
231 /**
232 * Hash map containing the global known nodes which are not natted.
233 */
234 struct GNUNET_CONTAINER_MultiShortmap *map_globals;
235};
236
237/**
238 * Getting the topology from file.
239 *
240 * @param filename The name of the topology file.
241 * @return The GNUNET_TESTING_NetjailTopology
242 */
243struct GNUNET_TESTING_NetjailTopology *
244GNUNET_TESTING_get_topo_from_file (const char *filename);
245
246
247/**
248 * Parse the topology data.
249 *
250 * @param data The topology data.
251 * @return The GNUNET_TESTING_NetjailTopology
252 */
253struct GNUNET_TESTING_NetjailTopology *
254GNUNET_TESTING_get_topo_from_string (char *data);
255
256
257/**
258 * Get the connections to other nodes for a specific node.
259 *
260 * @param num The specific node we want the connections for.
261 * @param topology The topology we get the connections from.
262 * @return The connections of the node.
263 */
264struct GNUNET_TESTING_NodeConnection *
265GNUNET_TESTING_get_connections (unsigned int num, struct
266 GNUNET_TESTING_NetjailTopology *topology);
267
268
269/**
270 * Get the address for a specific communicator from a connection.
271 *
272 * @param connection The connection we like to have the address from.
273 * @param prefix The communicator protocol prefix.
274 * @return The address of the communicator.
275 */
276char *
277GNUNET_TESTING_get_address (struct GNUNET_TESTING_NodeConnection *connection,
278 char *prefix);
279
280
281/**
282 * Deallocate memory of the struct GNUNET_TESTING_NetjailTopology.
283 *
284 * @param topology The GNUNET_TESTING_NetjailTopology to be deallocated.
285 */
286void
287GNUNET_TESTING_free_topology (struct GNUNET_TESTING_NetjailTopology *topology);
288
289
290/**
291 * Calculate the unique id identifying a node from a given connction.
292 *
293 * @param node_connection The connection we calculate the id from.
294 * @param topology The topology we get all needed information from.
295 * @return The unique id of the node from the connection.
296 */
297unsigned int
298GNUNET_TESTING_calculate_num (struct
299 GNUNET_TESTING_NodeConnection *node_connection,
300 struct GNUNET_TESTING_NetjailTopology *topology);
301
302
303/**
304 * Struct to hold information for callbacks.
305 *
306 */
307struct LocalPreparedState
308{
309 /**
310 * Context for our asynchronous completion.
311 */
312 struct GNUNET_TESTING_AsyncContext *ac;
313
314 /**
315 * Callback to write messages to the master loop.
316 *
317 */
318 TESTING_CMD_HELPER_write_cb write_message;
319};
320
321
322/**
323 * Create command.
324 *
325 * @param label name for command.
326 * @param topology_config Configuration file for the test topology.
327 * @return command.
328 */
329struct GNUNET_TESTING_Command
330GNUNET_TESTING_cmd_netjail_start (const char *label,
331 char *topology_config,
332 unsigned int *read_file);
333
334
335/**
336 * Create command.
337 *
338 * @param label Name for the command.
339 * @param topology The complete topology information.
340 * @return command.
341 */
342struct GNUNET_TESTING_Command
343GNUNET_TESTING_cmd_netjail_start_testing_system (
344 const char *label,
345 struct GNUNET_TESTING_NetjailTopology *topology);
346
347
348/**
349 * Create command.
350 *
351 * @param label name for command.
352 * @param topology_config Configuration file for the test topology.
353 * @return command.
354 */
355struct GNUNET_TESTING_Command
356GNUNET_TESTING_cmd_netjail_stop (const char *label,
357 char *topology_config,
358 unsigned int *read_file);
359
360
361/**
362 * Create command.
363 *
364 * @param label name for command.
365 * @param helper_start_label label of the cmd to start the test system.
366 * @param topology The complete topology information.
367 * @return command.
368 */
369struct GNUNET_TESTING_Command
370GNUNET_TESTING_cmd_stop_testing_system (
371 const char *label,
372 const char *helper_start_label,
373 struct GNUNET_TESTING_NetjailTopology *topology);
374
375
376/**
377 * Create a GNUNET_CMDS_LOCAL_FINISHED message.
378 *
379 * @param rv The result of the local test as GNUNET_GenericReturnValue.
380 * @return The GNUNET_CMDS_LOCAL_FINISHED message.
381*/
382struct GNUNET_MessageHeader *
383GNUNET_TESTING_send_local_test_finished_msg (enum GNUNET_GenericReturnValue rv);
384
385
386/**
387 * Function to get the trait with the async context.
388 *
389 * @param[out] ac GNUNET_TESTING_AsyncContext.
390 * @return #GNUNET_OK if no error occurred, #GNUNET_SYSERR otherwise.
391 */
392int
393GNUNET_TESTING_get_trait_async_context (
394 const struct GNUNET_TESTING_Command *cmd,
395 struct GNUNET_TESTING_AsyncContext **ac);
396
397
398/**
399 * Offer handles to testing cmd helper from trait
400 *
401 * @param cmd command to extract the message from.
402 * @param pt pointer to message.
403 * @return #GNUNET_OK on success.
404 */
405enum GNUNET_GenericReturnValue
406GNUNET_TESTING_get_trait_helper_handles (
407 const struct GNUNET_TESTING_Command *cmd,
408 struct GNUNET_HELPER_Handle ***helper);
409
410
411struct GNUNET_TESTING_Command
412GNUNET_TESTING_cmd_block_until_all_peers_started (
413 const char *label,
414 unsigned int *all_peers_started);
415
416
417struct GNUNET_TESTING_Command
418GNUNET_TESTING_cmd_block_until_external_trigger (
419 const char *label);
420
421struct GNUNET_TESTING_Command
422GNUNET_TESTING_cmd_send_peer_ready (const char *label,
423 TESTING_CMD_HELPER_write_cb write_message);
424
425
426/**
427 * Create command.
428 *
429 * @param label name for command.
430 * @param write_message Callback to write messages to the master loop.
431 * @return command.
432 */
433struct GNUNET_TESTING_Command
434GNUNET_TESTING_cmd_local_test_finished (
435 const char *label,
436 TESTING_CMD_HELPER_write_cb write_message);
437
438/**
439 * Create command.
440 *
441 * @param label name for command.
442 * @param write_message Callback to write messages to the master loop.
443 * @param all_local_tests_prepared Flag which will be set from outside.
444 * @return command.
445 */
446struct GNUNET_TESTING_Command
447GNUNET_TESTING_cmd_local_test_prepared (const char *label,
448 TESTING_CMD_HELPER_write_cb
449 write_message);
450
451/**
452 * Function to get the trait with the struct LocalPreparedState.
453 *
454 * @param[out] lfs struct LocalPreparedState.
455 * @return #GNUNET_OK if no error occurred, #GNUNET_SYSERR otherwise.
456 *
457 */
458enum GNUNET_GenericReturnValue
459GNUNET_TESTING_get_trait_local_prepared_state (
460 const struct GNUNET_TESTING_Command *cmd,
461 struct LocalPreparedState **lfs);
462
463#endif