MySQL  8.0.22
Source Code Documentation
gcs_xcom_proxy.h
Go to the documentation of this file.
1 /* Copyright (c) 2015, 2020, Oracle and/or its affiliates.
2 
3  This program is free software; you can redistribute it and/or modify
4  it under the terms of the GNU General Public License, version 2.0,
5  as published by the Free Software Foundation.
6 
7  This program is also distributed with certain software (including
8  but not limited to OpenSSL) that is licensed under separate terms,
9  as designated in a particular file or component or in included license
10  documentation. The authors of MySQL hereby grant you an additional
11  permission to link the program and your derivative works with the
12  separately licensed software that they have included with MySQL.
13 
14  This program is distributed in the hope that it will be useful,
15  but WITHOUT ANY WARRANTY; without even the implied warranty of
16  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17  GNU General Public License, version 2.0, for more details.
18 
19  You should have received a copy of the GNU General Public License
20  along with this program; if not, write to the Free Software
21  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA */
22 
23 #ifndef GCS_XCOM_PROXY_INCLUDED
24 #define GCS_XCOM_PROXY_INCLUDED
25 
26 #include <string>
27 #include <unordered_set> // std::unordered_set
38 #include "plugin/group_replication/libmysqlgcs/xdr_gen/xcom_vp.h"
39 
40 #define XCOM_COMM_STATUS_UNDEFINED -1
41 
42 /**
43  @class gcs_xcom_control_proxy
44 
45  This class is an abstraction layer between xcom and the actual
46  implementation. The purpose of this is to allow Gcs_xcom_control_interface
47  to be unit testable by creating mock classes on top of it.
48 */
50  public:
51  explicit Gcs_xcom_proxy() {}
52 
53  /**
54  The destructor.
55  */
56  virtual ~Gcs_xcom_proxy() {}
57 
58  /**
59  This is an utility member function that is used to call into XCom for
60  creating list with node's addresses and their associated UUIDs. Note
61  that callers must provide the UUID.
62 
63  @param n The number of elements in the list
64  @param names The names to be put on the list
65  @param uuids The UUIDs to be put on the list
66  @return a pointer to the list containing all the elements needed. The
67  caller is responsible to reclaim memory once he is done with this data
68  @c delete_node_address
69  */
70 
71  virtual node_address *new_node_address_uuid(unsigned int n, char *names[],
72  blob uuids[]) = 0;
73 
74  /**
75  This function is responsible to delete the list of nodes that had been
76  previously created by @c new_node_address.
77 
78  @param n the length of the list
79  @param na the list to delete
80  */
81 
82  virtual void delete_node_address(unsigned int n, node_address *na) = 0;
83 
84  /**
85  This member function is responsible to call into XCom consensus and add a
86  node to the group. The caller is responsible for ensuring that the session
87  has been opened before @c open_session and also that the node is not yet
88  in the configuration.
89 
90  The callee must have opened an XCom connection before calling this
91  function. @c xcom_client_open_connection.
92 
93  @param fd the file descriptor to the XCom connection established earlier
94  @param nl The node list containing the list of peers to add
95  @param group_id the identifier of the group to which the nodes should
96  be added
97  @returns true (false) on success (failure). Success means that XCom will
98  process our request, failure means it wont. There could be errors
99  later in the process of adding a node. Since this is basically an
100  asynchronous function, one needs to wait for the actual view change
101  to validate that the node was added to the configuration.
102  */
103 
104  virtual bool xcom_client_add_node(connection_descriptor *fd, node_list *nl,
105  uint32_t group_id) = 0;
106 
107  /**
108  This member function is responsible for triggering the removal of a node
109  from the XCom configuration. This function is asynchronous, so you need to
110  wait for the view change to actually validate that the removal was
111  successful.
112 
113  The caller is responsible for making sure that the server to be removed is
114  in the group.
115 
116  This function MUST be called after opening the local XCom session
117  @c xcom_input_connect.
118 
119  @param nl The list of nodes to remove from the group
120  @param group_id The identifier of the group from which the nodes will
121  be removed
122  @returns true (false) on success (failure). Success means that XCom will
123  process our request, failure means it wont. There could be errors
124  later in the process of removing a node. Since this is basically an
125  asynchronous function, one needs to wait for the actual view change
126  to validate that the nodes were removed from the configuration.
127  */
128 
129  virtual bool xcom_client_remove_node(node_list *nl, uint32_t group_id) = 0;
130 
131  /**
132  This member function is responsible for triggering the removal of a node
133  from the XCom configuration. This function is asynchronous, so you need to
134  wait for the view change to actually validate that the removal was
135  successful.
136 
137  The caller is responsible for making sure that the server to be removed is
138  in the group.
139 
140  The callee must have opened an XCom connection before calling this
141  function. @c xcom_client_open_connection.
142 
143  @param fd the file descriptor to the XCom connection established earlier
144  @param nl The list of nodes to remove from the group
145  @param group_id The identifier of the group from which the nodes will
146  be removed
147  @returns true (false) on success (failure). Success means that XCom will
148  process our request, failure means it wont. There could be errors
149  later in the process of removing a node. Since this is basically an
150  asynchronous function, one needs to wait for the actual view change
151  to validate that the nodes were removed from the configuration.
152  */
153 
154  virtual bool xcom_client_remove_node(connection_descriptor *fd, node_list *nl,
155  uint32_t group_id) = 0;
156 
157  /**
158  This member function is responsible for retrieving the event horizon of the
159  XCom configuration.
160 
161  This function REQUIRES a prior call to @c xcom_open_handlers to establish a
162  connection to XCom.
163 
164  @param[in] group_id The identifier of the group from which the event horizon
165  will be retrieved
166  @param[out] event_horizon A reference to where the group's event horizon
167  value will be written to
168  @retval true if successful and @c event_horizon was written to
169  @retval false otherwise
170 
171  */
172  virtual bool xcom_client_get_event_horizon(
173  uint32_t group_id, xcom_event_horizon &event_horizon) = 0;
174 
175  /**
176  This member function is responsible for triggering the reconfiguration of
177  the event horizon of the XCom configuration. This function is asynchronous,
178  so you need to poll @c xcom_get_event_horizon to actually validate that the
179  reconfiguration was successful.
180 
181  This function REQUIRES a prior call to @c xcom_open_handlers to establish a
182  connection to XCom.
183 
184  @param event_horizon The desired event horizon value
185  @param group_id The identifier of the group from which the nodes will
186  be removed
187  @returns true (false) on success (failure). Success means that XCom will
188  process our request, failure means it wont. There could be errors
189  later in the process of setting the event horizon. Since this is
190  basically an asynchronous function, one needs to busy-wait on
191  @c xcom_client_get_event_horizon to validate that the event horizon
192  was modified.
193  */
194  virtual bool xcom_client_set_event_horizon(
195  uint32_t group_id, xcom_event_horizon event_horizon) = 0;
196 
197  /**
198  This member function is responsible for retrieving the application payloads
199  decided in the synodes in @c synodes, from the XCom instance connected to
200  via @c fd.
201 
202  @param[in] fd The file descriptor to the XCom connection established
203  earlier
204  @param[in] group_id The identifier of the group from which the payloads
205  will be retrieved
206  @param[in] synodes The desired synodes
207  @param[out] reply Where the requested payloads will be written to
208  @returns true (false) on success (failure). Success means that XCom had the
209  requested payloads, which were written to @c reply.
210  */
211  virtual bool xcom_client_get_synode_app_data(
212  connection_descriptor *fd, uint32_t group_id, synode_no_array &synodes,
213  synode_app_data_array &reply) = 0;
214 
215  /**
216  This member function is responsible for setting a new value for the maximum
217  size of the XCom cache.
218 
219  This function is asynchronous, so the return value indicates only whether
220  the request to change the value was successfully pushed to XCom or not.
221  However, since the cache size is set only for the local node, and makes no
222  further verifications on the value, if XCom processes the request, it will
223  accept the new value. The callers of this function must validate that the
224  value set is within the limits set to the maximum size of the XCom cache.
225 
226  This function REQUIRES a prior call to @c xcom_open_handlers to establish a
227  connection to XCom.
228 
229  @param size The new value for the maximum size of the XCom cache.
230  @returns true (false) on success (failure). Success means that XCom will
231  process our request, failure means it wont.
232  */
233  virtual bool xcom_client_set_cache_size(uint64_t size) = 0;
234 
235  /**
236  This member function is responsible for pushing data into consensus on
237  XCom. The caller is responsible to making sure that there is an open XCom
238  session @c xcom_input_connect and also that the server is part of the XCom
239  configuration before sending data to it.
240 
241  @c data must have been allocated by one of the functions of the malloc
242  family, because @c data will be passed on to XCom. XCom is implemented in
243  C and will use @c free to dispose of @c data when it is finished with @c
244  data.
245 
246  This function takes ownership of @c data. This means that this
247  function becomes responsible for the lifetime of @c data. Since this
248  function takes ownership of @c data, the caller must not interact with @c
249  data after passing it to this function.
250 
251  @param size the size of the payload
252  @param data the payload
253  @returns true (false) on success (failure). Success means that XCom will
254  process our request, failure means it wont.
255  */
256 
257  virtual bool xcom_client_send_data(unsigned long long size, char *data) = 0;
258 
259  /**
260  This member function initializes XCom. This function must be called before
261  anything else and from within the XCom thread. It will eventually call
262  the main loop inside XCom.
263 
264  @param listen_port the port that the local XCom is to be listening on.
265  */
266 
267  virtual void xcom_init(xcom_port listen_port) = 0;
268 
269  /**
270  This member function finishes the XCom thread. This function must be
271  called when the XCOM thread was started but the node has not joined
272  a group.
273 
274  There could be errors later in the process of exiting XCom. Since this is
275  basically an asynchronous function, one needs to wait for the XCom thread to
276  to ensure that XCom terminated.
277  */
278 
279  virtual void xcom_exit() = 0;
280 
281  /*
282  Return the operation mode as an integer from an operation mode provided
283  as a string. Note that the string must be provided in upper case letters
284  and the possible values are: "DISABLED", "PREFERRED", "REQUIRED",
285  "VERIFY_CA" or "VERIFY_IDENTITY".
286 
287  If a different value is provide, INVALID_SSL_MODE (-1) is returned.
288  */
289 
290  virtual int xcom_get_ssl_mode(const char *mode) = 0;
291 
292  /*
293  Set the operation mode which might be the following:
294 
295  . SSL_DISABLED (1): The SSL mode will be disabled and this is the default
296  value.
297 
298  . SSL_PREFERRED (2): The SSL mode will be always disabled if this value is
299  provided and is only allowed to keep the solution compatibility with
300  MySQL server.
301 
302  . SSL_REQUIRED (4): The SSL mode will be enabled but the verifications
303  described in the next modes are not performed.
304 
305  . SSL_VERIFY_CA (4) - Verify the server TLS certificate against the
306  configured Certificate Authority (CA) certificates. The connection attempt
307  fails if no valid matching CA certificates are found.
308 
309  . SSL_VERIFY_IDENTITY (5): Like VERIFY_CA, but additionally verify that the
310  server certificate matches the host to which the connection is attempted.
311 
312  If a different value is provide, INVALID_SSL_MODE (-1) is returned.
313  */
314 
315  virtual int xcom_set_ssl_mode(int mode) = 0;
316 
317  /*
318  Return the operation fips mode as an integer from an operation fips mode
319  provided as a string. Note that the string must be provided in upper case
320  letters and the possible values are: "OFF", "ON", "STRICT",
321 
322  If a different value is provide, INVALID_SSL_MODE (-1) is returned.
323  */
324 
325  virtual int xcom_get_ssl_fips_mode(const char *mode) = 0;
326 
327  /*
328  Set the operation fips mode which might be the following:
329 
330  . SSL_FIPS_MODE_OFF (0): This will set openssl fips mode value to 0
331 
332  . SSL_FIPS_MODE_ON (1): This will set openssl fips mode value to 1
333 
334  . SSL_FIPS_MODE_STRICT (2): This will set openssl fips mode value to 2
335 
336  If a different value is provide, INVALID_SSL_FIPS_MODE (-1) is returned.
337  */
338 
339  virtual int xcom_set_ssl_fips_mode(int mode) = 0;
340 
341  /**
342  Initialize the SSL.
343 
344  @returns true (false) on success (failure)
345  */
346 
347  virtual bool xcom_init_ssl() = 0;
348 
349  /*
350  Destroy the SSL Configuration freeing allocated memory.
351  */
352 
353  virtual void xcom_destroy_ssl() = 0;
354 
355  /**
356  Return whether the SSL will be used to encrypt data or not.
357 
358  @returns true (false) if XCom will (not) use SSL
359  */
360 
361  virtual bool xcom_use_ssl() = 0;
362 
363  /*
364  Set the necessary SSL parameters before initialization.
365 
366  server_key_file - Path of file that contains the server's X509 key in PEM
367  format.
368  server_cert_file - Path of file that contains the server's X509 certificate
369  in PEM format.
370  client_key_file - Path of file that contains the client's X509 key in PEM
371  format.
372  client_cert_file - Path of file that contains the client's X509 certificate
373  in PEM format.
374  ca_file - Path of file that contains list of trusted SSL CAs.
375  ca_path - Path of directory that contains trusted SSL CA
376  certificates in PEM format.
377  crl_file - Path of file that contains certificate revocation lists.
378  crl_path - Path of directory that contains certificate revocation
379  list files.
380  cipher - List of permitted ciphers to use for connection
381  encryption.
382  tls_version - Protocols permitted for secure connections.
383  tls_ciphersuites - List of permitted ciphersuites to use for TLS 1.3
384  connection encryption.
385 
386  Note that only the server_key_file/server_cert_file and the client_key_file/
387  client_cert_file are required and the rest of the pointers can be NULL.
388  If the key is provided along with the certificate, either the key file or
389  the other can be ommited.
390 
391  The caller can free the parameters after the SSL is started
392  if this is necessary.
393  */
394  struct ssl_parameters {
395  const char *server_key_file;
396  const char *server_cert_file;
397  const char *client_key_file;
398  const char *client_cert_file;
399  const char *ca_file;
400  const char *ca_path;
401  const char *crl_file;
402  const char *crl_path;
403  const char *cipher;
404  };
405  struct tls_parameters {
406  const char *tls_version;
407  const char *tls_ciphersuites;
408  };
409  virtual void xcom_set_ssl_parameters(ssl_parameters ssl,
410  tls_parameters tls) = 0;
411 
412  virtual site_def const *find_site_def(synode_no synode) = 0;
413 
414  /**
415  This member function boots XCom.
416 
417  @param nl List with a single member - the one that boots the group
418  @param group_id the Group identifier to which the member belongs to
419  @returns true (false) on success (failure). Success means that XCom will
420  process our request, failure means it wont. There could be errors
421  later in the process of booting. Since this is basically an
422  asynchronous function, one needs to wait for XCom to signal it is
423  ready to validate whether it booted.
424  */
425 
426  virtual bool xcom_client_boot(node_list *nl, uint32_t group_id) = 0;
427 
428  /**
429  This member function opens a connection to an XCom instance.
430 
431  @param addr The XCom instance address
432  @param port The XCom instance port
433  @return a valid file descriptor on success, -1 otherwise
434  */
435 
437  std::string addr, xcom_port port) = 0;
438 
439  /**
440  This member function closes the connection to an XCom instance.
441 
442  @param fd The connection file descriptor
443  @returns true (false) on success (failure)
444  */
445 
447 
448  /**
449  This member waits for XCom to be initialized.
450  */
451 
452  virtual enum_gcs_error xcom_wait_ready() = 0;
453 
454  /*
455  This member retrieves the value of XCom initialized
456  */
457  virtual bool xcom_is_ready() = 0;
458 
459  /*
460  This member sets the value of XCom initialized
461  */
462  virtual void xcom_set_ready(bool value) = 0;
463 
464  /*
465  This member signals that XCom has initialized.
466  */
467  virtual void xcom_signal_ready() = 0;
468 
469  /**
470  @brief Call this method to wait for XCom communications to be initialized.
471 
472  Call this method to wait for XCom communications to be initialized. It will
473  block until XCom communications are either OK or error out. The value of
474  the status (XCOM_COMMS_OK or XCOM_COMMS_ERROR) is written into the status
475  out parameters.
476 
477  @param [out] status value of the XCom communication layer status.
478  It can be either XCOM_COMMS_OK or XCOM_COMMS_ERROR
479  */
480  virtual void xcom_wait_for_xcom_comms_status_change(int &status) = 0;
481 
482  /*
483  This verifies if the communication status callback from XCom has been called
484  and if the internal cached status is different from
485  XCOM_COMM_STATUS_UNDEFINED
486  */
487  virtual bool xcom_has_comms_status_changed() = 0;
488 
489  /*
490  This sets the status value of communication status callback from XCom.
491  Its main purpose is to reset the internal cached status to
492  XCOM_COMM_STATUS_UNDEFINED
493 
494  @param status the new status value
495  */
496  virtual void xcom_set_comms_status(int status) = 0;
497 
498  /*
499  This modifies the internal cached status to whatever value is delivered
500  by the XCom communication status callback. Then, it signals all threads
501  that might be waiting on xcom_wait_for_xcom_comms_status_change.
502 
503  @param status the new status value
504  */
505  virtual void xcom_signal_comms_status_changed(int status) = 0;
506 
507  /**
508  @brief Call this method to wait for XCom to exit.
509 
510  Call this method to wait for XCom to exit. It will block until XCom has
511  exit or an error occurs.
512 
513  @return GCS_OK if success, otherwise GCS_NOK.
514  */
515 
516  virtual enum_gcs_error xcom_wait_exit() = 0;
517 
518  /**
519  This verifies if XCom has finished or not.
520  */
521 
522  virtual bool xcom_is_exit() = 0;
523 
524  /**
525  This sets whether XCom has finished or not.
526  */
527 
528  virtual void xcom_set_exit(bool value) = 0;
529 
530  /**
531  Clean up variables used to notify states in the XCOM's state
532  machine.
533  */
534  virtual void xcom_set_cleanup() = 0;
535 
536  /**
537  This modifies the internal cached status and signals all threads
538  that might be waiting on xcom_wait_exit.
539  */
540 
541  virtual void xcom_signal_exit() = 0;
542 
543  /**
544  This method forces XCom to inject a new configuration in the group,
545  even if it does not contain a majority of members.
546 
547  @param nl The list of nodes that will belong to this new configuration
548  @param group_id The identifier of the group from which the nodes will
549  belong
550  @returns true (false) on success (failure). Success means that XCom will
551  process our request, failure means it wont. There could be errors
552  later in the process of forcing the configuration. Since this is
553  basically an asynchronous function, one needs to wait for the
554  actual view change to validate that the configuration was forced.
555  */
556  virtual bool xcom_client_force_config(node_list *nl, uint32_t group_id) = 0;
557 
558  /**
559  Function used to boot a node in XCOM.
560 
561  @param node Node information.
562  @param group_id_hash Hash of group identifier.
563  @returns true (false) on success (failure). Success means that XCom will
564  process our request, failure means it wont. There could be errors
565  later in the process of booting. Since this is basically an
566  asynchronous function, one needs to wait for XCom to signal it is
567  ready to validate whether it booted.
568  */
569  virtual bool xcom_boot_node(Gcs_xcom_node_information &node,
570  uint32_t group_id_hash) = 0;
571 
572  /**
573  Function to remove a set of nodes from XCOM.
574 
575  @param nodes Set of nodes.
576  @param group_id_hash Hash of group identifier.
577  @returns true (false) on success (failure). Success means that XCom will
578  process our request, failure means it wont. There could be errors
579  later in the process of removing a node. Since this is basically an
580  asynchronous function, one needs to wait for the actual view change
581  to validate that the nodes were removed from the configuration.
582  */
583 
584  virtual bool xcom_remove_nodes(Gcs_xcom_nodes &nodes,
585  uint32_t group_id_hash) = 0;
586 
587  /**
588  Function to remove a set of nodes from XCOM.
589 
590  @param con Connection to a node that will carry on the request.
591  @param nodes Set of nodes to remove.
592  @param group_id_hash Hash of group identifier.
593  @returns true (false) on success (failure). Success means that XCom will
594  process our request, failure means it wont. There could be errors
595  later in the process of removing a node. Since this is basically an
596  asynchronous function, one needs to wait for the actual view change
597  to validate that the nodes were removed from the configuration.
598  */
599 
600  virtual bool xcom_remove_nodes(connection_descriptor &con,
601  Gcs_xcom_nodes &nodes,
602  uint32_t group_id_hash) = 0;
603 
604  /**
605  Function to remove a node from XCOM.
606 
607  @param node Node information.
608  @param group_id_hash Hash of group identifier.
609  @returns true (false) on success (failure). Success means that XCom will
610  process our request, failure means it wont. There could be errors
611  later in the process of removing a node. Since this is basically an
612  asynchronous function, one needs to wait for the actual view change
613  to validate that the node was removed from the configuration.
614  */
615 
616  virtual bool xcom_remove_node(const Gcs_xcom_node_information &node,
617  uint32_t group_id_hash) = 0;
618 
619  /**
620  Function to add a set of nodes to XCOM.
621 
622  @param con Connection to a node that will carry on the request.
623  @param nodes Set of nodes.
624  @param group_id_hash Hash of group identifier.
625  @returns true (false) on success (failure). Success means that XCom will
626  process our request, failure means it wont. There could be errors
627  later in the process of adding a node. Since this is basically an
628  asynchronous function, one needs to wait for the actual view change
629  to validate that the nodes were added to the configuration.
630  */
631 
632  virtual bool xcom_add_nodes(connection_descriptor &con, Gcs_xcom_nodes &nodes,
633  uint32_t group_id_hash) = 0;
634 
635  /**
636  Function to add a node to XCOM.
637 
638  @param con Connection to a node that will carry on the request.
639  @param node Node information.
640  @param group_id_hash Hash of group identifier.
641  @returns true (false) on success (failure). Success means that XCom will
642  process our request, failure means it wont. There could be errors
643  later in the process of adding a node. Since this is basically an
644  asynchronous function, one needs to wait for the actual view change
645  to validate that the node was added to the configuration.
646  */
647 
648  virtual bool xcom_add_node(connection_descriptor &con,
649  const Gcs_xcom_node_information &node,
650  uint32_t group_id_hash) = 0;
651 
652  /**
653  Function to retrieve XCOM's minimum supported event horizon value.
654  */
655  virtual xcom_event_horizon xcom_get_minimum_event_horizon() = 0;
656 
657  /**
658  Function to retrieve XCOM's maximum supported event horizon value.
659  */
660  virtual xcom_event_horizon xcom_get_maximum_event_horizon() = 0;
661 
662  /**
663  Function to retrieve XCOM's event horizon.
664 
665  @param[in] group_id_hash Hash of group identifier.
666  @param[out] event_horizon A reference to where the group's event horizon
667  value will be written to
668 
669  @return true if successful, false otherwise
670  */
671  virtual bool xcom_get_event_horizon(uint32_t group_id_hash,
672  xcom_event_horizon &event_horizon) = 0;
673 
674  /**
675  Function to retrieve the application payloads decided on a set of synodes.
676 
677  @param[in] xcom_instance The XCom instance to connect to
678  @param[in] group_id_hash Hash of group identifier.
679  @param[in] synode_set The desired synodes
680  @param[out] reply Where the requested payloads will be written to
681  @returns true (false) on success (failure). Success means that XCom had the
682  requested payloads, which were written to @c reply.
683  */
684  virtual bool xcom_get_synode_app_data(
685  Gcs_xcom_node_information const &xcom_instance, uint32_t group_id_hash,
686  const std::unordered_set<Gcs_xcom_synode> &synode_set,
687  synode_app_data_array &reply) = 0;
688 
689  /**
690  Function to reconfigure XCOM's event horizon.
691 
692  @param group_id_hash Hash of group identifier.
693  @param event_horizon Desired event horizon value.
694 
695  @return true if successful, false otherwise
696  */
697  virtual bool xcom_set_event_horizon(uint32_t group_id_hash,
698  xcom_event_horizon event_horizon) = 0;
699  /**
700  Function to reconfigure the maximum size of the XCom cache.
701 
702  @param size Cache size limit.
703  @return true if the operation is successfully pushed to XCom's queue,
704  false otherwise
705  */
706  virtual bool xcom_set_cache_size(uint64_t size) = 0;
707 
708  /**
709  Function to force the set of nodes in XCOM's configuration.
710 
711  @param nodes Set of nodes.
712  @param group_id_hash Hash of group identifier.
713  @returns true (false) on success (failure). Success means that XCom will
714  process our request, failure means it wont. There could be errors
715  later in the process of forcing the configuration. Since this is
716  basically an asynchronous function, one needs to wait for the
717  actual view change to validate that the configuration was forced.
718  */
719 
720  virtual bool xcom_force_nodes(Gcs_xcom_nodes &nodes,
721  unsigned int group_id_hash) = 0;
722 
723  /**
724  Function that retrieves the value that signals that XCom
725  must be forcefully stopped.
726 
727  @return 1 if XCom needs to forcefully exit. 0 otherwise.
728  */
729  virtual bool get_should_exit() = 0;
730 
731  /**
732  Function that sets the value that signals that XCom
733  must be forcefully stopped.
734  */
735  virtual void set_should_exit(bool should_exit) = 0;
736 
737  /**
738  * Opens the input channel to XCom.
739  *
740  * @param address address to connect to
741  * @param port port to connect to
742  * @retval true if successful
743  * @retval false otherwise
744  */
745  virtual bool xcom_input_connect(std::string const &address,
746  xcom_port port) = 0;
747 
748  /**
749  * Closes the input channel to XCom.
750  */
751  virtual void xcom_input_disconnect() = 0;
752 
753  /**
754  * Attempts to send the command @c data to XCom. (Called by GCS.)
755  *
756  * The function takes ownership of @c data.
757  *
758  * @pre The input channel to XCom is open, i.e. @c xcom_input_connect
759  * @param data the command to send to XCom
760  * @retval true if the command was sent to XCom
761  * @retval false if the command was not sent to XCom
762  */
763  virtual bool xcom_input_try_push(app_data_ptr data) = 0;
764 
765  /**
766  * Attempts to send the command @c data to XCom, and returns a future to
767  * XCom's reply. (Called by GCS.)
768  *
769  * The function takes ownership of @c data.
770  *
771  * @pre The input channel to XCom is open, i.e. @c xcom_input_connect
772  * @param data the command to send to XCom
773  * @returns a future pointer to a Reply object if successful, a future pointer
774  * to nullptr otherwise
775  */
777  app_data_ptr data) = 0;
778 
779  /**
780  * Attempts to retrieve incoming commands. (Called by XCom.)
781  *
782  * @pre The input channel to XCom is open, i.e. @c xcom_input_connect
783  * @retval app_data_ptr linked list of the queued comamnds if the queue is
784  * not empty
785  * @retval nullptr if the queue is empty
786  */
788 
789  /**
790  * Performs a test connection to the given XCom instance via TCP.
791  *
792  * @param host the XCom instance's host
793  * @param port the XCom instance's port
794  * @returns true if we were able to successfully connect, false otherwise.
795  */
796  virtual bool test_xcom_tcp_connection(std::string &host, xcom_port port) = 0;
797 };
798 
799 /*
800  Virtual class that contains implementation of methods used to
801  map a node representation into XCOM's representation.
802  This layer becomes necessary to avoid duplicating code in test
803  cases.
804 */
806  public:
807  explicit Gcs_xcom_proxy_base() {}
808  ~Gcs_xcom_proxy_base() override {}
809 
811  uint32_t group_id_hash) override;
812  bool xcom_remove_nodes(Gcs_xcom_nodes &nodes,
813  uint32_t group_id_hash) override;
815  uint32_t group_id_hash) override;
817  uint32_t group_id_hash) override;
819  uint32_t group_id_hash) override;
821  const Gcs_xcom_node_information &node,
822  uint32_t group_id_hash) override;
823  xcom_event_horizon xcom_get_minimum_event_horizon() override;
824  xcom_event_horizon xcom_get_maximum_event_horizon() override;
825  bool xcom_get_event_horizon(uint32_t group_id_hash,
826  xcom_event_horizon &event_horizon) override;
827  bool xcom_set_event_horizon(uint32_t group_id_hash,
828  xcom_event_horizon event_horizon) override;
830  Gcs_xcom_node_information const &xcom_instance, uint32_t group_id_hash,
831  const std::unordered_set<Gcs_xcom_synode> &synode_set,
832  synode_app_data_array &reply) override;
833  bool xcom_set_cache_size(uint64_t size) override;
834  bool xcom_force_nodes(Gcs_xcom_nodes &nodes, uint32_t group_id_hash) override;
835 
836  private:
837  /* Serialize information on nodes to be sent to XCOM */
838  bool serialize_nodes_information(Gcs_xcom_nodes &nodes, node_list &nl);
839 
840  /* Free information on nodes sent to XCOM */
841  void free_nodes_information(node_list &nl);
842  bool test_xcom_tcp_connection(std::string &host, xcom_port port) override;
843 };
844 
845 /**
846  @class gcs_xcom_control_proxy_impl
847 
848  Implementation of gcs_xcom_control_proxy to be used by whom
849  instantiates Gcs_xcom_control_interface to be used in a real
850  scenario.
851 */
853  public:
854  explicit Gcs_xcom_proxy_impl();
855  Gcs_xcom_proxy_impl(unsigned int wt);
856  ~Gcs_xcom_proxy_impl() override;
857 
858  node_address *new_node_address_uuid(unsigned int n, char *names[],
859  blob uuids[]) override;
860  void delete_node_address(unsigned int n, node_address *na) override;
861  bool xcom_client_add_node(connection_descriptor *fd, node_list *nl,
862  uint32_t group_id) override;
863  bool xcom_client_remove_node(node_list *nl, uint32_t group_id) override;
864  bool xcom_client_remove_node(connection_descriptor *fd, node_list *nl,
865  uint32_t group_id) override;
867  uint32_t group_id, xcom_event_horizon &event_horizon) override;
868  bool xcom_client_set_event_horizon(uint32_t group_id,
869  xcom_event_horizon event_horizon) override;
871  uint32_t group_id_hash,
872  synode_no_array &synodes,
873  synode_app_data_array &reply) override;
874 
875  bool xcom_client_set_cache_size(uint64_t size) override;
876  bool xcom_client_boot(node_list *nl, uint32_t group_id) override;
878  xcom_port port) override;
880  bool xcom_client_send_data(unsigned long long size, char *data) override;
881  void xcom_init(xcom_port listen_port) override;
882  void xcom_exit() override;
883  int xcom_get_ssl_mode(const char *mode) override;
884  int xcom_get_ssl_fips_mode(const char *mode) override;
885  int xcom_set_ssl_fips_mode(int mode) override;
886  int xcom_set_ssl_mode(int mode) override;
887  bool xcom_init_ssl() override;
888  void xcom_destroy_ssl() override;
889  bool xcom_use_ssl() override;
890  void xcom_set_ssl_parameters(ssl_parameters ssl, tls_parameters tls) override;
891  site_def const *find_site_def(synode_no synode) override;
892 
893  enum_gcs_error xcom_wait_ready() override;
894  bool xcom_is_ready() override;
895  void xcom_set_ready(bool value) override;
896  void xcom_signal_ready() override;
897 
899  bool xcom_has_comms_status_changed() override;
900  void xcom_set_comms_status(int status) override;
901  void xcom_signal_comms_status_changed(int status) override;
902 
903  enum_gcs_error xcom_wait_exit() override;
904  bool xcom_is_exit() override;
905  void xcom_set_exit(bool value) override;
906  void xcom_signal_exit() override;
907 
908  void xcom_set_cleanup() override;
909 
910  bool xcom_client_force_config(node_list *nl, uint32_t group_id) override;
911  bool get_should_exit() override;
912  void set_should_exit(bool should_exit) override;
913 
914  bool xcom_input_connect(std::string const &address, xcom_port port) override;
915  void xcom_input_disconnect() override;
916  bool xcom_input_try_push(app_data_ptr data) override;
918  app_data_ptr data) override;
920 
921  private:
922  /*
923  Maximum waiting time used by timed_waits in xcom_wait_ready and
924  xcom_wait_for_xcom_comms_status_change.
925  */
926  unsigned int m_wait_time;
927 
928  // For synchronization between XCom and MySQL GCS infrastructure at startup.
932 
936 
940 
942 
943  // Stores SSL parameters
944  const char *m_server_key_file;
945  const char *m_server_cert_file;
946  const char *m_client_key_file;
947  const char *m_client_cert_file;
948  const char *m_ca_file;
949  const char *m_ca_path;
950  const char *m_crl_file;
951  const char *m_crl_path;
952  const char *m_cipher;
953  const char *m_tls_version;
954  const char *m_tls_ciphersuites;
955 
956  std::atomic_bool m_should_exit;
957 
958  /* Input channel to XCom */
960 
961  /*
962  Auxiliary function for the "xcom_wait_*" functions. Executes the actual
963  timed wait for the variable associated with the condition to be changed
964  and performs error checking.
965 
966  The function will lock @c condition_lock, so it must be unlocked when the
967  function is called.
968 
969  @param condition Cond variable on which we want to wait.
970  @param condition_lock Lock to access the @c condition variable.
971  @param need_to_wait A function implemented by the caller that verifies if
972  the wait shall be executed. The function must return
973  true when the wait must be executed, false otherwise.
974  @param condition_event A function that returns the string identifying the
975  event associated with the cond. The string will be
976  printed as a suffix to the error messages:
977  "<error code> while waiting for <cond_event string>"
978  The function receives the error code of the timed
979  wait as an argument.
980 
981  @retval GCS_OK if the wait is successful;
982  GCS_NOK if the timed wait terminates with an error.
983  */
984  enum_gcs_error xcom_wait_for_condition(
985  My_xp_cond_impl &condition, My_xp_mutex_impl &condition_lock,
986  std::function<bool(void)> need_to_wait,
987  std::function<const std::string(int res)> condition_event);
988 
989  /*
990  Disabling the copy constructor and assignment operator.
991  */
993  Gcs_xcom_proxy_impl &operator=(Gcs_xcom_proxy_impl const &);
994 };
995 
996 /**
997  A Gcs_xcom_interface needs to have an instance of this class
998  initialized before engaging XCom.
999  */
1001  public:
1002  explicit Gcs_xcom_app_cfg() {}
1003 
1004  virtual ~Gcs_xcom_app_cfg() {}
1005 
1006  /**
1007  Initializes the data structures to communicate with
1008  XCom the application injected configuration options.
1009  */
1010  void init();
1011 
1012  /**
1013  Configures how many loops to spin before blocking on
1014  the poll system call.
1015  @param loops the number of spins.
1016  */
1017  void set_poll_spin_loops(unsigned int loops);
1018 
1019  /**
1020  Configures the maximum size of the xcom cache.
1021  @param size the maximum size of the cache.
1022  */
1023  void set_xcom_cache_size(uint64_t size);
1024 
1025  /**
1026  Configures XCom with its unique instance identifier, i.e. its (address,
1027  incarnation) pair.
1028 
1029  Takes ownership of @c identity.
1030 
1031  @param identity the unique identifier
1032  @retval true if there was an error configuring XCom
1033  @retval false if configuration was successful
1034  */
1035  bool set_identity(node_address *identity);
1036 
1037  /**
1038  Must be called when XCom is not engaged anymore.
1039  */
1040  void deinit();
1041 };
1042 
1045  unsigned int port;
1046 };
1047 
1048 #endif /* GCS_XCOM_PROXY_INCLUDED */
virtual void xcom_set_comms_status(int status)=0
const char * ca_file
Definition: gcs_xcom_proxy.h:399
Definition: site_struct.h:29
const char * tls_ciphersuites
Definition: gcs_xcom_proxy.h:407
static mysql_service_status_t deinit()
Component deinitialization.
Definition: audit_api_message_emit.cc:579
const char * server_cert_file
Definition: gcs_xcom_proxy.h:396
const char * m_client_key_file
Definition: gcs_xcom_proxy.h:946
int m_xcom_comms_status
Definition: gcs_xcom_proxy.h:935
const char * m_server_key_file
Definition: gcs_xcom_proxy.h:944
std::atomic_bool m_should_exit
Definition: gcs_xcom_proxy.h:956
~Gcs_xcom_proxy_base() override
Definition: gcs_xcom_proxy.h:808
virtual bool get_should_exit()=0
Function that retrieves the value that signals that XCom must be forcefully stopped.
My_xp_mutex_impl m_lock_xcom_comms_status
Definition: gcs_xcom_proxy.h:933
virtual bool xcom_set_cache_size(uint64_t size)=0
Function to reconfigure the maximum size of the XCom cache.
Definition: gcs_xcom_proxy.h:1043
It represents a node within a group and is identified by the member identifier, unique identifier and...
Definition: gcs_xcom_group_member_information.h:192
const char * client_cert_file
Definition: gcs_xcom_proxy.h:398
const char * tls_version
Definition: gcs_xcom_proxy.h:406
const char * crl_file
Definition: gcs_xcom_proxy.h:401
virtual bool xcom_get_event_horizon(uint32_t group_id_hash, xcom_event_horizon &event_horizon)=0
Function to retrieve XCOM&#39;s event horizon.
Definition: my_xp_cond.h:133
const char * host
Definition: mysqladmin.cc:58
virtual enum_gcs_error xcom_wait_ready()=0
This member waits for XCom to be initialized.
const char * m_cipher
Definition: gcs_xcom_proxy.h:952
virtual void xcom_wait_for_xcom_comms_status_change(int &status)=0
Call this method to wait for XCom communications to be initialized.
mode
Definition: file_handle.h:59
virtual bool xcom_client_close_connection(connection_descriptor *fd)=0
This member function closes the connection to an XCom instance.
virtual bool xcom_add_nodes(connection_descriptor &con, Gcs_xcom_nodes &nodes, uint32_t group_id_hash)=0
Function to add a set of nodes to XCOM.
enum_gcs_error
This enumeration describes errors which can occur during group communication operations.
Definition: gcs_types.h:40
virtual bool xcom_force_nodes(Gcs_xcom_nodes &nodes, unsigned int group_id_hash)=0
Function to force the set of nodes in XCOM&#39;s configuration.
virtual int xcom_set_ssl_mode(int mode)=0
virtual bool xcom_init_ssl()=0
Initialize the SSL.
bool m_is_xcom_exit
Definition: gcs_xcom_proxy.h:939
virtual bool xcom_add_node(connection_descriptor &con, const Gcs_xcom_node_information &node, uint32_t group_id_hash)=0
Function to add a node to XCOM.
const char * m_tls_version
Definition: gcs_xcom_proxy.h:953
static mysql_service_status_t init()
Component initialization.
Definition: audit_api_message_emit.cc:570
virtual xcom_event_horizon xcom_get_maximum_event_horizon()=0
Function to retrieve XCOM&#39;s maximum supported event horizon value.
virtual int xcom_get_ssl_fips_mode(const char *mode)=0
virtual bool xcom_client_set_event_horizon(uint32_t group_id, xcom_event_horizon event_horizon)=0
This member function is responsible for triggering the reconfiguration of the event horizon of the XC...
Gcs_xcom_proxy * proxy
Definition: gcs_xcom_proxy.h:1044
const char * m_tls_ciphersuites
Definition: gcs_xcom_proxy.h:954
const char * crl_path
Definition: gcs_xcom_proxy.h:402
unsigned short xcom_port
Definition: xcom_common.h:45
virtual bool xcom_is_exit()=0
This verifies if XCom has finished or not.
virtual bool xcom_client_get_event_horizon(uint32_t group_id, xcom_event_horizon &event_horizon)=0
This member function is responsible for retrieving the event horizon of the XCom configuration.
virtual bool xcom_client_force_config(node_list *nl, uint32_t group_id)=0
This method forces XCom to inject a new configuration in the group, even if it does not contain a maj...
Gcs_xcom_app_cfg()
Definition: gcs_xcom_proxy.h:1002
virtual xcom_input_request_ptr xcom_input_try_pop()=0
Attempts to retrieve incoming commands.
virtual bool xcom_get_synode_app_data(Gcs_xcom_node_information const &xcom_instance, uint32_t group_id_hash, const std::unordered_set< Gcs_xcom_synode > &synode_set, synode_app_data_array &reply)=0
Function to retrieve the application payloads decided on a set of synodes.
std::future< std::unique_ptr< Reply > > future_reply
Definition: gcs_xcom_input_queue.h:59
static in_port_t port
Definition: testapp.c:33
virtual Gcs_xcom_input_queue::future_reply xcom_input_try_push_and_get_reply(app_data_ptr data)=0
Attempts to send the command data to XCom, and returns a future to XCom&#39;s reply.
virtual bool xcom_is_ready()=0
const char * m_ca_path
Definition: gcs_xcom_proxy.h:949
virtual void delete_node_address(unsigned int n, node_address *na)=0
This function is responsible to delete the list of nodes that had been previously created by new_node...
My_xp_cond_impl m_cond_xcom_ready
Definition: gcs_xcom_proxy.h:930
Interface for socket utility methods.
Definition: my_xp_util.h:153
virtual void xcom_exit()=0
This member function finishes the XCom thread.
virtual void set_should_exit(bool should_exit)=0
Function that sets the value that signals that XCom must be forcefully stopped.
virtual bool test_xcom_tcp_connection(std::string &host, xcom_port port)=0
Performs a test connection to the given XCom instance via TCP.
Definition: gcs_xcom_proxy.h:49
virtual bool xcom_set_event_horizon(uint32_t group_id_hash, xcom_event_horizon event_horizon)=0
Function to reconfigure XCOM&#39;s event horizon.
My_xp_cond_impl m_cond_xcom_comms_status
Definition: gcs_xcom_proxy.h:934
Gcs_xcom_input_queue m_xcom_input_queue
Definition: gcs_xcom_proxy.h:959
Definition: xcom_input_request.cc:27
Definition: node_connection.h:44
unsigned int m_wait_time
Definition: gcs_xcom_proxy.h:926
virtual bool xcom_client_set_cache_size(uint64_t size)=0
This member function is responsible for setting a new value for the maximum size of the XCom cache...
My_xp_socket_util * m_socket_util
Definition: gcs_xcom_proxy.h:941
virtual bool xcom_use_ssl()=0
Return whether the SSL will be used to encrypt data or not.
virtual bool xcom_client_get_synode_app_data(connection_descriptor *fd, uint32_t group_id, synode_no_array &synodes, synode_app_data_array &reply)=0
This member function is responsible for retrieving the application payloads decided in the synodes in...
const char * m_server_cert_file
Definition: gcs_xcom_proxy.h:945
virtual void xcom_input_disconnect()=0
Closes the input channel to XCom.
virtual connection_descriptor * xcom_client_open_connection(std::string addr, xcom_port port)=0
This member function opens a connection to an XCom instance.
virtual void xcom_init(xcom_port listen_port)=0
This member function initializes XCom.
virtual void xcom_signal_ready()=0
virtual void xcom_set_cleanup()=0
Clean up variables used to notify states in the XCOM&#39;s state machine.
const char * m_client_cert_file
Definition: gcs_xcom_proxy.h:947
virtual bool xcom_client_add_node(connection_descriptor *fd, node_list *nl, uint32_t group_id)=0
This member function is responsible to call into XCom consensus and add a node to the group...
Definition: gcs_xcom_proxy.h:852
This class contains information on the configuration, i.e set of nodes or simply site definition...
Definition: gcs_xcom_group_member_information.h:390
Definition: gcs_xcom_proxy.h:805
virtual bool xcom_remove_node(const Gcs_xcom_node_information &node, uint32_t group_id_hash)=0
Function to remove a node from XCOM.
My_xp_cond_impl m_cond_xcom_exit
Definition: gcs_xcom_proxy.h:938
My_xp_mutex_impl m_lock_xcom_ready
Definition: gcs_xcom_proxy.h:929
virtual node_address * new_node_address_uuid(unsigned int n, char *names[], blob uuids[])=0
This is an utility member function that is used to call into XCom for creating list with node&#39;s addre...
virtual bool xcom_input_try_push(app_data_ptr data)=0
Attempts to send the command data to XCom.
const char * ca_path
Definition: gcs_xcom_proxy.h:400
bool m_is_xcom_ready
Definition: gcs_xcom_proxy.h:931
virtual void xcom_set_ssl_parameters(ssl_parameters ssl, tls_parameters tls)=0
const char * m_ca_file
Definition: gcs_xcom_proxy.h:948
Gcs_xcom_proxy()
Definition: gcs_xcom_proxy.h:51
virtual void xcom_destroy_ssl()=0
Definition: gcs_xcom_proxy.h:405
const char * cipher
Definition: gcs_xcom_proxy.h:403
const char * server_key_file
Definition: gcs_xcom_proxy.h:395
int n
Definition: xcom_base.cc:442
virtual bool xcom_remove_nodes(Gcs_xcom_nodes &nodes, uint32_t group_id_hash)=0
Function to remove a set of nodes from XCOM.
virtual ~Gcs_xcom_proxy()
The destructor.
Definition: gcs_xcom_proxy.h:56
virtual bool xcom_client_remove_node(node_list *nl, uint32_t group_id)=0
This member function is responsible for triggering the removal of a node from the XCom configuration...
const char * client_key_file
Definition: gcs_xcom_proxy.h:397
virtual int xcom_set_ssl_fips_mode(int mode)=0
Definition: gcs_xcom_proxy.h:394
virtual void xcom_signal_exit()=0
This modifies the internal cached status and signals all threads that might be waiting on xcom_wait_e...
const char * m_crl_path
Definition: gcs_xcom_proxy.h:951
Gcs_xcom_proxy_base()
Definition: gcs_xcom_proxy.h:807
Definition: my_xp_mutex.h:120
const string value("\alue\)
std::decay_t< T > identity
Definition: string_view.h:176
static STATUS status
Definition: mysql.cc:199
virtual void xcom_set_ready(bool value)=0
virtual ~Gcs_xcom_app_cfg()
Definition: gcs_xcom_proxy.h:1004
My_xp_mutex_impl m_lock_xcom_exit
Definition: gcs_xcom_proxy.h:937
virtual xcom_event_horizon xcom_get_minimum_event_horizon()=0
Function to retrieve XCOM&#39;s minimum supported event horizon value.
virtual site_def const * find_site_def(synode_no synode)=0
A Gcs_xcom_interface needs to have an instance of this class initialized before engaging XCom...
Definition: gcs_xcom_proxy.h:1000
virtual void xcom_signal_comms_status_changed(int status)=0
virtual bool xcom_client_boot(node_list *nl, uint32_t group_id)=0
This member function boots XCom.
virtual bool xcom_client_send_data(unsigned long long size, char *data)=0
This member function is responsible for pushing data into consensus on XCom.
virtual bool xcom_input_connect(std::string const &address, xcom_port port)=0
Opens the input channel to XCom.
virtual enum_gcs_error xcom_wait_exit()=0
Call this method to wait for XCom to exit.
const char * m_crl_file
Definition: gcs_xcom_proxy.h:950
virtual bool xcom_boot_node(Gcs_xcom_node_information &node, uint32_t group_id_hash)=0
Function used to boot a node in XCOM.
virtual void xcom_set_exit(bool value)=0
This sets whether XCom has finished or not.
virtual int xcom_get_ssl_mode(const char *mode)=0
unsigned int port
Definition: gcs_xcom_proxy.h:1045
virtual bool xcom_has_comms_status_changed()=0