WebSocket protocol handler for message processing. More...

#include <websocket_protocol.h>

Collaboration diagram for kcenon::network::internal::websocket_protocol:

Public Member Functions
	websocket_protocol (bool is_client)
	Constructs a WebSocket protocol handler.

auto	process_data (std::span< const uint8_t > data) -> void
	Processes incoming WebSocket data.

auto	create_text_message (std::string &&text) -> std::vector< uint8_t >
	Creates a text message frame.

auto	create_binary_message (std::vector< uint8_t > &&data) -> std::vector< uint8_t >
	Creates a binary message frame.

auto	create_ping (std::vector< uint8_t > &&payload={}) -> std::vector< uint8_t >
	Creates a ping control frame.

auto	create_pong (std::vector< uint8_t > &&payload={}) -> std::vector< uint8_t >
	Creates a pong control frame.

auto	create_close (ws_close_code code, std::string &&reason="") -> std::vector< uint8_t >
	Creates a close control frame.

auto	set_message_callback (std::function< void(const ws_message &)> callback) -> void
	Sets the callback for data messages.

auto	set_ping_callback (std::function< void(const std::vector< uint8_t > &)> callback) -> void
	Sets the callback for ping frames.

auto	set_pong_callback (std::function< void(const std::vector< uint8_t > &)> callback) -> void
	Sets the callback for pong frames.

auto	set_close_callback (std::function< void(ws_close_code, const std::string &)> callback) -> void
	Sets the callback for close frames.

Private Member Functions
auto	process_frames () -> void
	Processes incoming frames from the buffer.

auto	handle_data_frame (const ws_frame_header &header, const std::vector< uint8_t > &payload) -> void
	Handles a data frame (text or binary).

auto	handle_control_frame (const ws_frame_header &header, const std::vector< uint8_t > &payload) -> void
	Handles a control frame (ping, pong, close).

auto	handle_ping (const std::vector< uint8_t > &payload) -> void
	Handles a ping frame.

auto	handle_pong (const std::vector< uint8_t > &payload) -> void
	Handles a pong frame.

auto	handle_close (const std::vector< uint8_t > &payload) -> void
	Handles a close frame.

Static Private Member Functions
static auto	is_valid_utf8 (const std::vector< uint8_t > &data) -> bool
	Validates UTF-8 encoding.

Private Attributes
bool	is_client_
	True if client (applies masking)

std::vector< uint8_t >	buffer_
	Incoming data buffer.

std::vector< uint8_t >	fragmented_message_
	Reassembly buffer for fragmented messages.

ws_opcode	fragmented_type_
	Type of fragmented message in progress.

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_

Detailed Description

WebSocket protocol handler for message processing.

This class handles the WebSocket protocol state machine including:

Frame processing and message reassembly
Fragmentation handling
Control frame processing (ping/pong/close)
Message callbacks

Definition at line 82 of file websocket_protocol.h.

Constructor & Destructor Documentation

◆ websocket_protocol()

kcenon::network::internal::websocket_protocol::websocket_protocol ( bool is_client )

explicit

Constructs a WebSocket protocol handler.

Parameters

is_client True if this is a client endpoint (applies masking)

Definition at line 30 of file websocket_protocol.cpp.

        : is_client_(is_client)
        , fragmented_type_(ws_opcode::continuation)
    {
    }

Member Function Documentation

◆ create_binary_message()

auto kcenon::network::internal::websocket_protocol::create_binary_message ( std::vector< uint8_t > && data ) -> std::vector<uint8_t>

Creates a binary message frame.

Encodes the binary data as a WebSocket binary frame. Uses move semantics for zero-copy operation.

Parameters

data	The binary data to send

Returns: Encoded WebSocket frame ready for transmission

Definition at line 269 of file websocket_protocol.cpp.

    {
        return websocket_frame::encode_frame(ws_opcode::binary, std::move(data), true,
                                             is_client_);
    }

References kcenon::network::internal::binary, and kcenon::network::internal::websocket_frame::encode_frame().

Here is the call graph for this function:

◆ create_close()

auto kcenon::network::internal::websocket_protocol::create_close	(	ws_close_code	code,
		std::string &&	reason = "" ) -> std::vector<uint8_t>

Creates a close control frame.

Initiates the WebSocket closing handshake.

Parameters

code	The close status code
reason	Optional human-readable reason (UTF-8)

Returns: Encoded close frame

Definition at line 302 of file websocket_protocol.cpp.

    {
        std::vector<uint8_t> payload;
 
        // Encode close code (network byte order)
        payload.push_back(static_cast<uint8_t>((static_cast<uint16_t>(code) >> 8) & 0xFF));
        payload.push_back(static_cast<uint8_t>(static_cast<uint16_t>(code) & 0xFF));
 
        // Append reason (if provided)
        if (!reason.empty())
        {
            // Validate UTF-8 in reason
            std::vector<uint8_t> reason_bytes(reason.begin(), reason.end());
            if (is_valid_utf8(reason_bytes))
            {
                payload.insert(payload.end(), reason.begin(), reason.end());
            }
        }
 
        // Ensure payload <= 125 bytes
        if (payload.size() > 125)
        {
            payload.resize(125);
        }
 
        return websocket_frame::encode_frame(ws_opcode::close, std::move(payload), true,
                                             is_client_);
    }

References kcenon::network::internal::close, and kcenon::network::internal::websocket_frame::encode_frame().

Here is the call graph for this function:

◆ create_ping()

auto kcenon::network::internal::websocket_protocol::create_ping ( std::vector< uint8_t > && payload = {} ) -> std::vector<uint8_t>

Creates 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 (typically empty)

Returns: Encoded ping frame

Definition at line 276 of file websocket_protocol.cpp.

    {
        // Ping payload must be <= 125 bytes
        if (payload.size() > 125)
        {
            payload.resize(125);
        }
 
        return websocket_frame::encode_frame(ws_opcode::ping, std::move(payload), true,
                                             is_client_);
    }

References kcenon::network::internal::websocket_frame::encode_frame(), and kcenon::network::internal::ping.

Here is the call graph for this function:

◆ create_pong()

auto kcenon::network::internal::websocket_protocol::create_pong ( std::vector< uint8_t > && payload = {} ) -> std::vector<uint8_t>

Creates a pong control frame.

Pong frames are sent in response to ping frames.

Parameters

payload Payload data (should match the ping payload)

Returns: Encoded pong frame

Definition at line 289 of file websocket_protocol.cpp.

    {
        // Pong payload must be <= 125 bytes
        if (payload.size() > 125)
        {
            payload.resize(125);
        }
 
        return websocket_frame::encode_frame(ws_opcode::pong, std::move(payload), true,
                                             is_client_);
    }

References kcenon::network::internal::websocket_frame::encode_frame(), and kcenon::network::internal::pong.

Referenced by kcenon::network::internal::websocket_socket::websocket_socket().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ create_text_message()

auto kcenon::network::internal::websocket_protocol::create_text_message ( std::string && text ) -> std::vector<uint8_t>

Creates a text message frame.

Encodes the text as a WebSocket text frame with UTF-8 validation. Uses move semantics for zero-copy operation.

Parameters

text	The text message to send

Returns: Encoded WebSocket frame ready for transmission

Definition at line 251 of file websocket_protocol.cpp.

    {
        // Convert string to bytes
        std::vector<uint8_t> payload(text.begin(), text.end());
 
        // Validate UTF-8
        if (!is_valid_utf8(payload))
        {
            // Return empty frame on invalid UTF-8
            return {};
        }
 
        // Encode as WebSocket frame
        return websocket_frame::encode_frame(ws_opcode::text, std::move(payload), true,
                                             is_client_);
    }

References kcenon::network::internal::websocket_frame::encode_frame(), and kcenon::network::internal::text.

Here is the call graph for this function:

◆ handle_close()

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

private

Handles a close frame.

Parses the close code and reason, then invokes the close callback.

Parameters

payload The close frame payload

Definition at line 219 of file websocket_protocol.cpp.

    {
        ws_close_code code = ws_close_code::normal;
        std::string reason;
 
        if (payload.size() >= 2)
        {
            // Extract close code (network byte order)
            code = static_cast<ws_close_code>((payload[0] << 8) | payload[1]);
 
            // Extract reason (if present)
            if (payload.size() > 2)
            {
                reason = std::string(payload.begin() + 2, payload.end());
 
                // Validate UTF-8 in reason
                std::vector<uint8_t> reason_bytes(reason.begin(), reason.end());
                if (!is_valid_utf8(reason_bytes))
                {
                    // Invalid UTF-8 in close reason
                    code = ws_close_code::protocol_error;
                    reason.clear();
                }
            }
        }
 
        if (close_callback_)
        {
            close_callback_(code, reason);
        }
    }

References kcenon::network::internal::normal, and kcenon::network::internal::protocol_error.

◆ handle_control_frame()

auto kcenon::network::internal::websocket_protocol::handle_control_frame	(	const ws_frame_header &	header,
		const std::vector< uint8_t > &	payload ) -> void

private

Handles a control frame (ping, pong, close).

Control frames must not be fragmented.

Parameters

header	The frame header
payload	The frame payload

Definition at line 168 of file websocket_protocol.cpp.

    {
        // Control frames must not be fragmented
        if (!header.fin)
        {
            // Protocol error
            return;
        }
 
        // Control frames must have payload <= 125 bytes
        if (header.payload_len > 125)
        {
            // Protocol error
            return;
        }
 
        switch (header.opcode)
        {
        case ws_opcode::ping:
            handle_ping(payload);
            break;
        case ws_opcode::pong:
            handle_pong(payload);
            break;
        case ws_opcode::close:
            handle_close(payload);
            break;
        default:
            // Unknown control frame
            break;
        }
    }

References kcenon::network::internal::close, kcenon::network::internal::ping, and kcenon::network::internal::pong.

◆ handle_data_frame()

auto kcenon::network::internal::websocket_protocol::handle_data_frame	(	const ws_frame_header &	header,
		const std::vector< uint8_t > &	payload ) -> void

private

Handles a data frame (text or binary).

Manages fragmentation and reassembly.

Parameters

header	The frame header
payload	The frame payload

Definition at line 90 of file websocket_protocol.cpp.

    {
        // Handle fragmentation
        if (header.opcode == ws_opcode::continuation)
        {
            // Continuation frame
            if (fragmented_message_.empty())
            {
                // Protocol error: continuation without initial frame
                return;
            }
 
            // Append to fragmented message
            fragmented_message_.insert(fragmented_message_.end(), payload.begin(),
                                       payload.end());
 
            if (header.fin)
            {
                // Final fragment - complete message
                ws_message msg;
                msg.type = (fragmented_type_ == ws_opcode::text) ? ws_message_type::text
                                                                  : ws_message_type::binary;
                msg.data = std::move(fragmented_message_);
 
                // Validate UTF-8 for text messages
                if (msg.type == ws_message_type::text && !is_valid_utf8(msg.data))
                {
                    // Invalid UTF-8, protocol error
                    fragmented_message_.clear();
                    return;
                }
 
                // Clear fragmentation state
                fragmented_message_.clear();
                fragmented_type_ = ws_opcode::continuation;
 
                // Invoke callback
                if (message_callback_)
                {
                    message_callback_(msg);
                }
            }
        }
        else
        {
            // Initial frame (text or binary)
            if (!header.fin)
            {
                // Start of fragmented message
                fragmented_type_ = header.opcode;
                fragmented_message_ = payload;
            }
            else
            {
                // Complete message in single frame
                ws_message msg;
                msg.type = (header.opcode == ws_opcode::text) ? ws_message_type::text
                                                               : ws_message_type::binary;
                msg.data = payload;
 
                // Validate UTF-8 for text messages
                if (msg.type == ws_message_type::text && !is_valid_utf8(msg.data))
                {
                    // Invalid UTF-8, protocol error
                    return;
                }
 
                // Invoke callback
                if (message_callback_)
                {
                    message_callback_(msg);
                }
            }
        }
    }

References kcenon::network::internal::binary, kcenon::network::internal::continuation, kcenon::network::internal::ws_message::data, kcenon::network::internal::text, and kcenon::network::internal::ws_message::type.

◆ handle_ping()

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

private

Handles a ping frame.

Invokes the ping callback if set.

Parameters

payload The ping payload

Definition at line 203 of file websocket_protocol.cpp.

    {
        if (ping_callback_)
        {
            ping_callback_(payload);
        }
    }

◆ handle_pong()

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

private

Handles a pong frame.

Invokes the pong callback if set.

Parameters

payload The pong payload

Definition at line 211 of file websocket_protocol.cpp.

    {
        if (pong_callback_)
        {
            pong_callback_(payload);
        }
    }

◆ is_valid_utf8()

auto kcenon::network::internal::websocket_protocol::is_valid_utf8 ( const std::vector< uint8_t > & data ) -> bool

staticprivate

Validates UTF-8 encoding.

Checks if the data is valid UTF-8 (required for text messages).

Parameters

data	The data to validate

Returns: True if valid UTF-8, false otherwise

Definition at line 356 of file websocket_protocol.cpp.

    {
        size_t i = 0;
        while (i < data.size())
        {
            uint8_t byte = data[i];
 
            // Determine the number of bytes in this UTF-8 character
            int bytes_to_follow = 0;
 
            if ((byte & 0x80) == 0x00)
            {
                // 1-byte character (0xxxxxxx)
                bytes_to_follow = 0;
            }
            else if ((byte & 0xE0) == 0xC0)
            {
                // 2-byte character (110xxxxx)
                bytes_to_follow = 1;
            }
            else if ((byte & 0xF0) == 0xE0)
            {
                // 3-byte character (1110xxxx)
                bytes_to_follow = 2;
            }
            else if ((byte & 0xF8) == 0xF0)
            {
                // 4-byte character (11110xxx)
                bytes_to_follow = 3;
            }
            else
            {
                // Invalid UTF-8 start byte
                return false;
            }
 
            // Check if we have enough bytes
            if (i + bytes_to_follow >= data.size())
            {
                return false;
            }
 
            // Validate continuation bytes
            for (int j = 1; j <= bytes_to_follow; ++j)
            {
                if ((data[i + j] & 0xC0) != 0x80)
                {
                    // Invalid continuation byte (should be 10xxxxxx)
                    return false;
                }
            }
 
            i += bytes_to_follow + 1;
        }
 
        return true;
    }

◆ process_data()

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

Processes incoming WebSocket data.

Parses frames, handles fragmentation, and invokes appropriate callbacks. This method should be called when data is received from the network.

Zero-Copy Performance

Accepts data as a non-owning span view, avoiding unnecessary copies. The data is copied once into the internal buffer for frame processing.

Lifetime Contract

The span must remain valid for the duration of this call.
After the call returns, the span may be invalidated.

Parameters

data	The incoming data buffer as a view

Definition at line 36 of file websocket_protocol.cpp.

    {
        // Append incoming data to buffer (single copy from span view)
        buffer_.insert(buffer_.end(), data.begin(), data.end());
 
        // Process frames from buffer
        process_frames();
    }

◆ process_frames()

auto kcenon::network::internal::websocket_protocol::process_frames ( ) -> void

private

Processes incoming frames from the buffer.

Attempts to parse and handle frames from the accumulated buffer. May invoke callbacks for complete messages.

Definition at line 45 of file websocket_protocol.cpp.

    {
        while (true)
        {
            // Try to decode frame header
            auto header_opt = websocket_frame::decode_header(buffer_);
            if (!header_opt.has_value())
            {
                // Not enough data for header, wait for more
                return;
            }
 
            const auto& header = header_opt.value();
 
            // Calculate total frame size
            const size_t header_size =
                websocket_frame::calculate_header_size(header.payload_len, header.mask);
            const size_t frame_size = header_size + header.payload_len;
 
            // Check if we have the complete frame
            if (buffer_.size() < frame_size)
            {
                // Incomplete frame, wait for more data
                return;
            }
 
            // Decode payload
            auto payload = websocket_frame::decode_payload(header, buffer_);
 
            // Remove processed frame from buffer
            buffer_.erase(buffer_.begin(), buffer_.begin() + frame_size);
 
            // Dispatch frame based on opcode
            if (header.opcode == ws_opcode::text || header.opcode == ws_opcode::binary ||
                header.opcode == ws_opcode::continuation)
            {
                handle_data_frame(header, payload);
            }
            else
            {
                handle_control_frame(header, payload);
            }
        }
    }

References kcenon::network::internal::binary, kcenon::network::internal::websocket_frame::calculate_header_size(), kcenon::network::internal::continuation, kcenon::network::internal::websocket_frame::decode_header(), kcenon::network::internal::websocket_frame::decode_payload(), and kcenon::network::internal::text.

Here is the call graph for this function:

◆ set_close_callback()

auto kcenon::network::internal::websocket_protocol::set_close_callback ( std::function< void(ws_close_code, const std::string &)> callback ) -> void

Sets the callback for 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 350 of file websocket_protocol.cpp.

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

Referenced by kcenon::network::internal::websocket_socket::websocket_socket().

Here is the caller graph for this function:

◆ set_message_callback()

auto kcenon::network::internal::websocket_protocol::set_message_callback ( std::function< void(const ws_message &)> callback ) -> void

Sets the callback for data 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 332 of file websocket_protocol.cpp.

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

Referenced by kcenon::network::internal::websocket_socket::websocket_socket().

Here is the caller graph for this function:

◆ set_ping_callback()

auto kcenon::network::internal::websocket_protocol::set_ping_callback ( std::function< void(const std::vector< uint8_t > &)> callback ) -> void

Sets the callback for 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 338 of file websocket_protocol.cpp.

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

Referenced by kcenon::network::internal::websocket_socket::websocket_socket().

Here is the caller graph for this function:

◆ set_pong_callback()

auto kcenon::network::internal::websocket_protocol::set_pong_callback ( std::function< void(const std::vector< uint8_t > &)> callback ) -> void

Sets the callback for 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 344 of file websocket_protocol.cpp.

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

Referenced by kcenon::network::internal::websocket_socket::websocket_socket().

Here is the caller graph for this function:

Member Data Documentation

◆ buffer_

std::vector<uint8_t> kcenon::network::internal::websocket_protocol::buffer_

private

Incoming data buffer.

Definition at line 214 of file websocket_protocol.h.

◆ close_callback_

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

private

Definition at line 222 of file websocket_protocol.h.

◆ fragmented_message_

std::vector<uint8_t> kcenon::network::internal::websocket_protocol::fragmented_message_

private

Reassembly buffer for fragmented messages.

Definition at line 215 of file websocket_protocol.h.

◆ fragmented_type_

ws_opcode kcenon::network::internal::websocket_protocol::fragmented_type_

private

Type of fragmented message in progress.

Definition at line 216 of file websocket_protocol.h.

◆ is_client_

bool kcenon::network::internal::websocket_protocol::is_client_

private

True if client (applies masking)

Definition at line 213 of file websocket_protocol.h.

◆ message_callback_

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

private

Definition at line 219 of file websocket_protocol.h.

◆ ping_callback_

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

private

Definition at line 220 of file websocket_protocol.h.

◆ pong_callback_

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

private

Definition at line 221 of file websocket_protocol.h.

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

src/internal/websocket/websocket_protocol.h
src/internal/websocket_protocol.cpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ websocket_protocol()

Member Function Documentation

◆ create_binary_message()

◆ create_close()

◆ create_ping()

◆ create_pong()

◆ create_text_message()

◆ handle_close()

◆ handle_control_frame()

◆ handle_data_frame()

◆ handle_ping()

◆ handle_pong()

◆ is_valid_utf8()

◆ process_data()

Zero-Copy Performance

Lifetime Contract

◆ process_frames()

◆ set_close_callback()

◆ set_message_callback()

◆ set_ping_callback()

◆ set_pong_callback()

Member Data Documentation

◆ buffer_

◆ close_callback_

◆ fragmented_message_

◆ fragmented_type_

◆ is_client_

◆ message_callback_

◆ ping_callback_

◆ pong_callback_