kcenon::network::internal::websocket_socket Class Reference

WebSocket framing layer built on top of tcp_socket. More...

#include <websocket_socket.h>

Inheritance diagram for kcenon::network::internal::websocket_socket:

Collaboration diagram for kcenon::network::internal::websocket_socket:

Public Member Functions
	websocket_socket (std::shared_ptr< tcp_socket > socket, bool is_client)
	Constructs a websocket_socket wrapping an existing tcp_socket.
	~websocket_socket ()
	Destructor.
auto	async_handshake (const std::string &host, const std::string &path, uint16_t port, std::function< void(std::error_code)> handler) -> void
	Performs WebSocket client handshake (RFC 6455 Section 4.1).
auto	async_accept (std::function< void(std::error_code)> handler) -> void
	Accepts WebSocket server handshake (RFC 6455 Section 4.2).
auto	start_read () -> void
	Starts reading WebSocket frames from the underlying socket.
auto	async_send_text (std::string &&message, std::function< void(std::error_code, std::size_t)> handler) -> VoidResult
	Sends a text message (UTF-8 encoded).
auto	async_send_binary (std::vector< uint8_t > &&data, std::function< void(std::error_code, std::size_t)> handler) -> VoidResult
	Sends a binary message.
auto	async_send_ping (std::vector< uint8_t > payload, std::function< void(std::error_code)> handler) -> void
	Sends a ping control frame.
auto	async_close (ws_close_code code, const std::string &reason, std::function< void(std::error_code)> handler) -> void
	Initiates the WebSocket closing handshake.
auto	state () const -> ws_state
	Gets the current connection state.
auto	is_open () const -> bool
	Checks if the connection is open and ready.
auto	set_message_callback (std::function< void(const ws_message &)> callback) -> void
	Sets the callback for received messages.
auto	set_ping_callback (std::function< void(const std::vector< uint8_t > &)> callback) -> void
	Sets the callback for received ping frames.
auto	set_pong_callback (std::function< void(const std::vector< uint8_t > &)> callback) -> void
	Sets the callback for received pong frames.
auto	set_close_callback (std::function< void(ws_close_code, const std::string &)> callback) -> void
	Sets the callback for received close frames.
auto	set_error_callback (std::function< void(std::error_code)> callback) -> void
	Sets the callback for errors.

Private Member Functions
auto	on_tcp_receive (std::span< const uint8_t > data) -> void
	Called by tcp_socket when data is received.
auto	on_tcp_error (std::error_code ec) -> void
	Called by tcp_socket when an error occurs.
auto	handle_protocol_message (const ws_message &msg) -> void
	Handles a decoded message from the protocol layer.
auto	handle_protocol_ping (const std::vector< uint8_t > &payload) -> void
	Handles a ping frame from the protocol layer.
auto	handle_protocol_pong (const std::vector< uint8_t > &payload) -> void
	Handles a pong frame from the protocol layer.
auto	handle_protocol_close (ws_close_code code, const std::string &reason) -> void
	Handles a close frame from the protocol layer.

Private Attributes
std::shared_ptr< tcp_socket >	tcp_socket_
websocket_protocol	protocol_
std::atomic< ws_state >	state_ {ws_state::connecting}
std::mutex	callback_mutex_
std::function< void(const ws_message &)>	message_callback_
std::function< void(const std::vector< uint8_t > &)>	ping_callback_
std::function< void(const std::vector< uint8_t > &)>	pong_callback_
std::function< void(ws_close_code, const std::string &)>	close_callback_
std::function< void(std::error_code)>	error_callback_

Detailed Description

WebSocket framing layer built on top of tcp_socket.

This class wraps an existing tcp_socket and provides WebSocket protocol framing. The underlying tcp_socket handles all transport I/O operations, while websocket_socket handles:

• WebSocket handshake (client and server)
• Frame encoding/decoding via websocket_protocol
• Message fragmentation and reassembly
• Connection state management
• Ping/pong keepalive
• Close handshake

Design rationale:

• Reuses tcp_socket infrastructure (no I/O duplication)
• Maintains consistency with existing network_system patterns
• Separates concerns: tcp_socket = transport, websocket_socket = framing

Definition at line 59 of file websocket_socket.h.

Constructor & Destructor Documentation

websocket_socket()

kcenon::network::internal::websocket_socket::websocket_socket	(	std::shared_ptr< tcp_socket >	socket,
		bool	is_client )

Constructs a websocket_socket wrapping an existing tcp_socket.

Parameters

socket	The underlying TCP socket (must be connected)
is_client	True if this is a client endpoint (applies masking)

Definition at line 16 of file websocket_socket.cpp.

        : tcp_socket_(std::move(socket))
        , protocol_(is_client)
    {
        // Set up WebSocket protocol callbacks
        protocol_.set_message_callback(
            [this](const ws_message& msg) { handle_protocol_message(msg); });
 
        protocol_.set_ping_callback([this](const std::vector<uint8_t>& payload)
                                    {
                                        // RFC 6455: Automatically respond to Ping with Pong
                                        auto pong_frame = protocol_.create_pong(
                                            std::vector<uint8_t>(payload));
                                        tcp_socket_->async_send(
                                            std::move(pong_frame),
                                            [](std::error_code, std::size_t) {});
 
                                        handle_protocol_ping(payload);
                                    });
 
        protocol_.set_pong_callback([this](const std::vector<uint8_t>& payload)
                                    { handle_protocol_pong(payload); });
 
        protocol_.set_close_callback([this](ws_close_code code, const std::string& reason)
                                     { handle_protocol_close(code, reason); });
 
        // Set up TCP socket callbacks to feed data into protocol layer
        // Use zero-copy span callback to avoid per-read vector allocation
        tcp_socket_->set_receive_callback_view(
            [this](std::span<const uint8_t> data) { on_tcp_receive(data); });
 
        tcp_socket_->set_error_callback(
            [this](std::error_code ec) { on_tcp_error(ec); });
    }

References kcenon::network::internal::websocket_protocol::create_pong(), handle_protocol_close(), handle_protocol_message(), handle_protocol_ping(), handle_protocol_pong(), on_tcp_error(), on_tcp_receive(), protocol_, kcenon::network::internal::websocket_protocol::set_close_callback(), kcenon::network::internal::websocket_protocol::set_message_callback(), kcenon::network::internal::websocket_protocol::set_ping_callback(), kcenon::network::internal::websocket_protocol::set_pong_callback(), and tcp_socket_.

Here is the call graph for this function:

~websocket_socket()

kcenon::network::internal::websocket_socket::~websocket_socket

(

)

Destructor.

Stops reading and cleans up resources.

Definition at line 52 of file websocket_socket.cpp.

    {
        // Cleanup resources if needed
    }

Member Function Documentation

async_accept()

auto kcenon::network::internal::websocket_socket::async_accept

(

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

handler

)

-> void

Accepts WebSocket server handshake (RFC 6455 Section 4.2).

Reads the client's HTTP/1.1 Upgrade request and sends the acceptance response. The handler is called with success/failure status.

Parameters

handler

Callback invoked with handshake result

Definition at line 124 of file websocket_socket.cpp.

    {
        // Set up temporary callback to receive handshake request
        // Use span callback for zero-copy during handshake
        tcp_socket_->set_receive_callback_view(
            [this, handler](std::span<const uint8_t> data)
            {
                // Convert request to string
                std::string request(data.begin(), data.end());
 
                // Parse client request
                auto result = websocket_handshake::parse_client_request(request);
 
                if (!result.success)
                {
                    handler(std::make_error_code(std::errc::protocol_error));
                    return;
                }
 
                // Extract client key (headers are stored lowercase by parse_headers)
                auto it = result.headers.find("sec-websocket-key");
                if (it == result.headers.end())
                {
                    handler(std::make_error_code(std::errc::protocol_error));
                    return;
                }
 
                std::string client_key = it->second;
 
                // Generate server response
                auto response = websocket_handshake::create_server_response(client_key);
                std::vector<uint8_t> response_data(response.begin(), response.end());
 
                // Send response
                tcp_socket_->async_send(
                    std::move(response_data),
                    [this, handler](std::error_code ec, std::size_t)
                    {
                        if (ec)
                        {
                            handler(ec);
                            return;
                        }
 
                        // Handshake successful, update state
                        state_ = ws_state::open;
 
                        // Restore normal receive callback
                        tcp_socket_->set_receive_callback_view(
                            [this](std::span<const uint8_t> data)
                            { on_tcp_receive(data); });
 
                        handler(std::error_code{});
                    });
            });
 
        // Start reading request
        tcp_socket_->start_read();
    }

References kcenon::network::internal::websocket_handshake::create_server_response(), kcenon::network::internal::open, and kcenon::network::internal::websocket_handshake::parse_client_request().

Here is the call graph for this function:

async_close()

auto kcenon::network::internal::websocket_socket::async_close	(	ws_close_code	code,
		const std::string &	reason,
		std::function< void(std::error_code)>	handler ) -> void

Initiates the WebSocket closing handshake.

Sends a close frame with the specified status code and reason. The connection state transitions to closing.

Parameters

code	The close status code (RFC 6455 Section 7.4)
reason	Optional human-readable reason (UTF-8, max ~123 bytes)
handler	Callback invoked when close frame is sent

Definition at line 249 of file websocket_socket.cpp.

    {
        // Update state to closing
        state_ = ws_state::closing;
 
        // Encode close frame
        auto frame_data = protocol_.create_close(code, std::string(reason));
 
        // Send via underlying tcp_socket
        tcp_socket_->async_send(std::move(frame_data),
                                [this, handler](std::error_code ec, std::size_t)
                                {
                                    if (ec)
                                    {
                                        state_ = ws_state::closed;
                                        if (handler)
                                        {
                                            handler(ec);
                                        }
                                        return;
                                    }
 
                                    // Close handshake initiated successfully
                                    if (handler)
                                    {
                                        handler(std::error_code{});
                                    }
                                });
    }

References kcenon::network::internal::closed, and kcenon::network::internal::closing.

async_handshake()

auto kcenon::network::internal::websocket_socket::async_handshake	(	const std::string &	host,
		const std::string &	path,
		uint16_t	port,
		std::function< void(std::error_code)>	handler ) -> void

Performs WebSocket client handshake (RFC 6455 Section 4.1).

Sends an HTTP/1.1 Upgrade request and validates the server response. The handler is called with success/failure status.

Parameters

host	The server hostname (for Host header)
path	The request path (e.g., "/chat")
port	The server port (for Host header)
handler	Callback invoked with handshake result

Definition at line 57 of file websocket_socket.cpp.

    {
        // Generate client handshake request
        auto handshake_request =
            websocket_handshake::create_client_handshake(host, path, port);
 
        // Store the expected key for validation
        auto key_start = handshake_request.find("Sec-WebSocket-Key: ");
        std::string client_key;
        if (key_start != std::string::npos)
        {
            key_start += 19; // Length of "Sec-WebSocket-Key: "
            auto key_end = handshake_request.find("\r\n", key_start);
            client_key = handshake_request.substr(key_start, key_end - key_start);
        }
 
        // Send handshake request
        std::vector<uint8_t> request_data(handshake_request.begin(),
                                          handshake_request.end());
 
        tcp_socket_->async_send(
            std::move(request_data),
            [this, client_key, handler](std::error_code ec, std::size_t)
            {
                if (ec)
                {
                    handler(ec);
                    return;
                }
 
                // Set up temporary callback to receive handshake response
                // Use span callback for zero-copy during handshake
                tcp_socket_->set_receive_callback_view(
                    [this, client_key, handler](std::span<const uint8_t> data)
                    {
                        // Convert response to string
                        std::string response(data.begin(), data.end());
 
                        // Validate server response
                        auto result = websocket_handshake::validate_server_response(
                            response, client_key);
 
                        if (!result.success)
                        {
                            handler(std::make_error_code(std::errc::protocol_error));
                            return;
                        }
 
                        // Handshake successful, update state
                        state_ = ws_state::open;
 
                        // Restore normal receive callback
                        tcp_socket_->set_receive_callback_view(
                            [this](std::span<const uint8_t> data)
                            { on_tcp_receive(data); });
 
                        handler(std::error_code{});
                    });
 
                // Start reading response
                tcp_socket_->start_read();
            });
    }

References kcenon::network::internal::websocket_handshake::create_client_handshake(), kcenon::network::internal::open, and kcenon::network::internal::websocket_handshake::validate_server_response().

Here is the call graph for this function:

async_send_binary()

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

Sends a binary message.

Uses move semantics for zero-copy operation. The data is encoded as a WebSocket binary frame.

Parameters

data	The binary data to send
handler	Callback invoked with send result

Returns

VoidResult indicating success

Definition at line 212 of file websocket_socket.cpp.

    {
        if (state_ != ws_state::open)
        {
            return error_void(error_codes::network_system::connection_closed,
                              "WebSocket connection not open");
        }
 
        // Encode binary message into WebSocket frame
        auto frame_data = protocol_.create_binary_message(std::move(data));
 
        // Send via underlying tcp_socket
        tcp_socket_->async_send(std::move(frame_data), std::move(handler));
 
        return ok();
    }

References kcenon::network::error_codes::network_system::connection_closed, kcenon::network::error_void(), kcenon::network::ok(), and kcenon::network::internal::open.

Here is the call graph for this function:

async_send_ping()

auto kcenon::network::internal::websocket_socket::async_send_ping	(	std::vector< uint8_t >	payload,
		std::function< void(std::error_code)>	handler ) -> void

Sends a ping control frame.

Ping frames are used to check connection liveness. The peer should respond with a pong frame.

Parameters

payload	Optional payload data (max 125 bytes)
handler	Callback invoked with send result

Definition at line 231 of file websocket_socket.cpp.

    {
        // Encode ping frame
        auto frame_data = protocol_.create_ping(std::move(payload));
 
        // Send via underlying tcp_socket
        tcp_socket_->async_send(std::move(frame_data),
                                [handler](std::error_code ec, std::size_t)
                                {
                                    if (handler)
                                    {
                                        handler(ec);
                                    }
                                });
    }

async_send_text()

auto kcenon::network::internal::websocket_socket::async_send_text	(	std::string &&	message,
		std::function< void(std::error_code, std::size_t)>	handler ) -> VoidResult

Sends a text message (UTF-8 encoded).

Uses move semantics for zero-copy operation. The message is validated for UTF-8 encoding and encoded as a WebSocket text frame.

Parameters

message	The text message to send
handler	Callback invoked with send result

Returns

VoidResult indicating validation success

Definition at line 187 of file websocket_socket.cpp.

    {
        if (state_ != ws_state::open)
        {
            return error_void(error_codes::network_system::connection_closed,
                              "WebSocket connection not open");
        }
 
        // Encode text message into WebSocket frame
        auto frame_data = protocol_.create_text_message(std::move(message));
 
        if (frame_data.empty())
        {
            return error_void(error_codes::common_errors::invalid_argument,
                              "Invalid UTF-8 in text message");
        }
 
        // Send via underlying tcp_socket
        tcp_socket_->async_send(std::move(frame_data), std::move(handler));
 
        return ok();
    }

References kcenon::network::error_codes::network_system::connection_closed, kcenon::network::error_void(), kcenon::network::error_codes::common_errors::invalid_argument, kcenon::network::message, kcenon::network::ok(), and kcenon::network::internal::open.

Here is the call graph for this function:

handle_protocol_close()

auto kcenon::network::internal::websocket_socket::handle_protocol_close ( ws_close_code code, const std::string & reason ) -> void

private

Handles a close frame from the protocol layer.

Updates connection state and invokes the close callback.

Parameters

code	The close status code
reason	The close reason string

Definition at line 371 of file websocket_socket.cpp.

    {
        // Update state to closed
        state_ = ws_state::closed;
 
        std::lock_guard<std::mutex> lock(callback_mutex_);
        if (close_callback_)
        {
            close_callback_(code, reason);
        }
    }

References kcenon::network::internal::closed.

Referenced by websocket_socket().

Here is the caller graph for this function:

handle_protocol_message()

auto kcenon::network::internal::websocket_socket::handle_protocol_message ( const ws_message & msg ) -> void

private

Handles a decoded message from the protocol layer.

Invokes the message callback.

Parameters

msg	The decoded message

Definition at line 342 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        if (message_callback_)
        {
            message_callback_(msg);
        }
    }

Referenced by websocket_socket().

Here is the caller graph for this function:

handle_protocol_ping()

auto kcenon::network::internal::websocket_socket::handle_protocol_ping ( const std::vector< uint8_t > & payload ) -> void

private

Handles a ping frame from the protocol layer.

Invokes the ping callback (application may send pong).

Parameters

payload

The ping payload

Definition at line 351 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        if (ping_callback_)
        {
            ping_callback_(payload);
        }
    }

Referenced by websocket_socket().

Here is the caller graph for this function:

handle_protocol_pong()

auto kcenon::network::internal::websocket_socket::handle_protocol_pong ( const std::vector< uint8_t > & payload ) -> void

private

Handles a pong frame from the protocol layer.

Invokes the pong callback.

Parameters

payload

The pong payload

Definition at line 361 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        if (pong_callback_)
        {
            pong_callback_(payload);
        }
    }

Referenced by websocket_socket().

Here is the caller graph for this function:

is_open()

auto kcenon::network::internal::websocket_socket::is_open

(

)

const -> bool

Checks if the connection is open and ready.

Returns

True if state is ws_state::open

Definition at line 283 of file websocket_socket.cpp.

    {
        return state_.load() == ws_state::open;
    }

References kcenon::network::internal::open, and state_.

on_tcp_error()

auto kcenon::network::internal::websocket_socket::on_tcp_error ( std::error_code ec ) -> void

private

Called by tcp_socket when an error occurs.

Propagates the error to the application.

Parameters

ec	The error code

Definition at line 329 of file websocket_socket.cpp.

    {
        // Update state to closed
        state_ = ws_state::closed;
 
        // Propagate error to application
        std::lock_guard<std::mutex> lock(callback_mutex_);
        if (error_callback_)
        {
            error_callback_(ec);
        }
    }

References kcenon::network::internal::closed.

Referenced by websocket_socket().

Here is the caller graph for this function:

on_tcp_receive()

auto kcenon::network::internal::websocket_socket::on_tcp_receive ( std::span< const uint8_t > data ) -> void

private

Called by tcp_socket when data is received.

Feeds the data into the WebSocket protocol decoder. Uses zero-copy span view from tcp_socket's read buffer.

Parameters

data	The received raw bytes as a view

Definition at line 323 of file websocket_socket.cpp.

    {
        // Feed raw TCP data into WebSocket protocol decoder (zero-copy view)
        protocol_.process_data(data);
    }

Referenced by websocket_socket().

Here is the caller graph for this function:

set_close_callback()

auto kcenon::network::internal::websocket_socket::set_close_callback

(

std::function< void(ws_close_code, const std::string &)>

callback

)

-> void

Sets the callback for received close frames.

This callback is invoked when a close frame is received. The application should respond with a close frame if it hasn't already.

Parameters

callback

The callback function

Definition at line 309 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        close_callback_ = std::move(callback);
    }

set_error_callback()

auto kcenon::network::internal::websocket_socket::set_error_callback

(

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

callback

)

-> void

Sets the callback for errors.

This callback is invoked when an error occurs on the underlying socket.

Parameters

callback

The callback function

Definition at line 316 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        error_callback_ = std::move(callback);
    }

set_message_callback()

auto kcenon::network::internal::websocket_socket::set_message_callback

(

std::function< void(const ws_message &)>

callback

)

-> void

Sets the callback for received messages.

This callback is invoked when a complete text or binary message has been received and reassembled.

Parameters

callback

The callback function

Definition at line 288 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        message_callback_ = std::move(callback);
    }

set_ping_callback()

auto kcenon::network::internal::websocket_socket::set_ping_callback

(

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

callback

)

-> void

Sets the callback for received ping frames.

This callback is invoked when a ping frame is received. The application may choose to send a pong response.

Parameters

callback

The callback function

Definition at line 295 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        ping_callback_ = std::move(callback);
    }

set_pong_callback()

auto kcenon::network::internal::websocket_socket::set_pong_callback

(

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

callback

)

-> void

Sets the callback for received pong frames.

This callback is invoked when a pong frame is received (typically in response to a ping).

Parameters

callback

The callback function

Definition at line 302 of file websocket_socket.cpp.

    {
        std::lock_guard<std::mutex> lock(callback_mutex_);
        pong_callback_ = std::move(callback);
    }

start_read()

auto kcenon::network::internal::websocket_socket::start_read

(

)

-> void

Starts reading WebSocket frames from the underlying socket.

Must be called after successful handshake to begin receiving messages.

Definition at line 185 of file websocket_socket.cpp.

{ tcp_socket_->start_read(); }

state()

auto kcenon::network::internal::websocket_socket::state

(

)

const -> ws_state

Gets the current connection state.

Returns

The current ws_state

Definition at line 281 of file websocket_socket.cpp.

{ return state_.load(); }

References state_.

Member Data Documentation

callback_mutex_

std::mutex kcenon::network::internal::websocket_socket::callback_mutex_

private

Definition at line 238 of file websocket_socket.h.

close_callback_

std::function<void(ws_close_code, const std::string&)> kcenon::network::internal::websocket_socket::close_callback_

private

Definition at line 242 of file websocket_socket.h.

error_callback_

std::function<void(std::error_code)> kcenon::network::internal::websocket_socket::error_callback_

private

Definition at line 243 of file websocket_socket.h.

message_callback_

std::function<void(const ws_message&)> kcenon::network::internal::websocket_socket::message_callback_

private

Definition at line 239 of file websocket_socket.h.

ping_callback_

std::function<void(const std::vector<uint8_t>&)> kcenon::network::internal::websocket_socket::ping_callback_

private

Definition at line 240 of file websocket_socket.h.

pong_callback_

std::function<void(const std::vector<uint8_t>&)> kcenon::network::internal::websocket_socket::pong_callback_

private

Definition at line 241 of file websocket_socket.h.

protocol_

websocket_protocol kcenon::network::internal::websocket_socket::protocol_

private

Definition at line 234 of file websocket_socket.h.

Referenced by websocket_socket().

state_

std::atomic<ws_state> kcenon::network::internal::websocket_socket::state_ {ws_state::connecting}

private

Definition at line 235 of file websocket_socket.h.

{ws_state::connecting};

Referenced by is_open(), and state().

tcp_socket_

std::shared_ptr<tcp_socket> kcenon::network::internal::websocket_socket::tcp_socket_

private

Definition at line 231 of file websocket_socket.h.

Referenced by websocket_socket().

---

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

• src/internal/websocket/websocket_socket.h
• src/internal/websocket_socket.cpp