dmsc::c

Module ws

Expand description

This file is part of DMSC. The DMSC project belongs to the Dunimd Team.

Licensed under the Apache License, Version 2.0 (the “License”); You may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

§WebSocket Module C API

This module provides C language bindings for DMSC’s WebSocket communication infrastructure. The WebSocket module delivers full-duplex, real-time communication capabilities for building interactive applications, live dashboards, chat systems, gaming backends, and streaming services. This C API enables C/C++ applications to leverage DMSC’s WebSocket functionality for building responsive, bidirectional communication layers over persistent connections.

§Module Architecture

The WebSocket module comprises three primary components that together provide complete WebSocket communication capabilities:

DMSCWSServerConfig: Configuration container for WebSocket server parameters including connection limits, message size limits, heartbeat settings, and security options. The configuration object controls server behavior, resource allocation, and operational characteristics.
DMSCWSSession: Individual WebSocket connection representation, tracking connection state, session metadata, message queues, and communication properties. Each session represents a unique client connection to the WebSocket server.
DMSCWSSessionManager: Central manager for all WebSocket sessions, handling session lifecycle, broadcasting, routing, and connection administration. The manager handles the complete WebSocket communication workflow including connection handling, message distribution, and cleanup.

§WebSocket Protocol

The WebSocket implementation provides complete RFC 6455 compliance:

Handshake Handling: Complete WebSocket handshake processing with HTTP upgrade mechanism. Validates request headers, verifies protocol version, and generates proper responses.
Frame Processing: Full frame lifecycle management including text frames, binary frames, continuation frames, close frames, ping frames, and pong frames. Handles fragmentation and reassembly transparently.
Extensions Support: Configurable WebSocket extensions including per-message deflate compression (RFC 7692) for reduced bandwidth usage. Support for custom extensions.
Subprotocol Negotiation: Support for WebSocket subprotocols for application-specific messaging semantics. Includes built-in support for common subprotocols.
Status Codes: Complete handling of WebSocket status codes including normal closure (1000), going away (1001), protocol error (1002), unsupported data (1003), and application codes.
Reason Phrases: Proper close frame reason phrases for debugging and logging. Includes support for custom application reason codes.

§Message Types

The WebSocket module supports comprehensive message types:

Text Messages: UTF-8 encoded text messages with automatic validation. Supports JSON, XML, and other text-based protocols. Validates UTF-8 encoding compliance.
Binary Messages: Raw binary data transmission for efficiency. Ideal for protocol buffers, images, files, and other binary formats. No encoding overhead or validation.
Continuation Messages: Support for message fragmentation across multiple frames. Automatic reassembly of fragmented messages on receive, transparent fragmentation on send.
Control Frames: Ping and Pong frames for connection health monitoring. Close frames for graceful connection termination with configurable reason codes.
Pong Payloads: Custom payload support in Pong frames for application-specific heartbeat data. Includes timestamp and custom application data.

§Connection Management

The session manager provides comprehensive connection handling:

Connection Lifecycle: Complete connection lifecycle from TCP handshake through WebSocket upgrade to graceful close. Handles all intermediate states and transitions.
Keep-Alive Mechanisms: Configurable keep-alive intervals with automatic Ping/Pong exchange. Detects half-open connections and zombie clients.
Heartbeat System: Application-level heartbeat for more sophisticated connection monitoring. Custom heartbeat intervals and timeout values per session.
Graceful Shutdown: Proper WebSocket close handshake with configurable timeout. Ensures all pending messages are sent before connection termination.
Forced Disconnection: Emergency disconnection capability for abuse prevention and resource cleanup. Includes configurable disconnect behavior and cleanup.
Connection Pooling: Resource pooling for high-connection-count scenarios. Reduces memory allocation overhead for large numbers of concurrent connections.

§Session Features

Individual sessions provide rich functionality:

Session Metadata: Store and retrieve arbitrary session data including user context, authentication state, and application-specific information. Key-value storage per session.
Remote Address: Access client network information including IP address, port, and protocol (IPv4/IPv6). Includes proxy protocol header parsing if enabled.
Connection Time: Track when the session was established for session duration calculations and timeout management.
Message Counters: Statistics tracking including messages sent, messages received, bytes sent, bytes received. Useful for monitoring and rate limiting.
Last Activity: Timestamp of last received message for idle detection and timeout management. Updated automatically on message receipt.
Request Information: Access to original HTTP upgrade request headers. Includes cookies, origin, subprotocols, and custom headers.

§Broadcasting

The session manager supports efficient message distribution:

Broadcast to All: Send message to all connected sessions with single call. Optimized for minimal overhead in multi-connection scenarios.
Selective Broadcast: Target specific sessions using filter criteria. Filter by session data, connection time, message counts, or custom predicates.
Room/Channel System: Group sessions into named rooms for targeted messaging. Supports dynamic room membership and room statistics.
Topic-Based Routing: Subscribe sessions to topics for pub/sub-style messaging. Efficient topic-based message routing with automatic topic management.
Exclusion: Broadcast to all except specific sessions. Useful for acknowledging messages back to sender while excluding them from broadcast.
Batching: Configurable batching for high-volume broadcasting. Reduces system calls and improves throughput for mass messaging.

§Security Features

The WebSocket module implements comprehensive security measures:

Origin Validation: Verify incoming requests against allowed origin list. Prevents cross-site WebSocket hijacking (CSWSH) attacks.
Subprotocol Validation: Validate requested subprotocols against allowed list. Ensures only negotiated subprotocols are used.
Request Validation: Validate HTTP upgrade request headers for security. Rejects malformed or suspicious requests.
Rate Limiting: Per-session and global rate limiting for message frequency. Configurable limits with customizable behavior (drop, queue, reject).
Message Size Limits: Configurable maximum message sizes for text and binary. Protects against memory exhaustion from oversized messages.
Connection Limits: Maximum concurrent connections per server and per IP. Prevents resource exhaustion from connection flooding.
TLS/SSL Support: Complete TLS integration for WSS (WebSocket Secure) connections. Modern TLS versions with configurable cipher suites.
Authentication Integration: Built-in support for token-based authentication. WebSocket-specific authentication handshake extensions.

§Compression

Built-in compression reduces bandwidth usage:

Per-Message Deflate: RFC 7692 compression for WebSocket messages. Transparent compression and decompression without application changes.
Compression Level: Configurable compression levels trading CPU for compression. Supports levels from fastest (no compression) to best compression.
Context Takeover: Optional context takeover for improved compression ratios. Memory trade-off for better compression efficiency.
Server Window Bits: Configurable server window size for compression. Tuning for specific bandwidth/CPU requirements.

§Performance Characteristics

WebSocket operations are optimized for high throughput:

Connection Handling: O(1) for new connections with constant-time session creation
Message Sending: O(1) to O(n) depending on broadcast targets
Message Receiving: O(1) for frame processing, O(n) for large message reassembly
Broadcasting: O(n) where n is number of target sessions
Throughput: Supports millions of messages per second on modern hardware
Latency: Sub-millisecond message processing for local connections

§Memory Management

All C API objects use opaque pointers with manual memory management:

Constructor functions allocate new instances on the heap
Destructor functions must be called to release memory
Session managers coordinate session cleanup
Message buffers are recycled for performance

§Thread Safety

The underlying implementations are thread-safe:

Concurrent connection handling from multiple threads supported
Message sending can be done from any thread
Session operations use internal synchronization
Broadcasting coordinates access across sessions

§Usage Example

// Create WebSocket server configuration
DMSCWSServerConfig* config = dmsc_ws_server_config_new();
if (config == NULL) {
    fprintf(stderr, "Failed to create WebSocket config\n");
    return ERROR_INIT;
}

// Configure server settings
dmsc_ws_server_config_set_host(config, "0.0.0.0");
dmsc_ws_server_config_set_port(config, 8080);
dmsc_ws_server_config_set_max_connections(config, 10000);
dmsc_ws_server_config_set_max_message_size(config, 1024 * 1024);  // 1MB
dmsc_ws_server_config_set_ping_interval(config, 30000);  // 30 seconds
dmsc_ws_server_config_set_ping_timeout(config, 5000);  // 5 seconds

// Enable compression
dmsc_ws_server_config_set_compression_enabled(config, true);
dmsc_ws_server_config_set_compression_level(config, 6);

// Enable security features
dmsc_ws_server_config_set_origin_validation(config, true);
dmsc_ws_server_config_add_allowed_origin(config, "https://example.com");
dmsc_ws_server_config_set_rate_limit_enabled(config, true);
dmsc_ws_server_config_set_rate_limit_messages(config, 100);
dmsc_ws_server_config_set_rate_limit_window(config, 1000);  // 1 second

// Create session manager
DMSCWSSessionManager* manager = dmsc_ws_session_manager_new(config);
if (manager == NULL) {
    fprintf(stderr, "Failed to create session manager\n");
    dmsc_ws_server_config_free(config);
    return ERROR_INIT;
}

// Start WebSocket server
int result = dmsc_ws_session_manager_start(manager);
if (result != 0) {
    fprintf(stderr, "Failed to start WebSocket server: %d\n", result);
    dmsc_ws_session_manager_free(manager);
    dmsc_ws_server_config_free(config);
    return ERROR_START;
}

printf("WebSocket server started on port %d\n",
       dmsc_ws_server_config_get_port(config));

// Set up event callbacks
dmsc_ws_session_manager_set_on_connect(manager, on_connect_callback, NULL);
dmsc_ws_session_manager_set_on_message(manager, on_message_callback, NULL);
dmsc_ws_session_manager_set_on_close(manager, on_close_callback, NULL);
dmsc_ws_session_manager_set_on_error(manager, on_error_callback, NULL);

// Application main loop - process events
while (running) {
    // Handle events with timeout
    dmsc_ws_session_manager_poll(manager, 1000);  // 1 second timeout

    // Process pending operations
    process_application_tasks();

    // Periodic tasks
    if (should_check_health()) {
        uint32_t active_count = dmsc_ws_session_manager_get_active_count(manager);
        uint32_t total_count = dmsc_ws_session_manager_get_total_count(manager);
        uint64_t total_messages = dmsc_ws_session_manager_get_total_messages(manager);

        printf("Active sessions: %u/%u, Messages: %lu\n",
               active_count, total_count, total_messages);
    }
}

// Broadcast message to all clients
const char* broadcast_msg = "{\"type\": \"broadcast\", \"message\": \"Hello all!\"}";
int send_count = dmsc_ws_session_manager_broadcast(manager, broadcast_msg, strlen(broadcast_msg));
printf("Broadcast sent to %d clients\n", send_count);

// Get session information
uint32_t session_count = dmsc_ws_session_manager_get_session_ids(manager, session_ids, max_sessions);

for (uint32_t i = 0; i < session_count && i < 10; i++) {
    DMSCWSSession* session = dmsc_ws_session_manager_get_session(manager, session_ids[i]);
    if (session != NULL) {
        const char* remote_addr = dmsc_ws_session_get_remote_addr(session);
        uint64_t connected_at = dmsc_ws_session_get_connected_at(session);
        uint64_t messages_sent = dmsc_ws_session_get_messages_sent(session);
        uint64_t bytes_sent = dmsc_ws_session_get_bytes_sent(session);

        printf("Session %u: %s, connected: %lu, sent: %lu/%lu\n",
               session_ids[i], remote_addr, connected_at, messages_sent, bytes_sent);

        // Send message to specific session
        dmsc_ws_session_send(session, "Welcome!", 8);

        dmsc_ws_session_free(session);
    }
}

// Room management example
const char* room_name = "chat_room_1";
dmsc_ws_session_manager_join_room(manager, session_ids[0], room_name);

// Send to room members only
const char* room_msg = "{\"type\": \"room\", \"content\": \"Hello room!\"}";
int room_count = dmsc_ws_session_manager_send_to_room(manager, room_name, room_msg, strlen(room_msg));
printf("Room message sent to %d clients\n", room_count);

// Send to room except sender
dmsc_ws_session_manager_send_to_room_except(
    manager, room_name, session_ids[0],
    room_msg, strlen(room_msg)
);

// Leave room
dmsc_ws_session_manager_leave_room(manager, session_ids[0], room_name);

// Get room members
uint32_t room_members[100];
uint32_t room_count = dmsc_ws_session_manager_get_room_members(
    manager, room_name, room_members, 100
);
printf("Room '%s' has %u members\n", room_name, room_count);

// Graceful shutdown
printf("Shutting down WebSocket server...\n");
dmsc_ws_session_manager_stop(manager, 5000);  // 5 second timeout
dmsc_ws_session_manager_free(manager);
dmsc_ws_server_config_free(config);

printf("WebSocket server shutdown complete\n");

§Event Callback Signatures

Event handlers must conform to the following signatures:

// Connection established
typedef void (*DMSWSConnectCallback)(
    DMSCWSSessionManager* manager,
    DMSCWSSession* session,
    void* user_data
);

// Message received
typedef void (*DMSWSMessageCallback)(
    DMSCWSSessionManager* manager,
    DMSCWSSession* session,
    DMSWSMessageType type,
    const char* data,
    size_t length,
    void* user_data
);

// Connection closed
typedef void (*DMSWSCloseCallback)(
    DMSCWSSessionManager* manager,
    DMSCWSSession* session,
    uint16_t code,
    const char* reason,
    void* user_data
);

// Error occurred
typedef void (*DMSWSErrorCallback)(
    DMSCWSSessionManager* manager,
    DMSCWSSession* session,
    int error_code,
    const char* error_message,
    void* user_data
);

§Dependencies

This module depends on the following DMSC components:

crate::ws: Rust WebSocket module implementation
crate::prelude: Common types and traits
tokio for async runtime (when async features enabled)
tungstenite for WebSocket protocol (when using pure Rust implementation)

§Feature Flags

The WebSocket module is enabled by the “ws” feature flag. Disable this feature to reduce binary size when WebSocket is not required.

Additional features:

ws-tungstenite: Enable Tungstenite-based WebSocket implementation
ws-async: Enable async message handling
ws-compression: Enable per-message deflate compression
ws-tls: Enable TLS/WSS support
ws-rate-limit: Enable rate limiting

Structs§

CDMSCWSServerConfig
CDMSCWSSession
CDMSCWSSessionManager

Functions§

dmsc_ws_server_config_free
dmsc_ws_server_config_new

Module ws

Module ws Copy item path

§WebSocket Module C API

§Module Architecture

§WebSocket Protocol

§Message Types

§Connection Management

§Session Features

§Broadcasting

§Security Features

§Compression

§Performance Characteristics

§Memory Management

§Thread Safety

§Usage Example

§Event Callback Signatures

§Dependencies

§Feature Flags

Structs§

Functions§

Module ws