kcenon::network::internal::secure_tcp_socket Class Reference

A lightweight wrapper around asio::ssl::stream<asio::ip::tcp::socket>, enabling asynchronous TLS/SSL encrypted read and write operations. More...

#include <secure_tcp_socket.h>

Inheritance diagram for kcenon::network::internal::secure_tcp_socket:

Collaboration diagram for kcenon::network::internal::secure_tcp_socket:

Public Types
using	ssl_socket = asio::ssl::stream<asio::ip::tcp::socket>

Public Member Functions
	secure_tcp_socket (asio::ip::tcp::socket socket, asio::ssl::context &ssl_context)
	Constructs a secure_tcp_socket by taking ownership of a moved socket and SSL context.
	~secure_tcp_socket ()=default
	Default destructor (no special cleanup needed).
auto	async_handshake (asio::ssl::stream_base::handshake_type type, std::function< void(std::error_code)> handler) -> void
	Performs asynchronous SSL handshake.
auto	set_receive_callback (std::function< void(const std::vector< uint8_t > &)> callback) -> void
	Sets a callback to receive inbound data chunks.
auto	set_receive_callback_view (std::function< void(std::span< const uint8_t >)> callback) -> void
	Sets a zero-copy callback to receive inbound data as a view.
auto	set_error_callback (std::function< void(std::error_code)> callback) -> void
	Sets a callback to handle socket errors (e.g., read/write failures).
auto	start_read () -> void
	Begins the continuous asynchronous read loop.
auto	async_send (std::vector< uint8_t > &&data, std::function< void(std::error_code, std::size_t)> handler) -> void
	Initiates an asynchronous write of the given data buffer with encryption.
auto	stream () -> ssl_socket &
	Provides direct access to the underlying SSL stream.
auto	socket () -> ssl_socket::lowest_layer_type &
	Provides access to the underlying TCP socket.
auto	stop_read () -> void
	Stops the read loop to prevent further async operations.
auto	close () -> void
	Safely closes the socket and stops all async operations.
auto	is_closed () const -> bool
	Checks if the socket has been closed.

Private Types
using	receive_callback_t = std::function<void(const std::vector<uint8_t>&)>
	Callback type aliases for lock-free storage.
using	receive_callback_view_t = std::function<void(std::span<const uint8_t>)>
using	error_callback_t = std::function<void(std::error_code)>

Private Member Functions
auto	do_read () -> void
	Internal function to handle the read logic with async_read_some().

Private Attributes
ssl_socket	ssl_stream_
std::array< uint8_t, 4096 >	read_buffer_
std::shared_ptr< receive_callback_t >	receive_callback_
std::shared_ptr< receive_callback_view_t >	receive_callback_view_
std::shared_ptr< error_callback_t >	error_callback_
std::mutex	callback_mutex_
std::atomic< bool >	is_reading_ {false}
std::atomic< bool >	is_closed_ {false}

Detailed Description

A lightweight wrapper around asio::ssl::stream<asio::ip::tcp::socket>, enabling asynchronous TLS/SSL encrypted read and write operations.

Key Features

• Maintains a ssl_stream_ (from ASIO SSL) for secure TCP communication.
• Performs SSL handshake before data transmission.
• Exposes set_receive_callback() to handle inbound encrypted data and set_error_callback() for error handling.
• start_read() begins an ongoing loop of async_read_some().
• async_send() performs an async_write of a given data buffer with encryption.

Thread Safety

• All public methods are thread-safe. Callback registration is protected by callback_mutex_.
• ASIO operations are serialized through the io_context, ensuring read_buffer_ is only accessed by one async operation at a time.
• The provided callbacks will be invoked on an ASIO worker thread; ensure that your callback logic is thread-safe if it shares data.

Definition at line 46 of file secure_tcp_socket.h.

Member Typedef Documentation

error_callback_t

using kcenon::network::internal::secure_tcp_socket::error_callback_t = std::function<void(std::error_code)>

private

Definition at line 217 of file secure_tcp_socket.h.

receive_callback_t

using kcenon::network::internal::secure_tcp_socket::receive_callback_t = std::function<void(const std::vector<uint8_t>&)>

private

Callback type aliases for lock-free storage.

Definition at line 215 of file secure_tcp_socket.h.

receive_callback_view_t

using kcenon::network::internal::secure_tcp_socket::receive_callback_view_t = std::function<void(std::span<const uint8_t>)>

private

Definition at line 216 of file secure_tcp_socket.h.

ssl_socket

using kcenon::network::internal::secure_tcp_socket::ssl_socket = asio::ssl::stream<asio::ip::tcp::socket>

Definition at line 49 of file secure_tcp_socket.h.

Constructor & Destructor Documentation

secure_tcp_socket()

kcenon::network::internal::secure_tcp_socket::secure_tcp_socket	(	asio::ip::tcp::socket	socket,
		asio::ssl::context &	ssl_context )

Constructs a secure_tcp_socket by taking ownership of a moved socket and SSL context.

Parameters

socket	An asio::ip::tcp::socket that must be open/connected or at least valid.
ssl_context	SSL context for encryption settings

After construction, you must call async_handshake() before using the socket for data transmission.

Definition at line 14 of file secure_tcp_socket.cpp.

        : ssl_stream_(std::move(socket), ssl_context)
    {
    }

~secure_tcp_socket()

kcenon::network::internal::secure_tcp_socket::~secure_tcp_socket ( )

default

Default destructor (no special cleanup needed).

Member Function Documentation

async_handshake()

auto kcenon::network::internal::secure_tcp_socket::async_handshake	(	asio::ssl::stream_base::handshake_type	type,
		std::function< void(std::error_code)>	handler ) -> void

Performs asynchronous SSL handshake.

Parameters

type	Handshake type (client or server)
handler	Completion handler with signature void(std::error_code)

Must be called before start_read() or async_send().

Definition at line 20 of file secure_tcp_socket.cpp.

    {
        auto self = shared_from_this();
        ssl_stream_.async_handshake(
            type,
            [handler = std::move(handler), self](std::error_code ec)
            {
                if constexpr (std::is_invocable_v<decltype(handler), std::error_code>)
                {
                    if (handler)
                    {
                        handler(ec);
                    }
                }
            });
    }

async_send()

auto kcenon::network::internal::secure_tcp_socket::async_send	(	std::vector< uint8_t > &&	data,
		std::function< void(std::error_code, std::size_t)>	handler ) -> void

Initiates an asynchronous write of the given data buffer with encryption.

Parameters

data	The buffer to send over TLS (moved for efficiency).
handler	A completion handler with signature void(std::error_code, std::size_t) that is invoked upon success or failure.

The handler receives:

• ec : the std::error_code from the write operation,
• bytes_transferred : how many bytes were actually written.

Note

Data is moved (not copied) to avoid memory allocation overhead.

The original vector will be empty after this call.

Definition at line 169 of file secure_tcp_socket.cpp.

    {
        // Check if socket has been closed before starting async operation
        // Use atomic is_closed_ flag to prevent data race with close()
        if (is_closed_.load())
        {
            if (handler)
            {
                handler(asio::error::not_connected, 0);
            }
            return;
        }
 
        auto self = shared_from_this();
        // Move data into shared_ptr for lifetime management
        auto buffer = std::make_shared<std::vector<uint8_t>>(std::move(data));
        asio::async_write(
            ssl_stream_, asio::buffer(*buffer),
            [handler = std::move(handler), self, buffer](std::error_code ec, std::size_t bytes_transferred)
            {
                if constexpr (std::is_invocable_v<decltype(handler), std::error_code, std::size_t>)
                {
                    if (handler)
                    {
                        handler(ec, bytes_transferred);
                    }
                }
            });
    }

close()

auto kcenon::network::internal::secure_tcp_socket::close

(

)

-> void

Safely closes the socket and stops all async operations.

This method atomically sets the closed flag before closing the socket, preventing data races between the close operation and async read operations. Thread-safe with respect to concurrent async operations.

Definition at line 76 of file secure_tcp_socket.cpp.

    {
        // Atomically mark socket as closed before actual close
        // This prevents data races with concurrent async operations
        is_closed_.store(true);
        is_reading_.store(false);
 
        std::error_code ec;
        ssl_stream_.lowest_layer().close(ec);
        // Ignore close errors - socket may already be closed
    }

do_read()

auto kcenon::network::internal::secure_tcp_socket::do_read ( ) -> void

private

Internal function to handle the read logic with async_read_some().

Upon success, it calls receive_callback_ if set, then schedules another read. On error, it calls error_callback_ if available.

Definition at line 93 of file secure_tcp_socket.cpp.

    {
        // Check if reading has been stopped before initiating new async operation
        if (!is_reading_.load())
        {
            return;
        }
 
        // Check if socket has been closed or is no longer open before starting async operation
        // This prevents data races and UBSAN errors from accessing null descriptor_state
        // Both checks are needed: is_closed_ for explicit close() calls, is_open() for ASIO state
        if (is_closed_.load() || !ssl_stream_.lowest_layer().is_open())
        {
            is_reading_.store(false);
            return;
        }
 
        auto self = shared_from_this();
        ssl_stream_.async_read_some(
            asio::buffer(read_buffer_),
            [this, self](std::error_code ec, std::size_t length)
            {
                // Check if reading has been stopped or socket closed at callback time
                // This prevents accessing invalid socket state after close()
                if (!is_reading_.load() || is_closed_.load())
                {
                    return;
                }
 
                if (ec)
                {
                    // On error, invoke the error callback
                    // Lock-free callback access via atomic_load
                    auto error_cb = std::atomic_load(&error_callback_);
                    if (error_cb && *error_cb)
                    {
                        (*error_cb)(ec);
                    }
                    return;
                }
 
                // On success, if length > 0, dispatch to the appropriate callback
                if (length > 0)
                {
                    // Lock-free callback access via atomic_load
                    // Prefer view callback (zero-copy) over vector callback
                    auto view_cb = std::atomic_load(&receive_callback_view_);
                    if (view_cb && *view_cb)
                    {
                        // Zero-copy path: create span view directly into read_buffer_
                        // No std::vector allocation or copy required
                        std::span<const uint8_t> data_view(read_buffer_.data(), length);
                        (*view_cb)(data_view);
                    }
                    else
                    {
                        // Legacy path: allocate and copy into vector for compatibility
                        auto recv_cb = std::atomic_load(&receive_callback_);
                        if (recv_cb && *recv_cb)
                        {
                            std::vector<uint8_t> chunk(read_buffer_.begin(),
                                                       read_buffer_.begin() + length);
                            (*recv_cb)(chunk);
                        }
                    }
                }
 
                // Continue reading only if still active and socket is not closed
                // Use atomic is_closed_ flag to prevent data race with close()
                if (is_reading_.load() && !is_closed_.load())
                {
                    do_read();
                }
            });
    }

is_closed()

auto kcenon::network::internal::secure_tcp_socket::is_closed ( ) const -> bool

nodiscard

Checks if the socket has been closed.

Returns

true if close() has been called on this socket.

Definition at line 88 of file secure_tcp_socket.cpp.

    {
        return is_closed_.load();
    }

References is_closed_.

set_error_callback()

auto kcenon::network::internal::secure_tcp_socket::set_error_callback

(

std::function< void(std::error_code)>

callback

)

-> void

Sets a callback to handle socket errors (e.g., read/write failures).

Parameters

callback

A function with signature void(std::error_code), invoked when any asynchronous operation fails.

If no callback is set, errors are not explicitly handled here (beyond stopping reads).

Definition at line 55 of file secure_tcp_socket.cpp.

    {
        auto new_cb = std::make_shared<error_callback_t>(std::move(callback));
        std::lock_guard<std::mutex> lock(callback_mutex_);
        std::atomic_store(&error_callback_, new_cb);
    }

set_receive_callback()

auto kcenon::network::internal::secure_tcp_socket::set_receive_callback

(

std::function< void(const std::vector< uint8_t > &)>

callback

)

-> void

Sets a callback to receive inbound data chunks.

Parameters

callback

A function with signature void(const std::vector<uint8_t>&), called whenever a chunk of data is successfully read and decrypted.

If no callback is set, received data is effectively discarded.

Note

This is the legacy callback API. For better performance, consider using set_receive_callback_view() instead.

Definition at line 39 of file secure_tcp_socket.cpp.

    {
        auto new_cb = std::make_shared<receive_callback_t>(std::move(callback));
        std::lock_guard<std::mutex> lock(callback_mutex_);
        std::atomic_store(&receive_callback_, new_cb);
    }

set_receive_callback_view()

auto kcenon::network::internal::secure_tcp_socket::set_receive_callback_view

(

std::function< void(std::span< const uint8_t >)>

callback

)

-> void

Sets a zero-copy callback to receive inbound data as a view.

Parameters

callback

A function with signature void(std::span<const uint8_t>), called whenever a chunk of data is successfully read and decrypted.

Zero-Copy Performance

Unlike set_receive_callback(), this callback receives data as a non-owning view directly into the internal read buffer, avoiding per-read std::vector allocations and copies.

Lifetime Contract

• The span is valid only until the callback returns.
• Callers must not store, capture, or use the span after returning from the callback.
• If data must be retained, copy it into your own container within the callback.

Dispatch Priority

• If both view and vector callbacks are set, the view callback takes priority and the vector callback is not invoked.

Example

sock->set_receive_callback_view([](std::span<const uint8_t> data) {
    // Process data directly (zero-copy)
    process_bytes(data.data(), data.size());
    // If you need to keep the data:
    // my_buffer.insert(my_buffer.end(), data.begin(), data.end());
});

Definition at line 47 of file secure_tcp_socket.cpp.

    {
        auto new_cb = std::make_shared<receive_callback_view_t>(std::move(callback));
        std::lock_guard<std::mutex> lock(callback_mutex_);
        std::atomic_store(&receive_callback_view_, new_cb);
    }

socket()

auto kcenon::network::internal::secure_tcp_socket::socket ( ) -> ssl_socket::lowest_layer_type&

inline

Provides access to the underlying TCP socket.

Returns

A reference to the lowest layer socket.

Definition at line 178 of file secure_tcp_socket.h.

        {
            return ssl_stream_.lowest_layer();
        }

References ssl_stream_.

start_read()

auto kcenon::network::internal::secure_tcp_socket::start_read

(

)

-> void

Begins the continuous asynchronous read loop.

Once called, the class repeatedly calls async_read_some(). If an error occurs, on_error() is triggered, stopping further reads.

Definition at line 63 of file secure_tcp_socket.cpp.

    {
        // Set reading flag and kick off the initial read loop
        is_reading_.store(true);
        do_read();
    }

stop_read()

auto kcenon::network::internal::secure_tcp_socket::stop_read

(

)

-> void

Stops the read loop to prevent further async operations.

Definition at line 70 of file secure_tcp_socket.cpp.

    {
        // Stop further read operations
        is_reading_.store(false);
    }

stream()

auto kcenon::network::internal::secure_tcp_socket::stream ( ) -> ssl_socket&

inline

Provides direct access to the underlying SSL stream.

Returns

A reference to the wrapped asio::ssl::stream.

Definition at line 172 of file secure_tcp_socket.h.

{ return ssl_stream_; }

References ssl_stream_.

Member Data Documentation

callback_mutex_

std::mutex kcenon::network::internal::secure_tcp_socket::callback_mutex_

private

Protects callback registration only.

Definition at line 232 of file secure_tcp_socket.h.

error_callback_

std::shared_ptr<error_callback_t> kcenon::network::internal::secure_tcp_socket::error_callback_

private

Definition at line 230 of file secure_tcp_socket.h.

is_closed_

std::atomic<bool> kcenon::network::internal::secure_tcp_socket::is_closed_ {false}

private

Flag to indicate socket is closed.

Definition at line 235 of file secure_tcp_socket.h.

{false};  

Referenced by is_closed().

is_reading_

std::atomic<bool> kcenon::network::internal::secure_tcp_socket::is_reading_ {false}

private

Flag to prevent read after stop.

Definition at line 234 of file secure_tcp_socket.h.

{false}; 

read_buffer_

std::array<uint8_t, 4096> kcenon::network::internal::secure_tcp_socket::read_buffer_

private

Buffer for receiving data in do_read().

Definition at line 222 of file secure_tcp_socket.h.

receive_callback_

std::shared_ptr<receive_callback_t> kcenon::network::internal::secure_tcp_socket::receive_callback_

private

Lock-free callback storage using shared_ptr + atomic operations. This eliminates mutex contention on the receive hot path.

Definition at line 228 of file secure_tcp_socket.h.

receive_callback_view_

std::shared_ptr<receive_callback_view_t> kcenon::network::internal::secure_tcp_socket::receive_callback_view_

private

Definition at line 229 of file secure_tcp_socket.h.

ssl_stream_

ssl_socket kcenon::network::internal::secure_tcp_socket::ssl_stream_

private

The underlying ASIO SSL stream.

Definition at line 219 of file secure_tcp_socket.h.

Referenced by socket(), and stream().

---

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

• src/internal/tcp/secure_tcp_socket.h
• src/internal/secure_tcp_socket.cpp