MySQL 9.3.0
Source Code Documentation
destination.h
Go to the documentation of this file.
1/*
2 Copyright (c) 2015, 2025, Oracle and/or its affiliates.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2.0,
6 as published by the Free Software Foundation.
7
8 This program is designed to work with certain software (including
9 but not limited to OpenSSL) that is licensed under separate terms,
10 as designated in a particular file or component or in included license
11 documentation. The authors of MySQL hereby grant you an additional
12 permission to link the program and your derivative works with the
13 separately licensed software that they have either included with
14 the program or referenced in the documentation.
15
16 This program is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 GNU General Public License for more details.
20
21 You should have received a copy of the GNU General Public License
22 along with this program; if not, write to the Free Software
23 Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
24*/
25
26#ifndef ROUTING_DESTINATION_INCLUDED
27#define ROUTING_DESTINATION_INCLUDED
28
29#include <cstdint>
30#include <list>
31#include <mutex>
32#include <optional>
33#include <string>
34#include <vector>
35
36#include "context.h"
37#include "my_compiler.h" // MY_ATTRIBUTE
43#include "mysqlrouter/routing.h"
44#include "protocol/protocol.h"
46
47namespace mysql_harness {
48class PluginFuncEnv;
49} // namespace mysql_harness
50
51// first argument is the new set of the allowed nodes
52// second argument is a set of nodes that can be used for new connections
53// third argument is an indication whether we should disconnect existing
54// connections (based on disconnect_on_metadata_unavailable setting)
55// fourth argument is the description of the condition that triggered the change
56// (like 'metadata change' etc.) can be used for logging purposes by the caller
58 std::function<void(const AllowedNodes &, const AllowedNodes &, const bool,
59 const std::string &)>;
60// NOTE: this has to be container like std::list that does not invalidate
61// iterators when it is modified as we return the iterator to the inserted
62// callback to the caller to allow unregistering
63using AllowedNodesChangeCallbacksList = std::list<AllowedNodesChangedCallback>;
65 AllowedNodesChangeCallbacksList::iterator;
66// Starting a socket acceptor returns a value indicating if the start succeeded.
68 std::function<stdx::expected<void, std::string>()>;
69using StopSocketAcceptorCallback = std::function<void()>;
70// First callback argument informs if the instances returned from the metadata
71// has changed. Second argument is a list of new instances available after
72// md refresh.
74 std::function<void(const bool, const AllowedNodes &)>;
75
76/** @class DestinationManager
77 * @brief Manage destinations for a Connection Routing
78 *
79 * This class manages destinations which are used in Connection Routing.
80 * A destination is usually a MySQL Server and is stored using the IP
81 * or hostname together with the TCP port (defaulting to 3306 for classic
82 * protocol or to 33060 for x protocol).
83 */
85 public:
86 using DestVector = std::vector<mysql_harness::Destination>;
87
88 /** @brief Default constructor
89 *
90 * @param io_ctx IO context
91 * @param routing_ctx Routing context
92 */
94 : io_ctx_{io_ctx}, routing_ctx_{routing_ctx} {}
95
96 /** @brief Destructor */
97 virtual ~DestinationManager() = default;
98
99 DestinationManager(const DestinationManager &other) = delete;
103
104 virtual void connect_status(std::error_code ec) = 0;
105
106 /** @brief Start the destination manager
107 *
108 * @param env pointer to the PluginFuncEnv object
109 */
110 virtual void start(const mysql_harness::PluginFuncEnv *env) = 0;
111
112 /**
113 * Set up destination manager, prepare the destinations.
114 *
115 * @return error code on failure
116 */
118 const routing_guidelines::Session_info &session_info) = 0;
119
122 }
123
124 /**
125 * refresh destinations.
126 *
127 * should be called after connecting to all destinations failed.
128 *
129 * @retval true refresh suceeded, there are destinations that could be used.
130 * @retval false refresh failed, there are no destinations that could be used.
131 */
134
135 /**
136 * Trigger listening socket acceptors state handler based on the destination
137 * type.
138 */
139 virtual void handle_sockets_acceptors() = 0;
140
141 /**
142 * Get destination that should be used for connection attempt.
143 *
144 * It uses routing strategies and internal information (last used indexes,
145 * failed attempt information) for destination selection.
146 *
147 * @return Destination candidate used for connection attempt.
148 */
149 virtual std::unique_ptr<Destination> get_next_destination(
151
152 /**
153 * Get destination that was selected as a destination candidate.
154 */
155 virtual std::unique_ptr<Destination> get_last_used_destination() const = 0;
156
157 /**
158 * Get addresses of all nodes that are a possible destination candidates.
159 */
160 virtual std::vector<mysql_harness::Destination> get_destination_candidates()
161 const = 0;
162
163 /**
164 * Check if routing guidelines uses $.session.rand as a match criterion.
165 */
167 if (!routing_ctx_.get_routing_guidelines()) return false;
168 return routing_ctx_.get_routing_guidelines()->session_rand_used();
169 }
170
171 /**
172 * Get information about this given Router instance.
173 */
176 }
177
178 /**
179 * Check if there are read-write destinations that could be used.
180 */
181 virtual bool has_read_write() const = 0;
182
183 /**
184 * Check if there are read-only destinations that could be used.
185 */
186 virtual bool has_read_only() const = 0;
187
188 protected:
190 return routing_ctx_;
191 }
192
195 std::mutex state_mtx_;
196 std::error_code last_ec_;
197};
198
199#endif // ROUTING_DESTINATION_INCLUDED
Manage destinations for a Connection Routing.
Definition: destination.h:84
std::error_code last_ec_
Definition: destination.h:196
virtual bool has_read_write() const =0
Check if there are read-write destinations that could be used.
DestinationManager & operator=(DestinationManager &&other)=delete
virtual void start(const mysql_harness::PluginFuncEnv *env)=0
Start the destination manager.
routing_guidelines::Router_info get_router_info() const
Get information about this given Router instance.
Definition: destination.h:174
net::io_context & io_ctx_
Definition: destination.h:193
std::mutex state_mtx_
Definition: destination.h:195
DestinationManager(net::io_context &io_ctx, MySQLRoutingContext &routing_ctx)
Default constructor.
Definition: destination.h:93
virtual bool refresh_destinations(const routing_guidelines::Session_info &)=0
refresh destinations.
virtual std::vector< mysql_harness::Destination > get_destination_candidates() const =0
Get addresses of all nodes that are a possible destination candidates.
virtual void connect_status(std::error_code ec)=0
DestinationManager & operator=(const DestinationManager &other)=delete
virtual mysqlrouter::ServerMode purpose() const
Definition: destination.h:120
std::vector< mysql_harness::Destination > DestVector
Definition: destination.h:86
DestinationManager(DestinationManager &&other)=delete
bool routing_guidelines_session_rand_used() const
Check if routing guidelines uses $.session.rand as a match criterion.
Definition: destination.h:166
virtual void handle_sockets_acceptors()=0
Trigger listening socket acceptors state handler based on the destination type.
const MySQLRoutingContext & get_routing_context() const
Definition: destination.h:189
virtual stdx::expected< void, std::error_code > init_destinations(const routing_guidelines::Session_info &session_info)=0
Set up destination manager, prepare the destinations.
virtual std::unique_ptr< Destination > get_last_used_destination() const =0
Get destination that was selected as a destination candidate.
virtual ~DestinationManager()=default
Destructor.
virtual std::unique_ptr< Destination > get_next_destination(const routing_guidelines::Session_info &)=0
Get destination that should be used for connection attempt.
MySQLRoutingContext & routing_ctx_
Definition: destination.h:194
DestinationManager(const DestinationManager &other)=delete
virtual bool has_read_only() const =0
Check if there are read-only destinations that could be used.
Allows the obervers to register for notifications on the change in the state of the destination nodes...
Definition: destination_nodes_state_notifier.h:71
MySQLRoutingContext holds data used by MySQLRouting (1 per plugin instances) and MySQLRoutingConnecti...
Definition: context.h:54
routing_guidelines::Router_info get_router_info() const
Definition: context.h:209
std::shared_ptr< routing_guidelines::Routing_guidelines_engine > get_routing_guidelines() const
Definition: context.h:198
PluginFuncEnv object.
Definition: loader.h:675
Definition: io_context.h:61
Definition: expected.h:286
std::function< void()> StopSocketAcceptorCallback
Definition: destination_nodes_state_notifier.h:55
std::function< stdx::expected< void, std::string >()> StartSocketAcceptorCallback
Definition: destination_nodes_state_notifier.h:54
std::function< void(const AllowedNodes &, const AllowedNodes &, const bool, const std::string &)> AllowedNodesChangedCallback
Definition: destination_nodes_state_notifier.h:45
AllowedNodesChangeCallbacksList::iterator AllowedNodesChangeCallbacksListIterator
Definition: destination_nodes_state_notifier.h:51
std::list< AllowedNodesChangedCallback > AllowedNodesChangeCallbacksList
Definition: destination_nodes_state_notifier.h:49
std::function< void(const bool, const AllowedNodes &)> MetadataRefreshCallback
Definition: destination_nodes_state_notifier.h:60
std::vector< AvailableDestination > AllowedNodes
Definition: destination_status_types.h:62
Header for compiler-dependent features.
Definition: common.h:44
ServerMode
Definition: datatypes.h:50
Information about this Router instance.
Definition: routing_guidelines.h:59
Information about incoming session.
Definition: routing_guidelines.h:103