server.h File Reference

Go to the source code of this file.

Data Structures
struct	tcp_client_context_t
	Per-client connection context. More...
struct	tcp_server_config_t
	TCP server configuration. More...
struct	tcp_client_entry
	Client registry entry. More...
struct	tcp_server
	TCP server state. More...

Typedefs
typedef struct tcp_client_entry	tcp_client_entry_t
typedef struct tcp_server	tcp_server_t
typedef void(*	tcp_client_cleanup_fn) (void *client_data)
	Callback for client cleanup.
typedef void(*	tcp_client_foreach_fn) (socket_t socket, void *client_data, void *user_arg)
	Callback for iterating over clients.
typedef void(*	tcp_status_update_fn) (void *user_data)
	Callback for periodic status updates.
typedef void *(*	tcp_client_handler_fn) (void *arg)
	Client handler thread function type.

Functions
asciichat_error_t	tcp_server_init (tcp_server_t *server, const tcp_server_config_t *config)
	Initialize TCP server.
asciichat_error_t	tcp_server_run (tcp_server_t *server)
	Run TCP server accept loop.
void	tcp_server_destroy (tcp_server_t *server)
	Shutdown TCP server.
void	tcp_server_set_cleanup_callback (tcp_server_t *server, tcp_client_cleanup_fn cleanup_fn)
	Set client cleanup callback.
asciichat_error_t	tcp_server_add_client (tcp_server_t *server, socket_t socket, void *client_data)
	Add client to registry.
asciichat_error_t	tcp_server_remove_client (tcp_server_t *server, socket_t socket)
	Remove client from registry.
asciichat_error_t	tcp_server_get_client (tcp_server_t *server, socket_t socket, void **out_data)
	Get client data.
void	tcp_server_foreach_client (tcp_server_t *server, tcp_client_foreach_fn callback, void *user_arg)
	Iterate over all clients.
size_t	tcp_server_get_client_count (tcp_server_t *server)
	Get client count.
const char *	tcp_client_context_get_ip (const tcp_client_context_t *ctx, char *buf, size_t len)
	Get formatted IP address from client context.
int	tcp_client_context_get_port (const tcp_client_context_t *ctx)
	Get port number from client context.
void	tcp_server_reject_client (socket_t socket, const char *reason)
	Reject client connection with reason.
asciichat_error_t	tcp_server_spawn_thread (tcp_server_t *server, socket_t client_socket, void *(*thread_func)(void *), void *thread_arg, int stop_id, const char *thread_name)
	Spawn a worker thread for a client.
asciichat_error_t	tcp_server_stop_client_threads (tcp_server_t *server, socket_t client_socket)
	Stop all threads for a client in stop_id order.
asciichat_error_t	tcp_server_get_thread_count (tcp_server_t *server, socket_t client_socket, size_t *count)
	Get thread count for a client.

Typedef Documentation

tcp_client_cleanup_fn

typedef void(* tcp_client_cleanup_fn) (void *client_data)

Callback for client cleanup.

Called when a client is removed from the registry. Use this to free any allocated client_data.

Parameters

client_data

User-provided client data to clean up

Definition at line 86 of file include/ascii-chat/network/tcp/server.h.

tcp_client_entry_t

typedef struct tcp_client_entry tcp_client_entry_t

Definition at line 75 of file include/ascii-chat/network/tcp/server.h.

tcp_client_foreach_fn

typedef void(* tcp_client_foreach_fn) (socket_t socket, void *client_data, void *user_arg)

Callback for iterating over clients.

Parameters

socket	Client socket
client_data	User-provided client data
user_arg	User argument passed to foreach function

Definition at line 95 of file include/ascii-chat/network/tcp/server.h.

tcp_client_handler_fn

typedef void *(* tcp_client_handler_fn) (void *arg)

Client handler thread function type.

Parameters

arg	Pointer to tcp_client_context_t

Returns

NULL (thread exit value)

The handler must:

• Close client_socket when done
• Free the context structure

Definition at line 131 of file include/ascii-chat/network/tcp/server.h.

tcp_server_t

typedef struct tcp_server tcp_server_t

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

tcp_status_update_fn

typedef void(* tcp_status_update_fn) (void *user_data)

Callback for periodic status updates.

Called periodically from the accept loop timeout path. Use this to update status displays, refresh metrics, or perform housekeeping tasks.

Parameters

user_data

User-provided data from config

Definition at line 105 of file include/ascii-chat/network/tcp/server.h.

Function Documentation

tcp_client_context_get_ip()

const char * tcp_client_context_get_ip	(	const tcp_client_context_t *	ctx,
		char *	buf,
		size_t	len
	)

Get formatted IP address from client context.

Extracts and formats the client IP address from the connection context. Works for both IPv4 and IPv6 addresses.

Parameters

ctx	Client context structure
buf	Output buffer for formatted IP string
len	Buffer size (recommend INET6_ADDRSTRLEN = 46 bytes)

Returns

Pointer to buf on success, NULL on error

Definition at line 492 of file lib/network/tcp/server.c.

                                                                                              {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ctx is NULL");
    return NULL;
  }
  if (!buf) {
    SET_ERRNO(ERROR_INVALID_PARAM, "buf is NULL");
    return NULL;
  }
  if (len == 0) {
    SET_ERRNO(ERROR_INVALID_PARAM, "len is 0");
    return NULL;
  }
 
  // Determine address family
  int addr_family = (ctx->addr.ss_family == AF_INET) ? AF_INET : AF_INET6;
 
  // Format IP address using existing utility
  if (format_ip_address(addr_family, (struct sockaddr *)&ctx->addr, buf, len) != 0) {
    return NULL;
  }
 
  return buf;
}

References tcp_client_context_t::addr, ERROR_INVALID_PARAM, format_ip_address(), and SET_ERRNO.

Referenced by acds_client_handler().

tcp_client_context_get_port()

int tcp_client_context_get_port

(

const tcp_client_context_t *

ctx

)

Get port number from client context.

Extracts the client port number from the connection context. Works for both IPv4 and IPv6 addresses.

Parameters

ctx	Client context structure

Returns

Port number (host byte order), or -1 on error

Definition at line 517 of file lib/network/tcp/server.c.

                                                                 {
  if (!ctx) {
    SET_ERRNO(ERROR_INVALID_PARAM, "ctx is NULL");
    return -1;
  }
 
  // Extract port based on address family
  if (ctx->addr.ss_family == AF_INET) {
    struct sockaddr_in *addr_in = (struct sockaddr_in *)&ctx->addr;
    return ntohs(addr_in->sin_port);
  } else if (ctx->addr.ss_family == AF_INET6) {
    struct sockaddr_in6 *addr_in6 = (struct sockaddr_in6 *)&ctx->addr;
    return ntohs(addr_in6->sin6_port);
  }
 
  SET_ERRNO(ERROR_INVALID_STATE, "Unknown address family: %d", ctx->addr.ss_family);
  return -1;
}

References tcp_client_context_t::addr, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, and SET_ERRNO.

tcp_server_add_client()

asciichat_error_t tcp_server_add_client	(	tcp_server_t *	server,
		socket_t	socket,
		void *	client_data
	)

Add client to registry.

Thread-safe registration of a connected client with arbitrary user data. The client_data pointer is stored as-is (caller retains ownership).

Parameters

server	Server structure
socket	Client socket (used as lookup key)
client_data	User-provided client data (can be NULL)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 366 of file lib/network/tcp/server.c.

                                                                                                  {
  if (!server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server is NULL");
  }
 
  if (socket == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "socket is invalid");
  }
 
  // Allocate new entry
  tcp_client_entry_t *entry = SAFE_MALLOC(sizeof(tcp_client_entry_t), tcp_client_entry_t *);
  if (!entry) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate client entry");
  }
 
  entry->socket = socket;
  entry->client_data = client_data;
 
  // Create thread pool for this client
  char pool_name[64];
  SAFE_SNPRINTF(pool_name, sizeof(pool_name), "client_%d", socket);
  entry->threads = thread_pool_create(pool_name);
  if (!entry->threads) {
    SAFE_FREE(entry);
    return SET_ERRNO(ERROR_MEMORY, "Failed to create thread pool for client");
  }
 
  // Add to hash table (thread-safe with write lock)
  rwlock_wrlock(&server->clients_rwlock);
  HASH_ADD(hh, server->clients, socket, sizeof(socket_t), entry);
  rwlock_wrunlock(&server->clients_rwlock);
 
  log_debug("Added client socket=%d to registry", socket);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, tcp_client_entry::client_data, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, ERROR_MEMORY, INVALID_SOCKET_VALUE, log_debug, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SAFE_MALLOC, SAFE_SNPRINTF, SET_ERRNO, tcp_client_entry::socket, thread_pool_create(), and tcp_client_entry::threads.

Referenced by acds_client_handler(), acds_websocket_client_handler(), and add_client().

tcp_server_destroy()

void tcp_server_destroy

(

tcp_server_t *

server

)

Shutdown TCP server.

Closes listen sockets and cleans up resources. Does NOT wait for client threads to exit (caller's responsibility).

Parameters

server

Server structure to clean up

Definition at line 302 of file lib/network/tcp/server.c.

                                              {
  if (!server) {
    return;
  }
 
  log_debug("Shutting down TCP server...");
 
  // Signal server to stop
  atomic_store_bool(&server->running, false);
 
  // Close listen sockets
  if (server->listen_socket != INVALID_SOCKET_VALUE) {
    log_debug("Closing IPv4 listen socket");
    socket_close(server->listen_socket);
    server->listen_socket = INVALID_SOCKET_VALUE;
  }
 
  if (server->listen_socket6 != INVALID_SOCKET_VALUE) {
    log_debug("Closing IPv6 listen socket");
    socket_close(server->listen_socket6);
    server->listen_socket6 = INVALID_SOCKET_VALUE;
  }
 
  // Clean up client registry
  rwlock_wrlock(&server->clients_rwlock);
 
  tcp_client_entry_t *entry = NULL, *tmp = NULL;
  HASH_ITER(hh, server->clients, entry, tmp) {
    // Call cleanup callback if set
    if (server->cleanup_fn && entry->client_data) {
      server->cleanup_fn(entry->client_data);
    }
 
    // Destroy thread pool (stops all threads and frees resources)
    if (entry->threads) {
      thread_pool_destroy(entry->threads);
      entry->threads = NULL;
    }
 
    HASH_DEL(server->clients, entry);
    SAFE_FREE(entry);
  }
  server->clients = NULL;
 
  rwlock_wrunlock(&server->clients_rwlock);
  rwlock_destroy(&server->clients_rwlock);
 
  // Note: This function does NOT wait for client threads to exit
  // Caller is responsible for thread lifecycle management
 
  log_debug("TCP server shutdown complete");
}

References atomic_store_bool(), tcp_server::cleanup_fn, tcp_client_entry::client_data, tcp_server::clients, tcp_server::clients_rwlock, INVALID_SOCKET_VALUE, tcp_server::listen_socket, tcp_server::listen_socket6, log_debug, tcp_server::running, rwlock_destroy(), rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, socket_close(), thread_pool_destroy(), and tcp_client_entry::threads.

Referenced by session_server_like_run().

tcp_server_foreach_client()

void tcp_server_foreach_client	(	tcp_server_t *	server,
		tcp_client_foreach_fn	callback,
		void *	user_arg
	)

Iterate over all clients.

Thread-safe iteration over all connected clients. The callback is called once per client while holding the clients mutex.

Parameters

server	Server structure
callback	Function to call for each client
user_arg	User argument passed to callback

Definition at line 461 of file lib/network/tcp/server.c.

                                                                                                     {
  if (!server || !callback) {
    return;
  }
 
  rwlock_rdlock(&server->clients_rwlock);
 
  tcp_client_entry_t *entry, *tmp;
  HASH_ITER(hh, server->clients, entry, tmp) {
    callback(entry->socket, entry->client_data, user_arg);
  }
 
  rwlock_rdunlock(&server->clients_rwlock);
}

References tcp_client_entry::client_data, tcp_server::clients, tcp_server::clients_rwlock, rwlock_rdlock, rwlock_rdunlock, and tcp_client_entry::socket.

Referenced by signaling_broadcast(), signaling_relay_ice(), and signaling_relay_sdp().

tcp_server_get_client()

asciichat_error_t tcp_server_get_client	(	tcp_server_t *	server,
		socket_t	socket,
		void **	out_data
	)

Get client data.

Thread-safe lookup of client data by socket.

Parameters

server	Server structure
socket	Client socket to look up
out_data	Output pointer for client data (set to NULL if not found)

Returns

ASCIICHAT_OK if found, ERROR_NOT_FOUND if not in registry

Definition at line 439 of file lib/network/tcp/server.c.

                                                                                                {
  if (!server || !out_data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server or out_data is NULL");
  }
 
  rwlock_rdlock(&server->clients_rwlock);
 
  tcp_client_entry_t *entry = NULL;
  HASH_FIND(hh, server->clients, &socket, sizeof(socket_t), entry);
 
  if (!entry) {
    *out_data = NULL;
    rwlock_rdunlock(&server->clients_rwlock);
    return SET_ERRNO(ERROR_INVALID_STATE, "Client socket=%d not in registry", socket);
  }
 
  *out_data = entry->client_data;
  rwlock_rdunlock(&server->clients_rwlock);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, tcp_client_entry::client_data, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, rwlock_rdlock, rwlock_rdunlock, and SET_ERRNO.

tcp_server_get_client_count()

size_t tcp_server_get_client_count

(

tcp_server_t *

server

)

Get client count.

Thread-safe count of connected clients.

Parameters

server

Server structure

Returns

Number of clients in registry

Definition at line 476 of file lib/network/tcp/server.c.

                                                         {
  if (!server) {
    return 0;
  }
 
  rwlock_rdlock(&server->clients_rwlock);
  size_t count = HASH_COUNT(server->clients);
  rwlock_rdunlock(&server->clients_rwlock);
 
  return count;
}

References tcp_server::clients, tcp_server::clients_rwlock, rwlock_rdlock, and rwlock_rdunlock.

Referenced by acds_client_handler(), acds_server_shutdown(), acds_websocket_client_handler(), and ui_status_gather().

tcp_server_get_thread_count()

asciichat_error_t tcp_server_get_thread_count	(	tcp_server_t *	server,
		socket_t	client_socket,
		size_t *	count
	)

Get thread count for a client.

Thread-safe count of worker threads spawned for a client.

Parameters

	server	Server structure
	client_socket	Client socket to query
[out]	count	Output pointer for thread count (set to 0 if client not found)

Returns

ASCIICHAT_OK on success, ERROR_NOT_FOUND if client not in registry

Definition at line 637 of file lib/network/tcp/server.c.

                                                                                                           {
  if (!server || !count) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server or count is NULL");
  }
 
  if (client_socket == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "client_socket is invalid");
  }
 
  *count = 0;
 
  // Find client entry
  rwlock_rdlock(&server->clients_rwlock);
  tcp_client_entry_t *entry = NULL;
  HASH_FIND(hh, server->clients, &client_socket, sizeof(socket_t), entry);
 
  if (!entry) {
    rwlock_rdunlock(&server->clients_rwlock);
    return SET_ERRNO(ERROR_NOT_FOUND, "Client socket=%d not in registry", client_socket);
  }
 
  // Get thread count from pool
  if (entry->threads) {
    *count = thread_pool_get_count(entry->threads);
  }
 
  rwlock_rdunlock(&server->clients_rwlock);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, INVALID_SOCKET_VALUE, rwlock_rdlock, rwlock_rdunlock, SET_ERRNO, thread_pool_get_count(), and tcp_client_entry::threads.

tcp_server_init()

asciichat_error_t tcp_server_init	(	tcp_server_t *	server,
		const tcp_server_config_t *	config
	)

Initialize TCP server.

Creates and binds TCP sockets according to configuration. At least one of IPv4 or IPv6 must be successfully bound.

Parameters

server	Server structure to initialize
config	Server configuration

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 105 of file lib/network/tcp/server.c.

                                                                                           {
  if (!server || !config) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server or config is NULL");
  }
 
  // Note: client_handler is optional - some users may use tcp_server just for socket setup
  // and implement their own accept loop (like ascii-chat server with its cleanup logic)
 
  // Initialize server state
  memset(server, 0, sizeof(*server));
  server->listen_socket = INVALID_SOCKET_VALUE;
  server->listen_socket6 = INVALID_SOCKET_VALUE;
  atomic_store_bool(&server->running, true);
  server->config = *config; // Copy config
 
  // Initialize client registry
  server->clients = NULL; // uthash starts with NULL
  server->cleanup_fn = NULL;
  if (rwlock_init(&server->clients_rwlock, "clients") != 0) {
    return SET_ERRNO(ERROR_THREAD, "Failed to initialize clients read-write lock");
  }
 
  // Determine which IP versions to bind
  bool should_bind_ipv4 = config->bind_ipv4;
  bool should_bind_ipv6 = config->bind_ipv6;
 
  // Bind IPv4 socket if requested
  if (should_bind_ipv4) {
    const char *ipv4_addr = (config->ipv4_address && config->ipv4_address[0] != '\0') ? config->ipv4_address : NULL;
    server->listen_socket = bind_and_listen(ipv4_addr, AF_INET, config->port);
 
    if (server->listen_socket == INVALID_SOCKET_VALUE) {
      log_warn("Failed to bind IPv4 socket");
    }
  }
 
  // Bind IPv6 socket if requested
  if (should_bind_ipv6) {
    const char *ipv6_addr = (config->ipv6_address && config->ipv6_address[0] != '\0') ? config->ipv6_address : NULL;
    server->listen_socket6 = bind_and_listen(ipv6_addr, AF_INET6, config->port);
 
    if (server->listen_socket6 == INVALID_SOCKET_VALUE) {
      log_warn("Failed to bind IPv6 socket");
    }
  }
 
  // Ensure at least one socket bound successfully
  if (server->listen_socket == INVALID_SOCKET_VALUE && server->listen_socket6 == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_NETWORK_BIND, "Failed to bind any sockets (IPv4 and IPv6 both failed)");
  }
 
  /* Register server with named registry, identified by port */
  char port_name[32];
  snprintf(port_name, sizeof(port_name), "server:%d", server->config.port);
  NAMED_REGISTER(server, port_name, "tcp_server", "0x%tx", NULL);
 
  /* Register server's sync primitives with hierarchical naming */
  NAMED_REGISTER_RWLOCK(&server->clients_rwlock, "clients_rwlock", (uintptr_t)(const void *)(server));
  NAMED_REGISTER_ATOMIC(&server->running, "is_running", (uintptr_t)(const void *)(server));
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_store_bool(), tcp_server_config_t::bind_ipv4, tcp_server_config_t::bind_ipv6, tcp_server::cleanup_fn, tcp_server::clients, tcp_server::clients_rwlock, tcp_server::config, ERROR_INVALID_PARAM, ERROR_NETWORK_BIND, ERROR_THREAD, INVALID_SOCKET_VALUE, tcp_server_config_t::ipv4_address, tcp_server_config_t::ipv6_address, tcp_server::listen_socket, tcp_server::listen_socket6, log_warn, NAMED_REGISTER, NAMED_REGISTER_ATOMIC, NAMED_REGISTER_RWLOCK, tcp_server_config_t::port, tcp_server::running, rwlock_init(), and SET_ERRNO.

Referenced by session_server_like_run().

tcp_server_reject_client()

void tcp_server_reject_client	(	socket_t	socket,
		const char *	reason
	)

Reject client connection with reason.

Helper for rejecting clients due to rate limits, capacity limits, etc. Logs the rejection reason and closes the socket.

Parameters

socket	Client socket to close
reason	Human-readable rejection reason (for logging)

Definition at line 536 of file lib/network/tcp/server.c.

                                                                   {
  if (socket == INVALID_SOCKET_VALUE) {
    SET_ERRNO(ERROR_INVALID_PARAM, "socket is INVALID_SOCKET_VALUE");
    return;
  }
 
  log_warn("Rejecting client connection: %s", reason ? reason : "unknown reason");
  socket_close(socket);
}

References ERROR_INVALID_PARAM, INVALID_SOCKET_VALUE, log_warn, SET_ERRNO, and socket_close().

Referenced by acds_client_handler().

tcp_server_remove_client()

asciichat_error_t tcp_server_remove_client	(	tcp_server_t *	server,
		socket_t	socket
	)

Remove client from registry.

Thread-safe removal of a client. If a cleanup callback is set, it will be called with the client_data before removal.

Parameters

server	Server structure
socket	Client socket to remove

Returns

ASCIICHAT_OK if removed, ERROR_NOT_FOUND if not in registry

Definition at line 402 of file lib/network/tcp/server.c.

                                                                                  {
  if (!server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server is NULL");
  }
 
  rwlock_wrlock(&server->clients_rwlock);
 
  tcp_client_entry_t *entry = NULL;
  HASH_FIND(hh, server->clients, &socket, sizeof(socket_t), entry);
 
  if (!entry) {
    rwlock_wrunlock(&server->clients_rwlock);
    // Already removed (e.g., during shutdown) - this is fine
    log_debug("Client socket=%d already removed from registry", socket);
    return ASCIICHAT_OK;
  }
 
  // Call cleanup callback if set
  if (server->cleanup_fn && entry->client_data) {
    server->cleanup_fn(entry->client_data);
  }
 
  // Destroy thread pool (stops all threads and frees resources)
  if (entry->threads) {
    thread_pool_destroy(entry->threads);
    entry->threads = NULL;
  }
 
  HASH_DEL(server->clients, entry);
  SAFE_FREE(entry);
 
  rwlock_wrunlock(&server->clients_rwlock);
 
  log_debug("Removed client socket=%d from registry", socket);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, tcp_server::cleanup_fn, tcp_client_entry::client_data, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, log_debug, rwlock_wrlock, rwlock_wrunlock, SAFE_FREE, SET_ERRNO, thread_pool_destroy(), and tcp_client_entry::threads.

Referenced by acds_client_handler(), and acds_websocket_client_handler().

tcp_server_run()

asciichat_error_t tcp_server_run

(

tcp_server_t *

server

)

Run TCP server accept loop.

Accepts client connections and spawns handler threads. Blocks until server->running is set to false.

Uses select() with timeout to handle dual-stack sockets and allow responsive shutdown. If a status_update_fn is configured, it will be called periodically on each select() timeout.

Parameters

server

Initialized server structure

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 168 of file lib/network/tcp/server.c.

                                                       {
  if (!server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server is NULL");
  }
 
  if (!server->config.client_handler) {
    return SET_ERRNO(ERROR_INVALID_PARAM,
                     "client_handler is required for tcp_server_run() - use custom accept loop if handler is NULL");
  }
 
  log_debug("TCP server starting accept loop...");
 
  while (atomic_load_bool(&server->running)) {
    // Build fd_set for select()
    fd_set read_fds;
    socket_fd_zero(&read_fds);
    socket_t max_fd = 0;
 
    // Add IPv4 socket if available
    if (server->listen_socket != INVALID_SOCKET_VALUE) {
      socket_fd_set(server->listen_socket, &read_fds);
      max_fd = server->listen_socket > max_fd ? server->listen_socket : max_fd;
    }
 
    // Add IPv6 socket if available
    if (server->listen_socket6 != INVALID_SOCKET_VALUE) {
      socket_fd_set(server->listen_socket6, &read_fds);
      max_fd = server->listen_socket6 > max_fd ? server->listen_socket6 : max_fd;
    }
 
    // Use timeout from config (defaults to 1 second if not set)
    // Convert double seconds to tv_sec and tv_usec
    double timeout_sec_double = server->config.accept_timeout_sec > 0 ? server->config.accept_timeout_sec : 1.0;
    time_t timeout_sec = (time_t)timeout_sec_double;
    long timeout_usec = (long)((timeout_sec_double - timeout_sec) * (double)US_PER_SEC_INT);
    struct timeval timeout = {.tv_sec = timeout_sec, .tv_usec = timeout_usec};
 
    int select_result = socket_select((int)max_fd, &read_fds, NULL, NULL, &timeout);
 
    if (select_result < 0) {
      // Check if interrupted by signal (expected during shutdown)
      int err = socket_get_last_error();
      if (err == EINTR) {
        // Signal interrupt (e.g., SIGTERM, SIGINT) - check running flag and continue
        log_debug("select() interrupted by signal");
        continue;
      }
      // Actual error - socket_get_error_string() returns last socket error
      log_error("select() failed in accept loop: %s (errno=%d)", socket_get_error_string(), err);
      continue;
    }
 
    if (select_result == 0) {
      // Timeout - invoke status update callback if configured
      if (server->config.status_update_fn) {
        server->config.status_update_fn(server->config.status_update_data);
      }
      log_debug_every(5000, "select() timeout on TCP server (no incoming connections)");
      continue;
    }
 
    // Check which socket has incoming connection
    socket_t ready_socket = INVALID_SOCKET_VALUE;
    if (server->listen_socket != INVALID_SOCKET_VALUE && socket_fd_isset(server->listen_socket, &read_fds)) {
      ready_socket = server->listen_socket;
    } else if (server->listen_socket6 != INVALID_SOCKET_VALUE && socket_fd_isset(server->listen_socket6, &read_fds)) {
      ready_socket = server->listen_socket6;
    }
 
    if (ready_socket == INVALID_SOCKET_VALUE) {
      // Spurious wakeup
      continue;
    }
 
    // Accept connection
    struct sockaddr_storage client_addr;
    socklen_t client_addr_len = sizeof(client_addr);
    socket_t client_socket = accept(ready_socket, (struct sockaddr *)&client_addr, &client_addr_len);
    if (socket_is_valid(client_socket)) {
      NAMED_REGISTER_SOCKET(client_socket, "tcp_client", NULL);
    }
 
    if (client_socket == INVALID_SOCKET_VALUE) {
      log_warn("Failed to accept connection");
      continue;
    }
 
    // Format client IP for logging
    char client_ip[INET6_ADDRSTRLEN];
    // NOLINTNEXTLINE(clang-analyzer-core.UndefinedBinaryOperatorResult) - client_addr filled by accept()
    int addr_family = (client_addr.ss_family == AF_INET) ? AF_INET : AF_INET6;
    if (format_ip_address(addr_family, (struct sockaddr *)&client_addr, client_ip, sizeof(client_ip)) != ASCIICHAT_OK) {
      SAFE_STRNCPY(client_ip, "(unknown)", sizeof(client_ip));
    }
 
    log_debug("Accepted connection from %s", client_ip);
 
    // Allocate client context
    tcp_client_context_t *ctx = SAFE_MALLOC(sizeof(tcp_client_context_t), tcp_client_context_t *);
    if (!ctx) {
      log_error("Failed to allocate client context");
      socket_close(client_socket);
      continue;
    }
 
    ctx->client_socket = client_socket;
    ctx->addr = client_addr;
    ctx->addr_len = client_addr_len;
    ctx->user_data = server->config.user_data;
 
    // Spawn client handler thread
    // Handler is responsible for:
    // 1. Allocating client_data
    // 2. Calling tcp_server_add_client() to register
    // 3. Spawning additional worker threads via tcp_server_spawn_thread() if needed
    // 4. Processing client requests
    // 5. Calling tcp_server_remove_client() on disconnect
    // 6. Closing socket and freeing ctx
    asciichat_thread_t thread;
    if (asciichat_thread_create(&thread, "tcp_client", server->config.client_handler, ctx) != 0) {
      log_error("Failed to create client handler thread for %s", client_ip);
      SAFE_FREE(ctx);
      socket_close(client_socket);
      continue;
    }
 
    // Thread is detached (handler is responsible for cleanup)
    (void)thread; // Suppress unused warning
  }
 
  log_debug("TCP server accept loop exited");
  return ASCIICHAT_OK;
}

References tcp_server_config_t::accept_timeout_sec, tcp_client_context_t::addr, tcp_client_context_t::addr_len, ASCIICHAT_OK, asciichat_thread_create, atomic_load_bool(), tcp_server_config_t::client_handler, tcp_client_context_t::client_socket, tcp_server::config, EINTR, ERROR_INVALID_PARAM, format_ip_address(), INVALID_SOCKET_VALUE, tcp_server::listen_socket, tcp_server::listen_socket6, log_debug, log_debug_every, log_error, log_warn, NAMED_REGISTER_SOCKET, tcp_server::running, SAFE_FREE, SAFE_MALLOC, SAFE_STRNCPY, SET_ERRNO, socket_close(), socket_fd_isset(), socket_fd_set(), socket_fd_zero(), socket_get_error_string(), socket_get_last_error(), socket_is_valid(), socket_select(), tcp_server_config_t::status_update_data, tcp_server_config_t::status_update_fn, US_PER_SEC_INT, tcp_client_context_t::user_data, and tcp_server_config_t::user_data.

Referenced by session_server_like_run().

tcp_server_set_cleanup_callback()

void tcp_server_set_cleanup_callback	(	tcp_server_t *	server,
		tcp_client_cleanup_fn	cleanup_fn
	)

Set client cleanup callback.

Sets the callback function that will be called when a client is removed from the registry. Use this to free any allocated client_data.

Parameters

server	Server structure
cleanup_fn	Cleanup callback (or NULL to disable)

Definition at line 359 of file lib/network/tcp/server.c.

                                                                                             {
  if (!server) {
    return;
  }
  server->cleanup_fn = cleanup_fn;
}

References tcp_server::cleanup_fn.

tcp_server_spawn_thread()

asciichat_error_t tcp_server_spawn_thread	(	tcp_server_t *	server,
		socket_t	client_socket,
		void *(*)(void *)	thread_func,
		void *	thread_arg,
		int	stop_id,
		const char *	thread_name
	)

Spawn a worker thread for a client.

Creates and tracks a new worker thread for the specified client. Threads are identified by stop_id for ordered cleanup - lower stop_id values are stopped first when the client disconnects.

Example stop_id ordering:

• stop_id=1: Receive thread (stop first to prevent new data)
• stop_id=2: Render threads (stop after receive)
• stop_id=3: Send thread (stop last after all processing done)

Parameters

server	Server structure
client_socket	Client socket to spawn thread for
thread_func	Thread function to execute
thread_arg	Argument passed to thread function
stop_id	Cleanup order (lower = stop first)
thread_name	Thread name for debugging (max 63 chars)

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 550 of file lib/network/tcp/server.c.

                                                                                                  {
  if (!server || !thread_func) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server or thread_func is NULL");
  }
 
  // For WebRTC clients (no socket): create thread directly without TCP server thread pool tracking
  // This allows render threads to work for both TCP and WebRTC clients
  if (client_socket == INVALID_SOCKET_VALUE) {
    // Extract thread handle from thread_arg if it's a client_info_t
    // We need to store the thread handle somewhere, but for now just create the thread
    // The caller must manage the thread handle directly for WebRTC clients
    log_debug("Spawning standalone thread '%s' (no socket, WebRTC client)", thread_name ? thread_name : "unnamed");
 
    // For WebRTC clients, we can't use thread_pool since there's no socket entry
    // Instead, create the thread directly - the caller must handle the thread
    // This is a hack to allow reusing tcp_server_spawn_thread for WebRTC
    // In the future, consider a unified thread management system
    asciichat_thread_t temp_thread;
    asciichat_error_t result = asciichat_thread_create(&temp_thread, "tcp_worker", thread_func, thread_arg);
    if (result != ASCIICHAT_OK) {
      return result;
    }
 
    // Note: temp_thread handle is lost here, but the thread is running
    // The caller must manage thread lifecycle for WebRTC clients differently
    (void)temp_thread; // Suppress unused warning
    return ASCIICHAT_OK;
  }
 
  // Find client entry
  rwlock_rdlock(&server->clients_rwlock);
  tcp_client_entry_t *entry = NULL;
  HASH_FIND(hh, server->clients, &client_socket, sizeof(socket_t), entry);
 
  if (!entry) {
    rwlock_rdunlock(&server->clients_rwlock);
    return SET_ERRNO(ERROR_NOT_FOUND, "Client socket=%d not in registry", client_socket);
  }
 
  // Spawn thread in client's thread pool
  asciichat_error_t result = thread_pool_spawn(entry->threads, thread_func, thread_arg, stop_id, thread_name);
 
  rwlock_rdunlock(&server->clients_rwlock);
 
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  size_t thread_count = thread_pool_get_count(entry->threads);
  log_debug("Spawned thread '%s' (stop_id=%d) for client socket=%d (total_threads=%zu)",
            thread_name ? thread_name : "unnamed", stop_id, client_socket, thread_count);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, asciichat_thread_create, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, INVALID_SOCKET_VALUE, log_debug, rwlock_rdlock, rwlock_rdunlock, SET_ERRNO, thread_pool_get_count(), thread_pool_spawn(), and tcp_client_entry::threads.

Referenced by create_client_render_threads().

tcp_server_stop_client_threads()

asciichat_error_t tcp_server_stop_client_threads	(	tcp_server_t *	server,
		socket_t	client_socket
	)

Stop all threads for a client in stop_id order.

Stops all worker threads spawned for the specified client. Threads are stopped in ascending stop_id order (lower values first). Joins each thread to ensure it has fully exited before proceeding.

Parameters

server	Server structure
client_socket	Client socket whose threads to stop

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 606 of file lib/network/tcp/server.c.

                                                                                               {
  if (!server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "server is NULL");
  }
 
  if (client_socket == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "client_socket is invalid");
  }
 
  // Find client entry
  rwlock_rdlock(&server->clients_rwlock);
  tcp_client_entry_t *entry = NULL;
  HASH_FIND(hh, server->clients, &client_socket, sizeof(socket_t), entry);
 
  if (!entry) {
    rwlock_rdunlock(&server->clients_rwlock);
    return SET_ERRNO(ERROR_NOT_FOUND, "Client socket=%d not in registry", client_socket);
  }
 
  // Stop all threads in client's thread pool (in stop_id order)
  asciichat_error_t result = ASCIICHAT_OK;
  if (entry->threads) {
    result = thread_pool_stop_all(entry->threads);
  }
 
  rwlock_rdunlock(&server->clients_rwlock);
 
  log_debug("All threads stopped for client socket=%d", client_socket);
  return result;
}

References ASCIICHAT_OK, tcp_server::clients, tcp_server::clients_rwlock, ERROR_INVALID_PARAM, ERROR_NOT_FOUND, INVALID_SOCKET_VALUE, log_debug, rwlock_rdlock, rwlock_rdunlock, SET_ERRNO, thread_pool_stop_all(), and tcp_client_entry::threads.

Referenced by remove_client().