kcenon::network::internal::websocket_frame Class Reference

Provides WebSocket frame encoding and decoding functionality. More...

#include <websocket_frame.h>

Collaboration diagram for kcenon::network::internal::websocket_frame:

Static Public Member Functions
static auto	encode_frame (ws_opcode opcode, std::vector< uint8_t > &&payload, bool fin=true, bool mask=false) -> std::vector< uint8_t >
	Encodes data into a WebSocket frame.
static auto	decode_header (const std::vector< uint8_t > &data) -> std::optional< ws_frame_header >
	Decodes a WebSocket frame header from raw data.
static auto	decode_payload (const ws_frame_header &header, const std::vector< uint8_t > &data) -> std::vector< uint8_t >
	Decodes the payload from a WebSocket frame.
static auto	apply_mask (std::vector< uint8_t > &data, const std::array< uint8_t, 4 > &mask) -> void
	Applies or removes XOR masking on data.
static auto	generate_mask () -> std::array< uint8_t, 4 >
	Generates a random 4-byte masking key.
static auto	calculate_header_size (uint64_t payload_len, bool mask) -> size_t
	Calculates the size of the frame header.

Detailed Description

Provides WebSocket frame encoding and decoding functionality.

This class implements RFC 6455 compliant frame encoding and decoding, including support for masking, fragmentation, and all frame types.

Definition at line 57 of file websocket_frame.h.

Member Function Documentation

apply_mask()

auto kcenon::network::internal::websocket_frame::apply_mask ( std::vector< uint8_t > & data, const std::array< uint8_t, 4 > & mask ) -> void

static

Applies or removes XOR masking on data.

WebSocket masking is symmetric (XOR operation), so this function can be used both to apply and remove masking.

Parameters

data	The data to mask/unmask (modified in place)
mask	The 4-byte masking key

Definition at line 249 of file websocket_frame.cpp.

    {
        for (size_t i = 0; i < data.size(); ++i)
        {
            data[i] ^= mask[i % 4];
        }
    }

calculate_header_size()

auto kcenon::network::internal::websocket_frame::calculate_header_size ( uint64_t payload_len, bool mask ) -> size_t

static

Calculates the size of the frame header.

Determines how many bytes the header will occupy based on payload length and masking flag.

Parameters

payload_len	The length of the payload
mask	Whether the frame will be masked

Returns

The header size in bytes

Definition at line 78 of file websocket_frame.cpp.

    {
        size_t header_size = MIN_HEADER_SIZE;
 
        if (payload_len >= 65536)
        {
            header_size += 8; // 64-bit length field
        }
        else if (payload_len >= 126)
        {
            header_size += 2; // 16-bit length field
        }
 
        if (mask)
        {
            header_size += MASKING_KEY_SIZE;
        }
 
        return header_size;
    }

Referenced by kcenon::network::internal::websocket_protocol::process_frames().

Here is the caller graph for this function:

decode_header()

auto kcenon::network::internal::websocket_frame::decode_header ( const std::vector< uint8_t > & data ) -> std::optional<ws_frame_header>

static

Decodes a WebSocket frame header from raw data.

Parses the first bytes of a WebSocket frame to extract header information. Does not validate or extract the payload.

Parameters

data	The raw frame data

Returns

Decoded header if valid, std::nullopt if invalid or incomplete

Definition at line 164 of file websocket_frame.cpp.

    {
        if (data.size() < MIN_HEADER_SIZE)
        {
            return std::nullopt;
        }
 
        ws_frame_header header{};
 
        // Parse byte 0: FIN, RSV1-3, Opcode
        const uint8_t byte0 = data[0];
        header.fin = (byte0 & FIN_BIT) != 0;
        header.rsv1 = (byte0 & RSV1_BIT) != 0;
        header.rsv2 = (byte0 & RSV2_BIT) != 0;
        header.rsv3 = (byte0 & RSV3_BIT) != 0;
        header.opcode = static_cast<ws_opcode>(byte0 & OPCODE_MASK);
 
        // Parse byte 1: Mask, Payload length
        const uint8_t byte1 = data[1];
        header.mask = (byte1 & MASK_BIT) != 0;
        uint8_t payload_len = byte1 & PAYLOAD_LEN_MASK;
 
        size_t offset = MIN_HEADER_SIZE;
 
        // Extended payload length
        if (payload_len == PAYLOAD_LEN_16BIT)
        {
            if (data.size() < offset + 2)
            {
                return std::nullopt;
            }
            header.payload_len = from_network_u16(&data[offset]);
            offset += 2;
        }
        else if (payload_len == PAYLOAD_LEN_64BIT)
        {
            if (data.size() < offset + 8)
            {
                return std::nullopt;
            }
            header.payload_len = from_network_u64(&data[offset]);
            offset += 8;
        }
        else
        {
            header.payload_len = payload_len;
        }
 
        // Masking key
        if (header.mask)
        {
            if (data.size() < offset + MASKING_KEY_SIZE)
            {
                return std::nullopt;
            }
            std::copy_n(data.begin() + offset, MASKING_KEY_SIZE, header.masking_key.begin());
        }
 
        return header;
    }

Referenced by kcenon::network::internal::websocket_protocol::process_frames().

Here is the caller graph for this function:

decode_payload()

auto kcenon::network::internal::websocket_frame::decode_payload ( const ws_frame_header & header, const std::vector< uint8_t > & data ) -> std::vector<uint8_t>

static

Decodes the payload from a WebSocket frame.

Extracts and unmasks (if necessary) the payload data from a frame using the provided header information.

Parameters

header	The decoded frame header
data	The complete frame data

Returns

Decoded (and unmasked if needed) payload

Definition at line 226 of file websocket_frame.cpp.

    {
        const size_t header_size = calculate_header_size(header.payload_len, header.mask);
 
        if (data.size() < header_size + header.payload_len)
        {
            return {};
        }
 
        std::vector<uint8_t> payload(data.begin() + header_size,
                                     data.begin() + header_size + header.payload_len);
 
        // Unmask if necessary
        if (header.mask)
        {
            apply_mask(payload, header.masking_key);
        }
 
        return payload;
    }

Referenced by kcenon::network::internal::websocket_protocol::process_frames().

Here is the caller graph for this function:

encode_frame()

auto kcenon::network::internal::websocket_frame::encode_frame ( ws_opcode opcode, std::vector< uint8_t > && payload, bool fin = true, bool mask = false ) -> std::vector<uint8_t>

static

Encodes data into a WebSocket frame.

Creates a properly formatted WebSocket frame with the specified opcode and payload. Uses move semantics for zero-copy operation.

Parameters

opcode	The operation code for this frame
payload	The payload data (will be moved)
fin	Final fragment flag (default: true)
mask	Whether to mask the payload (default: false)

Returns

Encoded frame as a byte vector

Definition at line 99 of file websocket_frame.cpp.

    {
        const uint64_t payload_len = payload.size();
        const size_t header_size = calculate_header_size(payload_len, mask);
 
        std::vector<uint8_t> frame;
        frame.reserve(header_size + payload_len);
 
        // Byte 0: FIN, RSV1-3, Opcode
        uint8_t byte0 = static_cast<uint8_t>(opcode);
        if (fin)
        {
            byte0 |= FIN_BIT;
        }
        frame.push_back(byte0);
 
        // Byte 1: Mask, Payload length
        uint8_t byte1 = 0;
        if (mask)
        {
            byte1 |= MASK_BIT;
        }
 
        if (payload_len < 126)
        {
            byte1 |= static_cast<uint8_t>(payload_len);
            frame.push_back(byte1);
        }
        else if (payload_len < 65536)
        {
            byte1 |= PAYLOAD_LEN_16BIT;
            frame.push_back(byte1);
 
            // Extended payload length (16-bit)
            auto len_bytes = to_network_u16(static_cast<uint16_t>(payload_len));
            frame.insert(frame.end(), len_bytes.begin(), len_bytes.end());
        }
        else
        {
            byte1 |= PAYLOAD_LEN_64BIT;
            frame.push_back(byte1);
 
            // Extended payload length (64-bit)
            auto len_bytes = to_network_u64(payload_len);
            frame.insert(frame.end(), len_bytes.begin(), len_bytes.end());
        }
 
        // Masking key (if mask is enabled)
        std::array<uint8_t, 4> masking_key{};
        if (mask)
        {
            masking_key = generate_mask();
            frame.insert(frame.end(), masking_key.begin(), masking_key.end());
 
            // Apply masking to payload
            apply_mask(payload, masking_key);
        }
 
        // Append payload
        frame.insert(frame.end(), payload.begin(), payload.end());
 
        return frame;
    }

Referenced by kcenon::network::internal::websocket_protocol::create_binary_message(), kcenon::network::internal::websocket_protocol::create_close(), kcenon::network::internal::websocket_protocol::create_ping(), kcenon::network::internal::websocket_protocol::create_pong(), and kcenon::network::internal::websocket_protocol::create_text_message().

Here is the caller graph for this function:

generate_mask()

auto kcenon::network::internal::websocket_frame::generate_mask ( ) -> std::array<uint8_t, 4>

static

Generates a random 4-byte masking key.

Creates a cryptographically random masking key as required by RFC 6455 for client-to-server frames.

Returns

A 4-byte random masking key

Definition at line 258 of file websocket_frame.cpp.

    {
        static thread_local std::random_device rd;
        static thread_local std::mt19937 gen(rd());
        static thread_local std::uniform_int_distribution<uint32_t> dis;
 
        const uint32_t random_value = dis(gen);
        return {static_cast<uint8_t>((random_value >> 24) & 0xFF),
                static_cast<uint8_t>((random_value >> 16) & 0xFF),
                static_cast<uint8_t>((random_value >> 8) & 0xFF),
                static_cast<uint8_t>(random_value & 0xFF)};
    }

---

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

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