-remove trailing whitespace
[oweals/gnunet.git] / src / testbed / testbed.h
1 /*
2       This file is part of GNUnet
3       (C) 2008--2013 Christian Grothoff (and other contributing authors)
4
5       GNUnet is free software; you can redistribute it and/or modify
6       it under the terms of the GNU General Public License as published
7       by the Free Software Foundation; either version 3, or (at your
8       option) any later version.
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       General Public License for more details.
14
15       You should have received a copy of the GNU General Public License
16       along with GNUnet; see the file COPYING.  If not, write to the
17       Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18       Boston, MA 02111-1307, USA.
19  */
20
21 /**
22  * @file testbed/testbed.h
23  * @brief IPC messages between testing API and service ("controller")
24  * @author Christian Grothoff
25  */
26
27 #ifndef TESTBED_H
28 #define TESTBED_H
29
30 #include "gnunet_util_lib.h"
31
32 GNUNET_NETWORK_STRUCT_BEGIN
33 /**
34  * Initial message from a client to a testing control service.
35  */
36 struct GNUNET_TESTBED_InitMessage
37 {
38
39   /**
40    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_INIT
41    */
42   struct GNUNET_MessageHeader header;
43
44   /**
45    * Host ID that the controller is either given (if this is the
46    * dominating client) or assumed to have (for peer-connections
47    * between controllers).  A controller must check that all
48    * connections make consistent claims...
49    */
50   uint32_t host_id GNUNET_PACKED;
51
52   /**
53    * Event mask that specifies which events this client
54    * is interested in.  In NBO.
55    */
56   uint64_t event_mask GNUNET_PACKED;
57
58   /* Followed by 0-terminated hostname of the controller */
59 };
60
61
62 /**
63  * Notify the service about a host that we intend to use.
64  */
65 struct GNUNET_TESTBED_AddHostMessage
66 {
67
68   /**
69    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST
70    */
71   struct GNUNET_MessageHeader header;
72
73   /**
74    * Unique ID for the host (in NBO).
75    */
76   uint32_t host_id GNUNET_PACKED;
77
78   /**
79    * SSH port to use, 0 for default (in NBO).
80    */
81   uint16_t ssh_port GNUNET_PACKED;
82
83   /**
84    * Number of bytes in the user name that follows;
85    * 0 to use no user name; otherwise 'strlen (username)',
86    * excluding 0-termination!
87    */
88   uint16_t username_length GNUNET_PACKED;
89
90   /**
91    * Number of bytes in the host name (excluding 0-termination) that follows the
92    * user name; cannot be 0
93    */
94   uint16_t hostname_length GNUNET_PACKED;
95
96   /**
97    * The length of the uncompressed configuration
98    */
99   uint16_t config_size GNUNET_PACKED;
100
101   /* followed by non 0-terminated user name */
102
103   /* followed by non 0-terminated host name */
104
105   /* followed by gzip compressed configuration to start or connect to a
106      controller on this host.  While starting the controller this configration
107      is used as a template */
108
109 };
110
111
112 /**
113  * Confirmation from the service that adding a host
114  * worked (or failed).
115  * FIXME: Where is this required?
116  */
117 struct GNUNET_TESTBED_HostConfirmedMessage
118 {
119
120   /**
121    * Type is GNUNET_MESSAGE_TYPE_TESTBED_ADD_HOST_SUCCESS
122    */
123   struct GNUNET_MessageHeader header;
124
125   /**
126    * Unique ID for the host (in NBO).
127    */
128   uint32_t host_id GNUNET_PACKED;
129
130   /* followed by the 0-terminated error message (on failure)
131    * (typical errors include host-id already in use) */
132
133 };
134
135
136 /**
137  * Client notifies controller that it should delegate
138  * requests for a particular client to a particular
139  * sub-controller.
140  */
141 struct GNUNET_TESTBED_ControllerLinkRequest
142 {
143
144   /**
145    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS
146    */
147   struct GNUNET_MessageHeader header;
148
149   /**
150    * For which host should requests be delegated? NBO.
151    */
152   uint32_t delegated_host_id GNUNET_PACKED;
153
154   /**
155    * The id of the operation which created this message
156    */
157   uint64_t operation_id GNUNET_PACKED;
158
159   /**
160    * Which host is responsible for managing the delegation? NBO
161    */
162   uint32_t slave_host_id GNUNET_PACKED;
163
164   /**
165    * Set to 1 if the receiving controller is the master controller for
166    * the slave host (and thus responsible for starting it?). 0 if not
167    */
168   uint8_t is_subordinate;
169
170 };
171
172
173 /**
174  * Response message for ControllerLinkRequest message
175  */
176 struct GNUNET_TESTBED_ControllerLinkResponse
177 {
178
179   /**
180    * Type is GNUNET_MESSAGE_TYPE_TESTBED_LINK_CONTROLLERS_RESULT
181    */
182   struct GNUNET_MessageHeader header;
183
184   /**
185    * The size of the compressed configuration. Can be ZERO if the controller is
186    * not started (depends on the ControllerLinkRequest). NBO.
187    */
188   uint16_t config_size GNUNET_PACKED;
189
190   /**
191    * Set to GNUNET_YES to signify SUCCESS; GNUNET_NO to signify failure
192    */
193   uint16_t success GNUNET_PACKED;
194
195   /**
196    * The id of the operation which created this message. NBO
197    */
198   uint64_t operation_id GNUNET_PACKED;
199
200   /* If controller linking is successful and configuration is present, then here
201    * comes the serialized gzip configuration with which the controller is
202    * running at the delegate host */
203
204   /* In case of failure, here comes the error message (without \0 termination)*/
205
206 };
207
208
209 /**
210  * Message sent from client to testing service to
211  * create (configure, but not start) a peer.
212  */
213 struct GNUNET_TESTBED_PeerCreateMessage
214 {
215
216   /**
217    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER
218    */
219   struct GNUNET_MessageHeader header;
220
221   /**
222    * On which host should the peer be started?
223    */
224   uint32_t host_id GNUNET_PACKED;
225
226   /**
227    * Unique operation id
228    */
229   uint64_t operation_id GNUNET_PACKED;
230
231   /**
232    * Unique ID for the peer.
233    */
234   uint32_t peer_id GNUNET_PACKED;
235
236   /**
237    * Size of the uncompressed configuration
238    */
239   uint16_t config_size GNUNET_PACKED;
240
241   /* followed by serialized peer configuration;
242    * gzip'ed configuration file in INI format */
243
244 };
245
246
247 /**
248  * Message sent from client to testing service to
249  * reconfigure a (stopped) a peer.
250  */
251 struct GNUNET_TESTBED_PeerReconfigureMessage
252 {
253
254   /**
255    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_RECONFIGURE_PEER
256    */
257   struct GNUNET_MessageHeader header;
258
259   /**
260    * Unique ID for the peer.
261    */
262   uint32_t peer_id GNUNET_PACKED;
263
264   /**
265    * Operation ID that is used to identify this operation.
266    */
267   uint64_t operation_id GNUNET_PACKED;
268
269   /**
270    * The length of the serialized configuration when uncompressed
271    */
272   uint16_t config_size GNUNET_PACKED;
273
274   /* followed by serialized peer configuration;
275    * gzip'ed configuration file in INI format */
276
277 };
278
279
280 /**
281  * Message sent from client to testing service to
282  * start a peer.
283  */
284 struct GNUNET_TESTBED_PeerStartMessage
285 {
286
287   /**
288    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_START_PEER
289    */
290   struct GNUNET_MessageHeader header;
291
292   /**
293    * Unique ID for the peer.
294    */
295   uint32_t peer_id GNUNET_PACKED;
296
297   /**
298    * Operation ID that is used to identify this operation.
299    */
300   uint64_t operation_id GNUNET_PACKED;
301
302 };
303
304
305 /**
306  * Message sent from client to testing service to
307  * stop a peer.
308  */
309 struct GNUNET_TESTBED_PeerStopMessage
310 {
311
312   /**
313    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_STOP_PEER
314    */
315   struct GNUNET_MessageHeader header;
316
317   /**
318    * Unique ID for the peer.
319    */
320   uint32_t peer_id GNUNET_PACKED;
321
322   /**
323    * Operation ID that is used to identify this operation.
324    */
325   uint64_t operation_id GNUNET_PACKED;
326
327 };
328
329
330 /**
331  * Message sent from client to testing service to
332  * destroy a (stopped) peer.
333  */
334 struct GNUNET_TESTBED_PeerDestroyMessage
335 {
336
337   /**
338    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_DESTROY_PEER
339    */
340   struct GNUNET_MessageHeader header;
341
342   /**
343    * Unique ID for the peer.
344    */
345   uint32_t peer_id GNUNET_PACKED;
346
347   /**
348    * Operation ID that is used to identify this operation.
349    */
350   uint64_t operation_id GNUNET_PACKED;
351
352 };
353
354
355 /**
356  * Message sent from client to testing service to
357  * (re)configure a "physical" link between two peers.
358  */
359 struct GNUNET_TESTBED_ConfigureUnderlayLinkMessage
360 {
361
362   /**
363    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_CONFIGURE_UNDERLAY_LINK
364    */
365   struct GNUNET_MessageHeader header;
366
367   /**
368    * 'enum GNUNET_TESTBED_ConnectOption' of the option to change
369    */
370   int32_t connect_option GNUNET_PACKED;
371
372   /**
373    * Unique ID for the first peer.
374    */
375   uint32_t peer1 GNUNET_PACKED;
376
377   /**
378    * Unique ID for the second peer.
379    */
380   uint32_t peer2 GNUNET_PACKED;
381
382   /**
383    * Operation ID that is used to identify this operation.
384    */
385   uint64_t operation_id GNUNET_PACKED;
386
387   /* followed by option-dependent variable-size values */
388
389 };
390
391
392 /**
393  * Message sent from client to testing service to
394  * connect two peers.
395  */
396 struct GNUNET_TESTBED_OverlayConnectMessage
397 {
398
399   /**
400    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_OVERLAY_CONNECT
401    */
402   struct GNUNET_MessageHeader header;
403
404   /**
405    * Unique ID for the first peer.
406    */
407   uint32_t peer1 GNUNET_PACKED;
408
409   /**
410    * Operation ID that is used to identify this operation.
411    */
412   uint64_t operation_id GNUNET_PACKED;
413
414   /**
415    * Unique ID for the second peer.
416    */
417   uint32_t peer2 GNUNET_PACKED;
418
419   /**
420    * The ID of the host which runs peer2
421    */
422   uint32_t peer2_host_id GNUNET_PACKED;
423
424 };
425
426
427 /**
428  * Message sent from host controller of a peer(A) to the host controller of
429  * another peer(B) to request B to connect to A
430  */
431 struct GNUNET_TESTBED_RemoteOverlayConnectMessage
432 {
433   /**
434    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_REMOTE_OVERLAY_CONNECT
435    */
436   struct GNUNET_MessageHeader header;
437
438   /**
439    * The Unique ID of B
440    */
441   uint32_t peer GNUNET_PACKED;
442
443   /**
444    * The Operation ID that is used to identify this operation
445    */
446   uint64_t operation_id GNUNET_PACKED;
447
448   /**
449    * Identity of A
450    */
451   struct GNUNET_PeerIdentity peer_identity;
452
453   /**
454    * To be followed by the HELLO message of A
455    */
456   struct GNUNET_MessageHeader hello[0];
457   // FIXME: we usually do not use this gcc-hack as some
458   // compilers / tools really get messed up by it...
459
460 };
461
462
463 /**
464  * Event notification from a controller to a client.
465  */
466 struct GNUNET_TESTBED_PeerEventMessage
467 {
468
469   /**
470    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_PEER_EVENT
471    */
472   struct GNUNET_MessageHeader header;
473
474   /**
475    * `enum GNUNET_TESTBED_EventType` (in NBO);
476    * either #GNUNET_TESTBED_ET_PEER_START or #GNUNET_TESTBED_ET_PEER_STOP.
477    */
478   int32_t event_type GNUNET_PACKED;
479
480   /**
481    * Host where the peer is running.
482    */
483   uint32_t host_id GNUNET_PACKED;
484
485   /**
486    * Peer that was started or stopped.
487    */
488   uint32_t peer_id GNUNET_PACKED;
489
490   /**
491    * Operation ID that is used to identify this operation.
492    */
493   uint64_t operation_id GNUNET_PACKED;
494
495 };
496
497
498 /**
499  * Event notification from a controller to a client.
500  */
501 struct GNUNET_TESTBED_ConnectionEventMessage
502 {
503
504   /**
505    * Type is GNUNET_MESSAGE_TYPE_TESTBED_PEER_CONNECT_EVENT
506    */
507   struct GNUNET_MessageHeader header;
508
509   /**
510    * 'enum GNUNET_TESTBED_EventType' (in NBO);
511    * either GNUNET_TESTBED_ET_CONNECT or GNUNET_TESTBED_ET_DISCONNECT.
512    */
513   int32_t event_type GNUNET_PACKED;
514
515   /**
516    * First peer.
517    */
518   uint32_t peer1 GNUNET_PACKED;
519
520   /**
521    * Second peer.
522    */
523   uint32_t peer2 GNUNET_PACKED;
524
525   /**
526    * Operation ID that is used to identify this operation.
527    */
528   uint64_t operation_id GNUNET_PACKED;
529
530 };
531
532
533 /**
534  * Event notification from a controller to a client.
535  */
536 struct GNUNET_TESTBED_OperationFailureEventMessage
537 {
538
539   /**
540    * Type is GNUNET_MESSAGE_TYPE_TESTBED_OPERATION_FAIL_EVENT
541    */
542   struct GNUNET_MessageHeader header;
543
544   /**
545    * 'enum GNUNET_TESTBED_EventType' (in NBO);
546    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
547    */
548   int32_t event_type GNUNET_PACKED;
549
550   /**
551    * Operation ID of the operation that created this event.
552    */
553   uint64_t operation_id GNUNET_PACKED;
554
555   /* followed by 0-terminated error message */
556
557 };
558
559
560 /**
561  * Event notification from a controller to a client.
562  */
563 struct GNUNET_TESTBED_PeerCreateSuccessEventMessage
564 {
565
566   /**
567    * Type is GNUNET_MESSAGE_TYPE_TESTBED_CREATE_PEER_SUCCESS
568    */
569   struct GNUNET_MessageHeader header;
570
571   /**
572    * Peer identity of the peer that was created.
573    */
574   uint32_t peer_id GNUNET_PACKED;
575
576   /**
577    * Operation ID of the operation that created this event.
578    */
579   uint64_t operation_id GNUNET_PACKED;
580
581 };
582
583
584 /**
585  * Event notification from a controller to a client for
586  * a generic operational success where the operation does
587  * not return any data.
588  */
589 struct GNUNET_TESTBED_GenericOperationSuccessEventMessage
590 {
591
592   /**
593    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GENERIC_OPERATION_SUCCESS
594    */
595   struct GNUNET_MessageHeader header;
596
597   /**
598    * 'enum GNUNET_TESTBED_EventType' (in NBO);
599    * GNUNET_TESTBED_ET_OPERATION_FINISHED.
600    */
601   int32_t event_type GNUNET_PACKED;
602
603   /**
604    * Operation ID of the operation that created this event.
605    */
606   uint64_t operation_id GNUNET_PACKED;
607
608 };
609
610
611 /**
612  * Message sent from client to testing service to
613  * obtain the configuration of a peer.
614  */
615 struct GNUNET_TESTBED_PeerGetConfigurationMessage
616 {
617
618   /**
619    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_PEER_INFORMATION
620    */
621   struct GNUNET_MessageHeader header;
622
623   /**
624    * Unique ID for the peer.
625    */
626   uint32_t peer_id GNUNET_PACKED;
627
628   /**
629    * Operation ID that is used to identify this operation.
630    */
631   uint64_t operation_id GNUNET_PACKED;
632
633 };
634
635
636 /**
637  * Peer configuration and identity reply from controller to a client.
638  */
639 struct GNUNET_TESTBED_PeerConfigurationInformationMessage
640 {
641
642   /**
643    * Type is #GNUNET_MESSAGE_TYPE_TESTBED_PEER_INFORMATION
644    */
645   struct GNUNET_MessageHeader header;
646
647   /**
648    * The id of the peer relevant to this information
649    */
650   uint32_t peer_id GNUNET_PACKED;
651
652   /**
653    * Operation ID of the operation that created this event.
654    */
655   uint64_t operation_id GNUNET_PACKED;
656
657   /**
658    * Identity of the peer.
659    */
660   struct GNUNET_PeerIdentity peer_identity;
661
662   /**
663    * The size of configuration when uncompressed
664    */
665   uint16_t config_size GNUNET_PACKED;
666
667   /* followed by gzip-compressed configuration of the peer */
668
669 };
670
671
672 /**
673  * Message to request configuration of a slave controller
674  */
675 struct GNUNET_TESTBED_SlaveGetConfigurationMessage
676 {
677   /**
678    * Type is GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIGURATION
679    */
680   struct GNUNET_MessageHeader header;
681
682   /**
683    * The id of the slave host
684    */
685   uint32_t slave_id GNUNET_PACKED;
686
687   /**
688    * Operation ID
689    */
690   uint64_t operation_id GNUNET_PACKED;
691
692 };
693
694
695 /**
696  * Reply to #GNUNET_MESSAGE_TYPE_TESTBED_GET_SLAVE_CONFIG message
697  */
698 struct GNUNET_TESTBED_SlaveConfiguration
699 {
700   /**
701    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SLAVE_CONFIGURATION
702    */
703   struct GNUNET_MessageHeader header;
704
705   /**
706    * The id of the host where the slave is running
707    */
708   uint32_t slave_id GNUNET_PACKED;
709
710   /**
711    * Operation ID
712    */
713   uint64_t operation_id GNUNET_PACKED;
714
715   /**
716    * The size of the configuration when uncompressed
717    */
718   uint16_t config_size GNUNET_PACKED;
719
720   /* followed by gzip-compressed configuration of the peer */
721
722 };
723
724
725 /**
726  * Shutdown peers message
727  */
728 struct GNUNET_TESTBED_ShutdownPeersMessage
729 {
730   /**
731    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
732    */
733   struct GNUNET_MessageHeader header;
734
735   /**
736    * Operation ID
737    */
738   uint64_t operation_id GNUNET_PACKED;
739 };
740
741
742 /**
743  * Message to start/stop services of a peer
744  */
745 struct GNUNET_TESTBED_ManagePeerServiceMessage
746 {
747   /**
748    * Type is GNUNET_MESSAGE_TYPE_TESTBED_SHUTDOWN_PEERS
749    */
750   struct GNUNET_MessageHeader header;
751
752   /**
753    * Unique ID of the peer whose service has to be managed.
754    */
755   uint32_t peer_id GNUNET_PACKED;
756
757   /**
758    * Operation ID
759    */
760   uint64_t operation_id GNUNET_PACKED;
761
762   /**
763    * set this to 1 to start the service; 0 to stop the service
764    */
765   uint8_t start;
766
767   /**
768    * The NULL-terminated name of the service to start/stop follows here
769    */
770 };
771
772
773 /**************************************/
774 /* Barriers IPC messages and protocol */
775 /**************************************/
776
777
778 /**
779  * The environmental variable which when available refers to the configuration
780  * file the local testbed controller is using
781  */
782 #define ENV_TESTBED_CONFIG "GNUNET_TESTBED_CONTROLLER_CONFIG"
783
784
785 /**
786  * Message to initialise a barrier
787  */
788 struct GNUNET_TESTBED_BarrierInit
789 {
790   /**
791    * Type is GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_INIT
792    */
793   struct GNUNET_MessageHeader header;
794
795   /**
796    * The quorum percentage needed for crossing the barrier
797    */
798   uint8_t quorum;
799
800   /**
801    * name of the barrier.  Non NULL-terminated.
802    */
803   char name[0];
804 };
805
806
807 /**
808  * Message to cancel a barrier
809  */
810 struct GNUNET_TESTBED_BarrierCancel
811 {
812   /**
813    * Type is GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_CANCEL
814    */
815   struct GNUNET_MessageHeader header;
816
817   /**
818    * The barrier name.  Non NULL terminated
819    */
820   char name[0];
821 };
822
823
824 /**
825  * Message for signalling status changes of a barrier
826  */
827 struct GNUNET_TESTBED_BarrierStatusMsg
828 {
829   /**
830    * Type is GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_STATUS
831    */
832   struct GNUNET_MessageHeader header;
833
834   /**
835    * status.  Use enumerated values of enum BarrierStatus
836    */
837   uint16_t status GNUNET_PACKED;
838
839   /**
840    * strlen of the barrier name
841    */
842   uint16_t name_len GNUNET_PACKED;
843
844   /**
845    * the barrier name (NULL terminated) concatenated with an error message (NULL
846    * terminated) if the status were to indicate an error
847    */
848   char data[0];
849 };
850
851
852 /**
853  * Message sent from peers to the testbed-barrier service to indicate that they
854  * have reached a barrier and are waiting for it to be crossed
855  */
856 struct GNUNET_TESTBED_BarrierWait
857 {
858   /**
859    * Type is GNUNET_MESSAGE_TYPE_TESTBED_BARRIER_WAIT
860    */
861   struct GNUNET_MessageHeader header;
862
863   /**
864    * The name of the barrier they have reached.  Non-NULL terminated.
865    */
866   char name[0];
867 };
868
869
870 GNUNET_NETWORK_STRUCT_END
871 #endif
872 /* end of testbed.h */