server.h File Reference

WebSocket server for accepting browser client connections. More...

Go to the source code of this file.

Data Structures
struct	websocket_client_context_t
	Listener settings and callbacks used to create a WebSocket server. More...
struct	websocket_server_config_t
	Listener settings and callbacks used to create a WebSocket server. More...
struct	websocket_server
	Runtime state for the WebSocket listener and its client-handler pool. More...

Typedefs
typedef struct websocket_server	websocket_server_t
typedef struct thread_pool	thread_pool_t
	One queued function call waiting for a thread-pool worker.
typedef void *(*	websocket_client_handler_fn) (void *arg)
	Connection-specific values handed to a WebSocket client worker.

Functions
asciichat_error_t	websocket_server_init (websocket_server_t *server, const websocket_server_config_t *config)
	Initialize WebSocket server.
asciichat_error_t	websocket_server_run (websocket_server_t *server)
	Run WebSocket server event loop.
void	websocket_server_destroy (websocket_server_t *server)
	Destroy WebSocket server and free resources.
void	websocket_server_cancel_service (websocket_server_t *server)
	Wake the WebSocket server event loop immediately.

Detailed Description

WebSocket server for accepting browser client connections.

Provides a WebSocket server implementation using libwebsockets to accept connections from browser-based WASM clients alongside the TCP server.

This module mirrors the tcp_server API to provide consistent server-side connection handling regardless of transport type.

Usage Pattern

1. Configure server with websocket_server_config_t
2. Call websocket_server_init() to create libwebsockets context
3. Call websocket_server_run() to start event loop (blocks)
4. Signal shutdown by setting running flag to false
5. Call websocket_server_destroy() to clean up

Example

// Define client handler (same as TCP)
void *my_client_handler(void *arg) {
    websocket_client_context_t *ctx = (websocket_client_context_t *)arg;
    // Process client connection via transport
    acip_transport_destroy(ctx->transport);
    SAFE_FREE(ctx);
    return NULL;
}
 
// Configure and run server
websocket_server_config_t config = {
    .port = 27224,
    .client_handler = my_client_handler,
    .user_data = NULL
};
 
websocket_server_t server;
if (websocket_server_init(&server, &config) == ASCIICHAT_OK) {
    websocket_server_run(&server);
    websocket_server_destroy(&server);
}

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Definition in file include/ascii-chat/network/websocket/server.h.

Typedef Documentation

thread_pool_t

typedef struct thread_pool thread_pool_t

One queued function call waiting for a thread-pool worker.

Thread handle and shutdown metadata for one pool-owned thread

This is the handoff point for thread pool. Callers fill threads, threads_mutex, thread_count, is_work_queue_mode before passing it on; consumers read the values during the operation and return ownership only where the member contract explicitly says they do.

Definition at line 63 of file include/ascii-chat/network/websocket/server.h.

websocket_client_handler_fn

typedef void *(* websocket_client_handler_fn) (void *arg)

Connection-specific values handed to a WebSocket client worker.

Runtime state for the WebSocket listener and its client-handler pool

Client handler function type

Called when a new WebSocket client connects. The handler receives a fully initialized transport ready for ACIP packets.

Parameters

arg	websocket_client_context_t* containing connection info

Returns

Thread exit value (ignored)

Definition at line 76 of file include/ascii-chat/network/websocket/server.h.

websocket_server_t

typedef struct websocket_server websocket_server_t

Definition at line 61 of file include/ascii-chat/network/websocket/server.h.

Function Documentation

websocket_server_cancel_service()

void websocket_server_cancel_service

(

websocket_server_t *

server

)

Wake the WebSocket server event loop immediately.

Thread-safe. Wakes lws_service() from its timeout wait, allowing the event loop to check the running flag without waiting for the full service timeout (50ms).

Parameters

server

Server instance (must have a valid context)

Definition at line 868 of file lib/network/websocket/server.c.

                                                                 {
  if (server && server->context) {
    lws_cancel_service(server->context);
  }
}

References websocket_server::context.

Referenced by network_server_stop().

websocket_server_destroy()

void websocket_server_destroy

(

websocket_server_t *

server

)

Destroy WebSocket server and free resources.

Parameters

server

Server instance to destroy

Definition at line 874 of file lib/network/websocket/server.c.

                                                          {
  if (!server) {
    return;
  }
 
  atomic_store_bool(&server->running, false);
 
  // Cancel any pending libwebsockets service calls to interrupt blocking lws_service()
  // This prevents the event loop from getting stuck in lws_service()
  if (server->context) {
    log_debug("Cancelling libwebsockets service");
    lws_cancel_service(server->context);
  }
 
  // Unregister atomic fields
  NAMED_UNREGISTER(&server->running);
 
  if (server->context) {
    NAMED_UNREGISTER(server->context);
    lws_context_destroy(server->context);
    server->context = NULL;
  }
  if (server->handler_pool) {
    thread_pool_destroy(server->handler_pool);
    server->handler_pool = NULL;
  }
 
  log_debug("WebSocket server destroyed");
}

References websocket_server::context, websocket_server::handler_pool, log_debug, NAMED_UNREGISTER, websocket_server::running, and thread_pool_destroy().

Referenced by network_server_stop().

websocket_server_init()

asciichat_error_t websocket_server_init	(	websocket_server_t *	server,
		const websocket_server_config_t *	config )

Initialize WebSocket server.

Creates libwebsockets context and prepares for accepting connections.

Parameters

server	Server instance to initialize
config	Server configuration

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 703 of file lib/network/websocket/server.c.

                                                                                                             {
  if (!server || !config || !config->client_handler) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  memset(server, 0, sizeof(*server));
  server->handler = config->client_handler;
  server->user_data = config->user_data;
  server->port = config->port;
  atomic_store_bool(&server->running, true);
 
  // Store server pointer in protocol user data so callbacks can access it
  websocket_protocols[0].user = server; // http protocol
  websocket_protocols[1].user = server; // acip protocol
 
  // Enable libwebsockets logging through centralized logging system
  lws_log_init_server();
 
  // HTTP mount for /health endpoint (required for LWS_CALLBACK_HTTP to fire)
  static const struct lws_http_mount health_mount = {
      .mount_next = NULL,
      .mountpoint = "/",
      .mountpoint_len = 1,
      .origin = "http",
      .def = NULL,
      .protocol = "http",
      .origin_protocol = LWSMPRO_CALLBACK,
  };
 
  // Configure libwebsockets context
  struct lws_context_creation_info info = {0};
  info.port = config->port;
  info.iface = config->bind_address;
  info.protocols = websocket_protocols;
  info.mounts = &health_mount;
  info.gid = (gid_t)-1;                                // Cast to avoid undefined behavior with unsigned type
  info.uid = (uid_t)-1;                                // Cast to avoid undefined behavior with unsigned type
  info.options = LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT; // Initialize SSL/TLS support (required for server binding)
  info.extensions = NULL;                              // Disable permessage-deflate - causing connection issues
  info.retry_and_idle_policy = &keep_alive_policy; // Configure keep-alive to prevent idle disconnects during handshake
 
  // Configure TLS/WSS support if certificates are provided (check for non-empty strings)
  if (config->tls_cert_path && config->tls_cert_path[0] != '\0' && config->tls_key_path &&
      config->tls_key_path[0] != '\0') {
#ifdef LWS_WITH_TLS
    // Validate certificate and key files are readable
    if (platform_access(config->tls_cert_path, R_OK) != 0) {
      return SET_ERRNO(ERROR_NETWORK_BIND, "TLS certificate file not readable: %s (errno=%d)", config->tls_cert_path,
                       errno);
    }
    if (platform_access(config->tls_key_path, R_OK) != 0) {
      return SET_ERRNO(ERROR_NETWORK_BIND, "TLS key file not readable: %s (errno=%d)", config->tls_key_path, errno);
    }
 
    info.ssl_cert_filepath = config->tls_cert_path;
    info.ssl_private_key_filepath = config->tls_key_path;
    server->tls_enabled = true;
    log_info("WebSocket server configured for WSS (TLS): cert=%s, key=%s", config->tls_cert_path, config->tls_key_path);
#else
    log_warn("WebSocket server: TLS support not compiled in libwebsockets; WSS unavailable");
#endif
  } else if ((config->tls_cert_path && config->tls_cert_path[0] != '\0') ||
             (config->tls_key_path && config->tls_key_path[0] != '\0')) {
    NOTICE(DANGER, "WEBSOCKET TLS DISABLED",
           "WebSocket server: Both TLS certificate and key must be provided for WSS; using plain WS");
  }
 
  // Increase per-thread service buffer to prevent fragmentation of large messages
  // Default is 4KB, causing large frames to fragment into many chunks
  // Video frames are 921KB, so increase to 2MB to handle them without fragmentation
  info.pt_serv_buf_size = 2 * 1024 * 1024; // 2MB per-thread service buffer
 
  // Disable ALL default timeouts and keep-alive mechanisms
  // Use only the explicit retry_and_idle_policy we set above (30/35 seconds)
  info.ka_time = 0;           // Disable TCP keep-alive probes (use WebSocket pings instead)
  info.ka_probes = 0;         // Disable TCP probes
  info.ka_interval = 0;       // Disable TCP probe intervals
  info.keepalive_timeout = 0; // Disable HTTP keep-alive timeout entirely
 
  // Explicitly set a very large idle timeout to prevent early disconnection
  // Without this, libwebsockets defaults to 5 seconds for HTTP connections
  // Set to effectively infinite (100 hours) since we use retry_and_idle_policy instead
  info.timeout_secs = 360000; // 100 hours - effectively disabled
 
  // Create libwebsockets context
  // Log diagnostic info before attempting creation
  log_debug("lws_create_context: port=%u, protocols=%p, options=0x%x", info.port, (void *)info.protocols, info.options);
 
  server->context = lws_create_context(&info);
  if (!server->context) {
    // Capture any OpenSSL errors that may have occurred during context creation
    unsigned long ssl_err = 0;
    char ssl_err_str[NETWORK_WEBSOCKET_SERVER_SSL_ERR_BUFFER_SIZE] = "no OpenSSL errors in queue";
 
    // Extract all errors from OpenSSL error queue
    while ((ssl_err = ERR_get_error()) != 0) {
      ERR_error_string_n(ssl_err, ssl_err_str, sizeof(ssl_err_str));
      log_error("OpenSSL error: %lu: %s", ssl_err, ssl_err_str);
    }
 
    return SET_ERRNO(ERROR_NETWORK_BIND, "Failed to create libwebsockets context (last OpenSSL error: %s)",
                     ssl_err_str);
  }
 
  // Each connection owns a handler until disconnect; provide a worker for every participant.
  server->handler_pool = thread_pool_create_with_workers("websocket_handlers", MAX_SESSION_PARTICIPANTS);
 
  if (!server->handler_pool) {
    lws_context_destroy(server->context);
    server->context = NULL;
    return SET_ERRNO(ERROR_THREAD, "Failed to create WebSocket handler thread pool");
  }
 
  /* Register WebSocket server with named registry */
  char ws_port_name[NETWORK_WEBSOCKET_SERVER_WS_PORT_NAME_BUFFER_SIZE];
  snprintf(ws_port_name, sizeof(ws_port_name), "ws:%d", server->port);
  NAMED_REGISTER(server, ws_port_name, "websocket_server", "0x%tx", NULL);
 
  /* Register server's sync primitives with hierarchical naming */
  NAMED_REGISTER_ATOMIC(&server->running, "is_running", (uintptr_t)(const void *)(server));
 
  /* Register WebSocket context as child of server */
  NAMED_REGISTER_WEBSOCKET(server->context, "context", (uintptr_t)(const void *)(server));
 
  log_info("WebSocket server initialized on port %d with static file serving", config->port);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, websocket_server_config_t::bind_address, websocket_server_config_t::client_handler, websocket_server::context, errno, ERROR_INVALID_PARAM, ERROR_NETWORK_BIND, ERROR_THREAD, websocket_server::handler, websocket_server::handler_pool, log_debug, log_error, log_info, log_warn, lws_log_init_server(), MAX_SESSION_PARTICIPANTS, NAMED_REGISTER, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_WEBSOCKET, NETWORK_WEBSOCKET_SERVER_SSL_ERR_BUFFER_SIZE, NETWORK_WEBSOCKET_SERVER_WS_PORT_NAME_BUFFER_SIZE, NOTICE, websocket_server::port, websocket_server_config_t::port, R_OK, websocket_server::running, SET_ERRNO, thread_pool_create_with_workers(), websocket_server_config_t::tls_cert_path, websocket_server::tls_enabled, websocket_server_config_t::tls_key_path, websocket_server::user_data, and websocket_server_config_t::user_data.

Referenced by network_server_create().

websocket_server_run()

asciichat_error_t websocket_server_run

(

websocket_server_t *

server

)

Run WebSocket server event loop.

Blocks until server is signaled to stop via running flag.

Parameters

server

Server instance

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 831 of file lib/network/websocket/server.c.

                                                                   {
  if (!server || !server->context) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid server");
  }
 
  log_info("WebSocket server starting event loop on port %d", server->port);
 
  // Run libwebsockets event loop
  uint64_t last_service_ns = 0;
  int service_call_count = 0;
  while (atomic_load_bool(&server->running)) {
    // Service libwebsockets with 16ms timeout to match 60 FPS frame rate.
    // This provides frequent event processing (~60 callback invocations per second) so that
    // WebSocket frames queued by the render loop are sent promptly, matching TCP performance.
    // All client connections share this single server context, so a single lws_service() call
    // services fragments and events for all clients simultaneously.
    uint64_t service_start_ns = time_get_ns();
    if (last_service_ns && service_start_ns - last_service_ns > 30 * US_PER_MS_INT) {
      // > 30ms gap between service calls
      double gap_ms = (double)(service_start_ns - last_service_ns) / 1e6;
      log_debug_every(US_PER_SEC_INT, "[LWS_SERVICE_GAP] %.1fms gap between lws_service calls", gap_ms);
    }
    service_call_count++;
    log_debug_every(500 * US_PER_MS_INT, "[LWS_SERVICE] Call #%d, context=%s", service_call_count,
                    NAMED_DESCRIBE(server->context, "websocket_server"));
    int result = lws_service(server->context, 1);
    if (result < 0) {
      log_error("libwebsockets service error: %d", result);
      break;
    }
  }
 
  log_info(
      "WebSocket server event loop exited (context will be destroyed by main thread after handler threads complete)");
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, websocket_server::context, ERROR_INVALID_PARAM, log_debug_every, log_error, log_info, NAMED_DESCRIBE, websocket_server::port, websocket_server::running, SET_ERRNO, US_PER_MS_INT, and US_PER_SEC_INT.