Wrapper around messaging_client that adds automatic reconnection with exponential backoff and circuit breaker pattern. More...

#include <resilient_client.h>

Collaboration diagram for kcenon::network::utils::resilient_client:

Public Member Functions
	resilient_client (const std::string &client_id, const std::string &host, unsigned short port, size_t max_retries=3, std::chrono::milliseconds initial_backoff=std::chrono::seconds(1))
	Constructs a resilient client with reconnection support.

	~resilient_client () noexcept
	Destructor - disconnects client if still connected.

auto	connect () -> VoidResult
	Connects to the server with retry logic.

auto	disconnect () -> VoidResult
	Disconnects from the server.

auto	send_with_retry (std::vector< uint8_t > &&data) -> VoidResult
	Sends data with automatic reconnection on failure.

auto	is_connected () const noexcept -> bool
	Checks if currently connected to server.

auto	set_reconnect_callback (std::function< void(size_t attempt)> callback) -> void
	Sets callback for reconnection events.

auto	set_disconnect_callback (std::function< void()> callback) -> void
	Sets callback for connection loss events.

auto	get_client () const -> std::shared_ptr< core::messaging_client >
	Gets the underlying messaging client.

Private Member Functions
auto	reconnect () -> VoidResult
	Attempts to reconnect with exponential backoff.

auto	calculate_backoff (size_t attempt) const -> std::chrono::milliseconds
	Calculates backoff duration for given attempt.

Private Attributes
std::shared_ptr< core::messaging_client >	client_

std::string	host_

unsigned short	port_

size_t	max_retries_

std::chrono::milliseconds	initial_backoff_

std::atomic< bool >	is_connected_ {false}

std::function< void(size_t)>	reconnect_callback_

std::function< void()>	disconnect_callback_

Detailed Description

Wrapper around messaging_client that adds automatic reconnection with exponential backoff and circuit breaker pattern.

Thread Safety

All public methods are thread-safe
Reconnection logic is protected by internal state management
Callbacks are invoked on reconnection thread

Key Features

Automatic reconnection on connection loss
Exponential backoff to prevent connection storms
Configurable retry behavior (max attempts, backoff)
Circuit breaker pattern to prevent cascade failures
Callback notifications for reconnection events
Graceful degradation on persistent failures

Circuit Breaker Integration

The circuit breaker prevents excessive retry attempts when the backend is unavailable. When the circuit opens, send_with_retry() will fail immediately without attempting network calls.

Usage Example

auto client = std::make_shared<resilient_client>(
    "client_id", "localhost", 8080,
    3,  // max retries
    std::chrono::seconds(1),  // initial backoff
    common::resilience::circuit_breaker_config{
        .failure_threshold = 5,
        .timeout = std::chrono::seconds(30)
    }
);
 
client->set_reconnect_callback([](size_t attempt) {
    std::cout << "Reconnecting (attempt " << attempt << ")\n";
});
 
auto result = client->connect();
if (!result) {
    std::cerr << "Failed to connect\n";
}
 
// Send with automatic retry and circuit breaker protection
std::vector<uint8_t> data = {1, 2, 3};
auto send_result = client->send_with_retry(std::move(data));
 
// Check circuit state
if (client->circuit_state() == common::resilience::circuit_state::OPEN) {
    std::cerr << "Circuit is open, backend unavailable\n";
}

Definition at line 80 of file resilient_client.h.

Constructor & Destructor Documentation

◆ resilient_client()

kcenon::network::utils::resilient_client::resilient_client	(	const std::string &	client_id,
		const std::string &	host,
		unsigned short	port,
		size_t	max_retries = 3,
		std::chrono::milliseconds	initial_backoff = std::chrono::seconds(1) )

Constructs a resilient client with reconnection support.

Parameters

client_id	Client identifier
host	Server hostname or IP address
port	Server port number
max_retries	Maximum number of reconnection attempts (default: 3)
initial_backoff	Initial backoff duration (default: 1 second)
cb_config	Circuit breaker configuration (default values if not specified)

Definition at line 14 of file resilient_client.cpp.

        : host_(host)
        , port_(port)
        , max_retries_(max_retries)
        , initial_backoff_(initial_backoff)
#ifdef WITH_COMMON_SYSTEM
        , circuit_breaker_(std::make_unique<common::resilience::circuit_breaker>(cb_config))
#endif
    {
        client_ = std::make_shared<core::messaging_client>(client_id);
#ifdef WITH_COMMON_SYSTEM
        NETWORK_LOG_INFO("[resilient_client] Created with max_retries=" +
            std::to_string(max_retries) + ", initial_backoff=" +
            std::to_string(initial_backoff.count()) + "ms" +
            ", circuit_breaker failure_threshold=" +
            std::to_string(cb_config.failure_threshold));
#else
        NETWORK_LOG_INFO("[resilient_client] Created with max_retries=" +
            std::to_string(max_retries) + ", initial_backoff=" +
            std::to_string(initial_backoff.count()) + "ms");
#endif
    }

References client_, and NETWORK_LOG_INFO.

◆ ~resilient_client()

kcenon::network::utils::resilient_client::~resilient_client ( )

noexcept

Destructor - disconnects client if still connected.

Definition at line 45 of file resilient_client.cpp.

    {
        try
        {
            if (is_connected_.load())
            {
                (void)disconnect();
            }
        }
        catch (...)
        {
            // Destructor must not throw
        }
    }

References disconnect(), and is_connected_.

Here is the call graph for this function:

Member Function Documentation

◆ calculate_backoff()

auto kcenon::network::utils::resilient_client::calculate_backoff ( size_t attempt ) const -> std::chrono::milliseconds

private

Calculates backoff duration for given attempt.

Parameters

attempt Current attempt number (1-based)

Returns: Backoff duration in milliseconds

Definition at line 310 of file resilient_client.cpp.

    {
        // Exponential backoff: initial_backoff * 2^(attempt-1)
        // Capped at 30 seconds to prevent excessive delays
        auto backoff = initial_backoff_ * (1 << (attempt - 1));
        auto max_backoff = std::chrono::duration_cast<std::chrono::milliseconds>(
            std::chrono::seconds(30));
 
        return std::min(backoff, max_backoff);
    }

◆ connect()

auto kcenon::network::utils::resilient_client::connect ( ) -> VoidResult

Connects to the server with retry logic.

Returns: Result<void> - Success if connected, error otherwise

Attempts to connect with exponential backoff between retries. Invokes reconnect_callback_ on each retry attempt.

Definition at line 60 of file resilient_client.cpp.

    {
        if (is_connected_.load())
        {
            return ok();
        }
 
        for (size_t attempt = 1; attempt <= max_retries_; ++attempt)
        {
            NETWORK_LOG_INFO("[resilient_client] Connection attempt " +
                std::to_string(attempt) + "/" + std::to_string(max_retries_));
 
            // Invoke reconnect callback if set
            if (reconnect_callback_)
            {
                reconnect_callback_(attempt);
            }
 
            // Attempt to connect
            auto result = client_->start_client(host_, port_);
            if (!result.is_err())
            {
                is_connected_.store(true);
                NETWORK_LOG_INFO("[resilient_client] Connected successfully on attempt " +
                    std::to_string(attempt));
                return ok();
            }
 
            NETWORK_LOG_WARN("[resilient_client] Connection attempt " +
                std::to_string(attempt) + " failed: " + result.error().message);
 
            // Don't sleep after last failed attempt
            if (attempt < max_retries_)
            {
                auto backoff = calculate_backoff(attempt);
                NETWORK_LOG_INFO("[resilient_client] Backing off for " +
                    std::to_string(backoff.count()) + "ms");
                std::this_thread::sleep_for(backoff);
            }
        }
 
        return error_void(
            error_codes::network_system::connection_failed,
            "Failed to connect after " + std::to_string(max_retries_) + " attempts",
            "resilient_client::connect",
            "Host: " + host_ + ", Port: " + std::to_string(port_)
        );
    }

References kcenon::network::error_codes::network_system::connection_failed, kcenon::network::error_void(), NETWORK_LOG_INFO, NETWORK_LOG_WARN, and kcenon::network::ok().

Here is the call graph for this function:

◆ disconnect()

auto kcenon::network::utils::resilient_client::disconnect ( ) -> VoidResult

Disconnects from the server.

Returns: Result<void> - Success if disconnected, error otherwise

Definition at line 109 of file resilient_client.cpp.

    {
        if (!is_connected_.load())
        {
            return ok();
        }
 
        auto result = client_->stop_client();
        if (!result.is_err())
        {
            is_connected_.store(false);
 
            // Invoke disconnect callback if set
            if (disconnect_callback_)
            {
                disconnect_callback_();
            }
 
            NETWORK_LOG_INFO("[resilient_client] Disconnected successfully");
        }
        else
        {
            NETWORK_LOG_ERROR("[resilient_client] Failed to disconnect: " +
                result.error().message);
        }
 
        return result;
    }

References NETWORK_LOG_ERROR, NETWORK_LOG_INFO, and kcenon::network::ok().

Referenced by ~resilient_client().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_client()

auto kcenon::network::utils::resilient_client::get_client ( ) const -> std::shared_ptr<core::messaging_client>

nodiscard

Gets the underlying messaging client.

Returns: Shared pointer to the messaging_client

Definition at line 259 of file resilient_client.cpp.

    {
        return client_;
    }

References client_.

◆ is_connected()

auto kcenon::network::utils::resilient_client::is_connected ( ) const -> bool

nodiscardnoexcept

Checks if currently connected to server.

Returns: true if connected, false otherwise

Definition at line 242 of file resilient_client.cpp.

    {
        return is_connected_.load() && client_->is_connected();
    }

References client_, and is_connected_.

◆ reconnect()

auto kcenon::network::utils::resilient_client::reconnect ( ) -> VoidResult

private

Attempts to reconnect with exponential backoff.

Returns: Result<void> - Success if reconnected, error otherwise

Definition at line 265 of file resilient_client.cpp.

    {
        NETWORK_LOG_INFO("[resilient_client] Attempting reconnection");
 
        // Ensure client is disconnected first
        if (client_->is_connected())
        {
            (void)client_->stop_client();
        }
 
        // Try to reconnect with retry logic
        for (size_t attempt = 1; attempt <= max_retries_; ++attempt)
        {
            if (reconnect_callback_)
            {
                reconnect_callback_(attempt);
            }
 
            auto result = client_->start_client(host_, port_);
            if (!result.is_err())
            {
                is_connected_.store(true);
                NETWORK_LOG_INFO("[resilient_client] Reconnected successfully on attempt " +
                    std::to_string(attempt));
                return ok();
            }
 
            NETWORK_LOG_WARN("[resilient_client] Reconnection attempt " +
                std::to_string(attempt) + " failed: " + result.error().message);
 
            if (attempt < max_retries_)
            {
                auto backoff = calculate_backoff(attempt);
                std::this_thread::sleep_for(backoff);
            }
        }
 
        return error_void(
            error_codes::network_system::connection_failed,
            "Failed to reconnect after " + std::to_string(max_retries_) + " attempts",
            "resilient_client::reconnect",
            "Host: " + host_ + ", Port: " + std::to_string(port_)
        );
    }

References kcenon::network::error_codes::network_system::connection_failed, kcenon::network::error_void(), NETWORK_LOG_INFO, NETWORK_LOG_WARN, and kcenon::network::ok().

Here is the call graph for this function:

◆ send_with_retry()

auto kcenon::network::utils::resilient_client::send_with_retry ( std::vector< uint8_t > && data ) -> VoidResult

Sends data with automatic reconnection on failure.

Parameters

data	Data to send (moved for efficiency)

Returns: Result<void> - Success if sent, error after all retries exhausted

If connection is lost, automatically attempts to reconnect before retrying the send operation.

Definition at line 138 of file resilient_client.cpp.

    {
#ifdef WITH_COMMON_SYSTEM
        // Check circuit breaker first
        if (!circuit_breaker_->allow_request())
        {
            NETWORK_LOG_WARN("[resilient_client] Circuit breaker is open, failing fast");
            return error_void(
                kcenon::network::error_codes_ext::network_system::circuit_open,
                "Circuit breaker is open",
                "resilient_client::send_with_retry",
                "Circuit state: " + common::resilience::to_string(circuit_breaker_->get_state())
            );
        }
#endif
 
        // Keep a copy of the data for retries
        auto data_copy = data;
 
        for (size_t attempt = 1; attempt <= max_retries_; ++attempt)
        {
            // Check if connected
            if (!is_connected_.load() || !client_->is_connected())
            {
                NETWORK_LOG_WARN("[resilient_client] Not connected, attempting reconnection");
 
                // Attempt to reconnect
                auto reconnect_result = reconnect();
                if (reconnect_result.is_err())
                {
                    NETWORK_LOG_ERROR("[resilient_client] Reconnection failed: " +
                        reconnect_result.error().message);
 
#ifdef WITH_COMMON_SYSTEM
                    // Record failure to circuit breaker
                    circuit_breaker_->record_failure();
#endif
 
                    // Exponential backoff before next retry
                    if (attempt < max_retries_)
                    {
                        auto backoff = calculate_backoff(attempt);
                        NETWORK_LOG_INFO("[resilient_client] Backing off for " +
                            std::to_string(backoff.count()) + "ms");
                        std::this_thread::sleep_for(backoff);
                    }
                    continue;
                }
            }
 
            // Try to send
            std::vector<uint8_t> send_data = data_copy;  // Make a copy for this attempt
            auto result = client_->send_packet(std::move(send_data));
 
            if (!result.is_err())
            {
#ifdef WITH_COMMON_SYSTEM
                // Record success to circuit breaker
                circuit_breaker_->record_success();
#endif
 
                NETWORK_LOG_DEBUG("[resilient_client] Sent " +
                    std::to_string(data_copy.size()) + " bytes successfully");
                return ok();
            }
 
            NETWORK_LOG_WARN("[resilient_client] Send attempt " +
                std::to_string(attempt) + " failed: " + result.error().message);
 
#ifdef WITH_COMMON_SYSTEM
            // Record failure to circuit breaker
            circuit_breaker_->record_failure();
#endif
 
            // Mark as disconnected if send failed
            is_connected_.store(false);
 
            // Disconnect the client
            (void)client_->stop_client();
 
            // Invoke disconnect callback if set
            if (disconnect_callback_)
            {
                disconnect_callback_();
            }
 
            // Don't sleep after last failed attempt
            if (attempt < max_retries_)
            {
                auto backoff = calculate_backoff(attempt);
                NETWORK_LOG_INFO("[resilient_client] Backing off for " +
                    std::to_string(backoff.count()) + "ms");
                std::this_thread::sleep_for(backoff);
            }
        }
 
        return error_void(
            error_codes::network_system::send_failed,
            "Failed to send after " + std::to_string(max_retries_) + " attempts",
            "resilient_client::send_with_retry",
            "Data size: " + std::to_string(data_copy.size()) + " bytes"
        );
    }

References kcenon::network::error_codes_ext::network_system::circuit_open, kcenon::network::error_void(), NETWORK_LOG_DEBUG, NETWORK_LOG_ERROR, NETWORK_LOG_INFO, NETWORK_LOG_WARN, kcenon::network::ok(), and kcenon::network::error_codes::network_system::send_failed.

Here is the call graph for this function:

◆ set_disconnect_callback()

auto kcenon::network::utils::resilient_client::set_disconnect_callback ( std::function< void()> callback ) -> void

Sets callback for connection loss events.

Parameters

callback Function called when connection is lost

Definition at line 253 of file resilient_client.cpp.

    {
        disconnect_callback_ = std::move(callback);
    }

◆ set_reconnect_callback()

auto kcenon::network::utils::resilient_client::set_reconnect_callback ( std::function< void(size_t attempt)> callback ) -> void

Sets callback for reconnection events.

Parameters

callback Function called on each reconnection attempt

The callback receives the current attempt number (1-based).

Definition at line 247 of file resilient_client.cpp.

    {
        reconnect_callback_ = std::move(callback);
    }

Member Data Documentation

◆ client_

std::shared_ptr<core::messaging_client> kcenon::network::utils::resilient_client::client_

private

Underlying client

Definition at line 180 of file resilient_client.h.

Referenced by get_client(), is_connected(), and resilient_client().

◆ disconnect_callback_

std::function<void()> kcenon::network::utils::resilient_client::disconnect_callback_

private

Disconnection callback

Definition at line 190 of file resilient_client.h.

◆ host_

std::string kcenon::network::utils::resilient_client::host_

private

Server hostname

Definition at line 182 of file resilient_client.h.

◆ initial_backoff_

std::chrono::milliseconds kcenon::network::utils::resilient_client::initial_backoff_

private

Initial backoff duration

Definition at line 185 of file resilient_client.h.

◆ is_connected_

std::atomic<bool> kcenon::network::utils::resilient_client::is_connected_ {false}

private

Connection state

Definition at line 187 of file resilient_client.h.

187{false};

Referenced by is_connected(), and ~resilient_client().

◆ max_retries_

size_t kcenon::network::utils::resilient_client::max_retries_

private

Maximum retry attempts

Definition at line 184 of file resilient_client.h.

◆ port_

unsigned short kcenon::network::utils::resilient_client::port_

private

Server port

Definition at line 183 of file resilient_client.h.

◆ reconnect_callback_

std::function<void(size_t)> kcenon::network::utils::resilient_client::reconnect_callback_

private

Reconnection callback

Definition at line 189 of file resilient_client.h.

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

src/internal/utils/resilient_client.h
src/internal/utils/resilient_client.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Thread Safety

Key Features

Circuit Breaker Integration

Usage Example

Constructor & Destructor Documentation

◆ resilient_client()

◆ ~resilient_client()

Member Function Documentation

◆ calculate_backoff()

◆ connect()

◆ disconnect()

◆ get_client()

◆ is_connected()

◆ reconnect()

◆ send_with_retry()

◆ set_disconnect_callback()

◆ set_reconnect_callback()

Member Data Documentation

◆ client_

◆ disconnect_callback_

◆ host_

◆ initial_backoff_

◆ is_connected_

◆ max_retries_

◆ port_

◆ reconnect_callback_