Manage the MySQL Router application. More...

#include <router_app.h>

Public Member Functions
	MySQLRouter ()
	Default constructor. More...

	MySQLRouter (const std::string &program_name, const std::vector< std::string > &arguments, std::ostream &out_stream=std::cout, std::ostream &err_stream=std::cerr, mysqlrouter::SysUserOperationsBase *sys_user_operations=mysqlrouter::SysUserOperations::instance())
	Constructor with command line arguments as vector. More...

	MySQLRouter (const int argc, char *argv, std::ostream &out_stream, std::ostream &err_stream, mysqlrouter::SysUserOperationsBase sys_user_operations=mysqlrouter::SysUserOperations::instance())
	Constructor with command line arguments. More...

virtual	~MySQLRouter ()=default

std::string	get_package_name () noexcept

std::string	get_version () noexcept
	Returns the MySQL Router version as string. More...

std::string	get_version_line () noexcept
	Returns string version details. More...

void	start ()
	Starts the MySQL Router application. More...

void	stop ()
	Stop and cleanup the MySQL Router application. More...

const std::vector< std::string > &	get_default_config_files () const noexcept
	Gets list of default configuration files. More...

const std::vector< std::string > &	get_config_files () const noexcept
	Gets list of configuration files passed using command line. More...

const std::vector< std::string > &	get_extra_config_files () const noexcept
	Gets list of extra configuration files passed using command line. More...

Static Public Member Functions
static void	init_main_logger (mysql_harness::LoaderConfig &config, bool raw_mode=false, bool use_os_log=false)
	Initialize main logger. More...

Private Member Functions
virtual void	init (const std::string &program_name, const std::vector< std::string > &arguments)
	Initializes the MySQL Router application. More...

void	prepare_command_options () noexcept
	Prepares a command line option. More...

void	parse_command_options (const std::vector< std::string > &arguments)
	Process command line options. More...

std::vector< std::string >	check_config_files ()
	Finds all valid configuration files. More...

void	show_help ()
	Shows the help screen on the console. More...

void	save_bootstrap_option_not_empty (const std::string &option_name, const std::string &save_name, const std::string &option_value)
	Saves the selected command line option in the internal options array after verifying it's value not empty and the router is doing bootstrap. More...

void	assert_bootstrap_mode (const std::string &option_name) const
	verify that bootstrap option (–bootstrap or -B) was given by user. More...

void	assert_not_bootstrap_mode (const std::string &option_name) const
	verify that option given by user is not used with bootstrap option (–bootstrap or -B). More...

void	assert_option_value_in_range (const std::string &option_value, const int min, const int max) const
	verify that option given by user is an integer value in the given range. More...

void	show_usage (bool include_options) noexcept
	Shows command line usage and option description. More...

void	show_usage () noexcept

void	set_default_config_files (const char *locations) noexcept
	Sets default configuration file locations. More...

void	bootstrap (const std::string &program_name, const std::string &metadata_server_uri, const std::string &plugin_folder="")

uint32_t	get_router_id (mysql_harness::Config &config)

void	init_keyring (mysql_harness::Config &config)

void	init_dynamic_state (mysql_harness::Config &config)

void	init_keyring_using_external_facility (mysql_harness::Config &config)
	Initializes keyring using master-key-reader and master-key-writer. More...

void	init_keyring_using_master_key_file ()
	Initializes keyring using master key file. More...

void	init_keyring_using_prompted_password ()
	Initializes keyring using password read from STDIN. More...

void	init_loader (mysql_harness::LoaderConfig &config)

mysql_harness::LoaderConfig *	make_config (const std::map< std::string, std::string > params, const std::vector< std::string > &config_files)

std::map< std::string, std::string >	get_default_paths () const

Private Attributes
std::tuple< const uint8_t, const uint8_t, const uint8_t >	version_
	Tuple describing the MySQL Router version, with major, minor and patch level. More...

std::vector< std::string >	default_config_files_
	Vector with default configuration file locations as strings. More...

std::vector< std::string >	extra_config_files_
	Vector with extra configuration file locations as strings. More...

std::vector< std::string >	config_files_
	Vector with configuration files passed through command line arguments. More...

std::string	pid_file_path_
	PID file location. More...

bool	pid_file_created_ {false}

CmdArgHandler	arg_handler_
	CmdArgHandler object handling command line arguments. More...

std::unique_ptr< mysql_harness::Loader >	loader_
	Harness loader. More...

bool	can_start_
	Whether the MySQLRouter can start or not. More...

bool	showing_info_
	Whether we are showing information on command line, for example, using –help or –version. More...

std::string	bootstrap_uri_
	Value of the argument passed to the -B or –bootstrap command line option for bootstrapping. More...

std::string	bootstrap_directory_
	Valueof the argument passed to the –directory command line option. More...

std::map< std::string, std::string >	bootstrap_options_
	key/value map of additional configuration options for bootstrap More...

std::map< std::string, std::vector< std::string > >	bootstrap_multivalue_options_
	key/list-of-values map of additional configuration options for bootstrap More...

mysql_harness::Path	origin_
	Path to origin of executable. More...

KeyringInfo	keyring_info_

std::ostream &	out_stream_

std::ostream &	err_stream_

bool	core_file_ {false}

std::string	user_cmd_line_
	Value of the –user parameter given on the command line if router is launched in bootstrap mode. More...

std::string	username_
	Value of the –user parameter given on the command line. More...

mysqlrouter::SysUserOperationsBase *	sys_user_operations_
	Pointer to the object to be used to perform system specific user-related operations. More...

mysql_harness::SignalHandler	signal_handler_

Detailed Description

Manage the MySQL Router application.

The class MySQLRouter manages the MySQL Router application. It handles the command arguments, finds valid configuration files, and starts all plugins.

Since MySQL Router requires at least 1 configuration file to be available for reading, if no default configuration file location could be read and no explicit location was given, the application exits.

The class depends on MySQL Harness to, among other things, load the configuration and initialize all request plugins.

Example usage:

int main(int argc, char** argv) { MySQLRouter router(argc, argv); router.start(); }

Constructor & Destructor Documentation

◆ MySQLRouter() [1/3]

MySQLRouter::MySQLRouter ( )

inline

Default constructor.

Default constructor of MySQL Router which will not initialize.

Usage:

MySQLRouter router;
router.start();

◆ MySQLRouter() [2/3]

MySQLRouter::MySQLRouter	(	const std::string &	program_name,
		const std::vector< std::string > &	arguments,
		std::ostream &	out_stream = `std::cout`,
		std::ostream &	err_stream = `std::cerr`,
		mysqlrouter::SysUserOperationsBase *	sys_user_operations = `mysqlrouter::SysUserOperations::instance()`
	)

Constructor with command line arguments as vector.

Constructor of MySQL Router which will start with the given command line arguments as a vector of strings.

Example usage:

MySQLRouter router(argv[0],
                   vector<string>({argv + 1, argv + argc}));
router.start();

Parameters

program_name	path of the started executable
arguments	a vector of strings
out_stream	output stream representing "stdout"
err_stream	output stream representing "stderr"
sys_user_operations	system operations which provide chown, ...

◆ MySQLRouter() [3/3]

MySQLRouter::MySQLRouter	(	const int	argc,
		char **	argv,
		std::ostream &	out_stream,
		std::ostream &	err_stream,
		mysqlrouter::SysUserOperationsBase *	sys_user_operations = `mysqlrouter::SysUserOperations::instance()`
	)

Constructor with command line arguments.

Constructor of MySQL Router which will start with the given command line arguments given as the arguments argc and argv. Typically, argc and argv are passed on from the global main function.

Example usage:

int main(int argc, char** argv) {
  MySQLRouter router(argc, argv);
  router.start();
}

Parameters

argc	number of arguments
argv	pointer to first command line argument
out_stream	output stream representing "stdout"
err_stream	output stream representing "stderr"
sys_user_operations	system operations which provide chown, ...

◆ ~MySQLRouter()

virtual MySQLRouter::~MySQLRouter ( )

virtualdefault

Member Function Documentation

◆ assert_bootstrap_mode()

void MySQLRouter::assert_bootstrap_mode ( const std::string & option_name ) const

private

verify that bootstrap option (–bootstrap or -B) was given by user.

Exceptions

std::runtime_error if called in non-bootstrap mode.

◆ assert_not_bootstrap_mode()

void MySQLRouter::assert_not_bootstrap_mode ( const std::string & option_name ) const

private

verify that option given by user is not used with bootstrap option (–bootstrap or -B).

Exceptions

std::runtime_error if called in bootstrap mode.

◆ assert_option_value_in_range()

void MySQLRouter::assert_option_value_in_range	(	const std::string &	option_value,
		const int	min,
		const int	max
	)		const

private

verify that option given by user is an integer value in the given range.

Exceptions

std::out_of_range	- option not in [min, max] range
std::invalid_argument	- not a valid integer

◆ bootstrap()

void MySQLRouter::bootstrap	(	const std::string &	program_name,
		const std::string &	metadata_server_uri,
		const std::string &	plugin_folder = `""`
	)

private

◆ check_config_files()

std::vector< std::string > MySQLRouter::check_config_files ( )

private

Finds all valid configuration files.

Finds all valid configuration files from the list of default configuration file locations.

An exception of type std::runtime_error is thrown when no valid configuration file was found.

Returns: returns a list of valid configuration file locations

◆ get_config_files()

const std::vector< std::string > & MySQLRouter::get_config_files ( ) const

inlinenoexcept

Gets list of configuration files passed using command line.

Returns a list of configuration files which were passed through command line options.

Returns: std::vector<string>

◆ get_default_config_files()

const std::vector< std::string > & MySQLRouter::get_default_config_files ( ) const

inlinenoexcept

Gets list of default configuration files.

Returns a list of configuration files which will be read (if available) by default.

Returns: std::vector<string>

◆ get_default_paths()

std::map< std::string, std::string > MySQLRouter::get_default_paths ( ) const

private

◆ get_extra_config_files()

const std::vector< std::string > & MySQLRouter::get_extra_config_files ( ) const

inlinenoexcept

Gets list of extra configuration files passed using command line.

Returns a list of extra configuration files which were passed through command line options.

Returns: std::vector<string>

◆ get_package_name()

std::string MySQLRouter::get_package_name ( )

noexcept

◆ get_router_id()

uint32_t MySQLRouter::get_router_id ( mysql_harness::Config & config )

private

◆ get_version()

std::string MySQLRouter::get_version ( )

noexcept

Returns the MySQL Router version as string.

Returns the MySQL Router as a string. The string is a concatenation of version's major, minor and patch parts, for example 1.0.2.

Returns: string containing the version

◆ get_version_line()

std::string MySQLRouter::get_version_line ( )

noexcept

Returns string version details.

Returns string with name and version details, including:

name of the application,
version,
platform and architecture,
edition,
and a special part-of-clause.

The architecture is either 32-bit or 64-bit. Edition is usually used to denote whether release is either GPLv2 license or commercial.

The part-of clause is used to show which product family MySQL Router belongs to.

Returns: a string containing version details

◆ init()

void MySQLRouter::init	(	const std::string &	program_name,
		const std::vector< std::string > &	arguments
	)

privatevirtual

Initializes the MySQL Router application.

Initialized the MySQL Router application by

setting the default configuration files,
loading the command line options,
processing the given command line arguments,
and finding all the usable configuration files.

The command line options are passed using the arguments argument. It should be a vector of strings. For example, to start MySQL Router using the main() functions argc and argv arguments:

MySQLRouter router(vector<string>({argv + 1, argv + argc}));
router.start();

Parameters

program_name	path to the executable.
arguments	command line arguments as vector of strings

◆ init_dynamic_state()

void MySQLRouter::init_dynamic_state ( mysql_harness::Config & config )

private

◆ init_keyring()

void MySQLRouter::init_keyring ( mysql_harness::Config & config )

private

◆ init_keyring_using_external_facility()

void MySQLRouter::init_keyring_using_external_facility ( mysql_harness::Config & config )

private

Initializes keyring using master-key-reader and master-key-writer.

Exceptions

MasterKeyReadError

◆ init_keyring_using_master_key_file()

void MySQLRouter::init_keyring_using_master_key_file ( )

private

Initializes keyring using master key file.

Exceptions

std::runtime_error

◆ init_keyring_using_prompted_password()

void MySQLRouter::init_keyring_using_prompted_password ( )

private

Initializes keyring using password read from STDIN.

Exceptions

std::runtime_error

◆ init_loader()

void MySQLRouter::init_loader ( mysql_harness::LoaderConfig & config )

private

◆ init_main_logger()

void MySQLRouter::init_main_logger	(	mysql_harness::LoaderConfig &	config,
		bool	raw_mode = `false`,
		bool	use_os_log = `false`
	)

static

Initialize main logger.

Initializes main logger, according to options in the configuration.

Parameters

config	Configuration to be used to initialize logger
raw_mode	If true, all messages are logged raw; if false, messages are subject formatting
use_os_log	If true, Windows EventLog will be used instead of STDERR; Currently this option is only meaningful on Windows

Exceptions

std::runtime_error

on:

failure to initialize file or OS logger
bad configuration

Note: This function is static and public, because unlike create_plugin_loggers(), it's also meant to be called very early during startup, close to main().

◆ make_config()

mysql_harness::LoaderConfig * MySQLRouter::make_config	(	const std::map< std::string, std::string >	params,
		const std::vector< std::string > &	config_files
	)

private

◆ parse_command_options()

void MySQLRouter::parse_command_options ( const std::vector< std::string > & arguments )

private

Process command line options.

Processes command line options for the MySQL Router mysqlrouter application.

◆ prepare_command_options()

void MySQLRouter::prepare_command_options ( )

privatenoexcept

Prepares a command line option.

Prepares command line options for the MySQL Router mysqlrouter application.

◆ save_bootstrap_option_not_empty()

void MySQLRouter::save_bootstrap_option_not_empty	(	const std::string &	option_name,
		const std::string &	save_name,
		const std::string &	option_value
	)

private

Saves the selected command line option in the internal options array after verifying it's value not empty and the router is doing bootstrap.

Throws: std::runtime_error

◆ set_default_config_files()

void MySQLRouter::set_default_config_files ( const char * locations )

privatenoexcept

Sets default configuration file locations.

Sets the default configuration file locations based on information found in the locations argument. The locations should be provided as a semicolon separated list.

The previous loaded locations are first removed. If not new locations were provider (if locations argument is empty), then no configuration files will be available.

Locations can include environment variable placeholders. These placeholders are replaced using the provided name. For example, user Jane executing MySQL Router:

 /opt/ENV{USER}/etc    becomes   /opt/jane/etc

If the environment variable is not available, for example if MYSQL_ROUTER_HOME was not set before starting MySQL Router, every location using this environment variable will be ignored.

Parameters

locations a char* with semicolon separated file locations

◆ show_help()

void MySQLRouter::show_help ( )

private

Shows the help screen on the console.

Shows the help screen on the console including

copyright and trademark notice,
command line usage,
default configuration file locations,
and options with their descriptions.

Users would use the command line option --help:

shell> mysqlrouter --help

◆ show_usage() [1/2]

void MySQLRouter::show_usage ( )

privatenoexcept

◆ show_usage() [2/2]

void MySQLRouter::show_usage ( bool include_options )

privatenoexcept

Shows command line usage and option description.

Shows command line usage and all available options together with their description. It is possible to prevent the option listing by setting the argument include_options to false.

Parameters

include_options bool whether we show the options and descriptions

◆ start()

void MySQLRouter::start ( )

Starts the MySQL Router application.

Starts the MySQL Router application, reading the configuration file(s) and loading and starting all plugins.

Example:

MySQLRouter router;
router.start();

Throws std::runtime_error on configuration or plugin errors.

◆ stop()

void MySQLRouter::stop ( )

Stop and cleanup the MySQL Router application.

Cleanup to perform when the MySQL Router application shuts down.

Example:

MySQLRouter router;
router.start();
...
router.stop();

Throws std::runtime_error on errors during cleanup.

Member Data Documentation

◆ arg_handler_

CmdArgHandler MySQLRouter::arg_handler_

private

CmdArgHandler object handling command line arguments.

◆ bootstrap_directory_

std::string MySQLRouter::bootstrap_directory_

private

Valueof the argument passed to the –directory command line option.

◆ bootstrap_multivalue_options_

std::map<std::string, std::vector<std::string> > MySQLRouter::bootstrap_multivalue_options_

private

key/list-of-values map of additional configuration options for bootstrap

◆ bootstrap_options_

std::map<std::string, std::string> MySQLRouter::bootstrap_options_

private

key/value map of additional configuration options for bootstrap

◆ bootstrap_uri_

std::string MySQLRouter::bootstrap_uri_

private

Value of the argument passed to the -B or –bootstrap command line option for bootstrapping.

◆ can_start_

bool MySQLRouter::can_start_

private

Whether the MySQLRouter can start or not.

◆ config_files_

std::vector<std::string> MySQLRouter::config_files_

private

Vector with configuration files passed through command line arguments.

◆ core_file_

bool MySQLRouter::core_file_ {false}

private

◆ default_config_files_

std::vector<std::string> MySQLRouter::default_config_files_

private

Vector with default configuration file locations as strings.

◆ err_stream_

std::ostream& MySQLRouter::err_stream_

private

◆ extra_config_files_

std::vector<std::string> MySQLRouter::extra_config_files_

private

Vector with extra configuration file locations as strings.

◆ keyring_info_

KeyringInfo MySQLRouter::keyring_info_

private

◆ loader_

std::unique_ptr<mysql_harness::Loader> MySQLRouter::loader_

private

Harness loader.

◆ origin_

mysql_harness::Path MySQLRouter::origin_

private

Path to origin of executable.

This variable contain the directory that the executable is running from.

◆ out_stream_

std::ostream& MySQLRouter::out_stream_

private

◆ pid_file_created_

bool MySQLRouter::pid_file_created_ {false}

private

◆ pid_file_path_

std::string MySQLRouter::pid_file_path_

private

PID file location.

◆ showing_info_

bool MySQLRouter::showing_info_

private

Whether we are showing information on command line, for example, using –help or –version.

◆ signal_handler_

mysql_harness::SignalHandler MySQLRouter::signal_handler_

private

◆ sys_user_operations_

mysqlrouter::SysUserOperationsBase* MySQLRouter::sys_user_operations_

private

Pointer to the object to be used to perform system specific user-related operations.

◆ user_cmd_line_

std::string MySQLRouter::user_cmd_line_

private

Value of the –user parameter given on the command line if router is launched in bootstrap mode.

◆ username_

std::string MySQLRouter::username_

private

Value of the –user parameter given on the command line.

It is used to buffer the value of –user parameter till all command line parameters are parsed. If router is launched in bootstrap mode, then username_ is copied to user_cmd_line_, otherwise it is copied to bootstrap_options_["user"]

◆ version_

std::tuple<const uint8_t, const uint8_t, const uint8_t> MySQLRouter::version_

private

Tuple describing the MySQL Router version, with major, minor and patch level.

The documentation for this class was generated from the following files:

router/src/router/src/router_app.h
router/src/router/src/router_app.cc

Public Member Functions

Static Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ MySQLRouter() [1/3]

◆ MySQLRouter() [2/3]

◆ MySQLRouter() [3/3]

◆ ~MySQLRouter()

Member Function Documentation

◆ assert_bootstrap_mode()

◆ assert_not_bootstrap_mode()

◆ assert_option_value_in_range()

◆ bootstrap()

◆ check_config_files()

◆ get_config_files()

◆ get_default_config_files()

◆ get_default_paths()

◆ get_extra_config_files()

◆ get_package_name()

◆ get_router_id()

◆ get_version()

◆ get_version_line()

◆ init()

◆ init_dynamic_state()

◆ init_keyring()

◆ init_keyring_using_external_facility()

◆ init_keyring_using_master_key_file()

◆ init_keyring_using_prompted_password()

◆ init_loader()

◆ init_main_logger()

◆ make_config()

◆ parse_command_options()

◆ prepare_command_options()

◆ save_bootstrap_option_not_empty()

◆ set_default_config_files()

◆ show_help()

◆ show_usage() [1/2]

◆ show_usage() [2/2]

◆ start()

◆ stop()

Member Data Documentation

◆ arg_handler_

◆ bootstrap_directory_

◆ bootstrap_multivalue_options_

◆ bootstrap_options_

◆ bootstrap_uri_

◆ can_start_

◆ config_files_

◆ core_file_

◆ default_config_files_

◆ err_stream_

◆ extra_config_files_

◆ keyring_info_

◆ loader_

◆ origin_

◆ out_stream_

◆ pid_file_created_

◆ pid_file_path_

◆ showing_info_

◆ signal_handler_

◆ sys_user_operations_

◆ user_cmd_line_

◆ username_

◆ version_