client.h File Reference

Per-client state management and lifecycle orchestration. More...

Go to the source code of this file.

Data Structures
struct	client_manager_t
	Global client manager structure for server-side client coordination. More...

Typedefs
typedef struct server_context_t	server_context_t

Functions
int	add_client (server_context_t *server_ctx, socket_t socket, const char *client_ip, int port)
int	add_webrtc_client (server_context_t *server_ctx, acip_transport_t *transport, const char *client_ip)
int	remove_client (server_context_t *server_ctx, uint32_t client_id)
client_info_t *	find_client_by_id (uint32_t client_id)
client_info_t *	find_client_by_socket (socket_t socket)
	Find client by socket descriptor using linear search.
void	cleanup_client_media_buffers (client_info_t *client)
void	cleanup_client_packet_queues (client_info_t *client)
void *	client_receive_thread (void *arg)
void	stop_client_threads (client_info_t *client)
int	process_encrypted_packet (client_info_t *client, packet_type_t *type, void **data, size_t *len, uint32_t *sender_id)
void	process_decrypted_packet (client_info_t *client, packet_type_t type, void *data, size_t len)
void	initialize_client_info (client_info_t *client)

Variables
client_manager_t	g_client_manager
	Global client manager singleton - central coordination point.
rwlock_t	g_client_manager_rwlock
	Reader-writer lock protecting the global client manager.

Detailed Description

Per-client state management and lifecycle orchestration.

This header provides server-specific client management functions. The client_info_t structure and network logging macros are defined in lib/network/client.h.

Definition in file src/server/client.h.

Typedef Documentation

server_context_t

typedef struct server_context_t server_context_t

Definition at line 16 of file src/server/client.h.

Function Documentation

add_client()

int add_client	(	server_context_t *	server_ctx,
		socket_t	socket,
		const char *	client_ip,
		int	port
	)

add_webrtc_client()

int add_webrtc_client	(	server_context_t *	server_ctx,
		acip_transport_t *	transport,
		const char *	client_ip
	)

cleanup_client_media_buffers()

void cleanup_client_media_buffers

(

client_info_t *

client

)

Definition at line 1851 of file src/server/client.c.

                                                         {
  if (!client) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Client is NULL");
    return;
  }
 
  if (client->incoming_video_buffer) {
    video_frame_buffer_destroy(client->incoming_video_buffer);
    client->incoming_video_buffer = NULL;
  }
 
  // Clean up outgoing video buffer (for ASCII frames)
  if (client->outgoing_video_buffer) {
    video_frame_buffer_destroy(client->outgoing_video_buffer);
    client->outgoing_video_buffer = NULL;
  }
 
  // Clean up pre-allocated send buffer
  if (client->send_buffer) {
    SAFE_FREE(client->send_buffer);
    client->send_buffer = NULL;
    client->send_buffer_size = 0;
  }
 
  if (client->incoming_audio_buffer) {
    audio_ring_buffer_destroy(client->incoming_audio_buffer);
    client->incoming_audio_buffer = NULL;
  }
 
  // Clean up Opus decoder
  if (client->opus_decoder) {
    opus_codec_destroy((opus_codec_t *)client->opus_decoder);
    client->opus_decoder = NULL;
  }
}

References audio_ring_buffer_destroy(), ERROR_INVALID_PARAM, client_info::incoming_audio_buffer, client_info::incoming_video_buffer, opus_codec_destroy(), client_info::opus_decoder, client_info::outgoing_video_buffer, SAFE_FREE, client_info::send_buffer, client_info::send_buffer_size, SET_ERRNO, and video_frame_buffer_destroy().

cleanup_client_packet_queues()

void cleanup_client_packet_queues

(

client_info_t *

client

)

Definition at line 1887 of file src/server/client.c.

                                                         {
  if (!client)
    return;
 
  if (client->audio_queue) {
    packet_queue_destroy(client->audio_queue);
    client->audio_queue = NULL;
  }
 
  // Video now uses double buffer, cleaned up in cleanup_client_media_buffers
}

References client_info::audio_queue, and packet_queue_destroy().

client_receive_thread()

void * client_receive_thread

(

void *

arg

)

Definition at line 1240 of file src/server/client.c.

                                       {
  client_info_t *client = (client_info_t *)arg;
 
  // CRITICAL: Validate client pointer immediately before any access
  // This prevents crashes if remove_client() has zeroed the client struct
  // while the thread was still starting at RtlUserThreadStart
  if (!client) {
    log_error("Invalid client info in receive thread (NULL pointer)");
    return NULL;
  }
 
  if (atomic_load(&client->protocol_disconnect_requested)) {
    log_debug("Receive thread for client %u exiting before start (protocol disconnect requested)",
              atomic_load(&client->client_id));
    return NULL;
  }
 
  // Check if client_id is 0 (client struct has been zeroed by remove_client)
  // This must be checked BEFORE accessing any client fields
  if (atomic_load(&client->client_id) == 0) {
    log_debug("Receive thread: client_id is 0, client struct may have been zeroed, exiting");
    return NULL;
  }
 
  // Additional validation: check socket is valid
  if (client->socket == INVALID_SOCKET_VALUE) {
    log_error("Invalid client socket in receive thread");
    return NULL;
  }
 
  // Enable thread cancellation for clean shutdown
  // Thread cancellation not available in platform abstraction
  // Threads should exit when g_server_should_exit is set
 
  log_debug("Started receive thread for client %u (%s)", atomic_load(&client->client_id), client->display_name);
 
  // DEBUG: Check loop entry conditions
  bool should_exit = atomic_load(&g_server_should_exit);
  bool is_active = atomic_load(&client->active);
  socket_t sock = client->socket;
  log_debug("RECV_THREAD_START: Client %u conditions: should_exit=%d, active=%d, socket=%d (INVALID=%d)",
            atomic_load(&client->client_id), should_exit, is_active, sock, INVALID_SOCKET_VALUE);
 
  while (!atomic_load(&g_server_should_exit) && atomic_load(&client->active) &&
         client->socket != INVALID_SOCKET_VALUE) {
 
    // Use unified secure packet reception with auto-decryption
    // CRITICAL: Check client_id is still valid before accessing transport
    // This prevents accessing freed memory if remove_client() has zeroed the client struct
    if (atomic_load(&client->client_id) == 0) {
      log_debug("Client client_id reset, exiting receive thread");
      break;
    }
 
    // Receive and dispatch packet using ACIP transport API
    // This combines packet reception, decryption, parsing, handler dispatch, and cleanup
    asciichat_error_t acip_result =
        acip_server_receive_and_dispatch(client->transport, client, &g_acip_server_callbacks);
 
    // Check if shutdown was requested during the network call
    if (atomic_load(&g_server_should_exit)) {
      break;
    }
 
    // Handle receive errors
    if (acip_result != ASCIICHAT_OK) {
      // Check error type to determine if we should disconnect
      asciichat_error_context_t err_ctx;
      if (HAS_ERRNO(&err_ctx)) {
        if (err_ctx.code == ERROR_NETWORK) {
          // Network error or EOF - client disconnected
          log_debug("Client %u disconnected (network error): %s", client->client_id, err_ctx.context_message);
          break;
        } else if (err_ctx.code == ERROR_CRYPTO) {
          // Security violation
          log_error_client(client,
                           "SECURITY VIOLATION: Unencrypted packet when encryption required - terminating connection");
          atomic_store(&g_server_should_exit, true);
          break;
        }
      }
 
      // Other errors - log but don't disconnect immediately
      log_warn("ACIP receive/dispatch failed for client %u: %s", client->client_id,
               asciichat_error_string(acip_result));
    }
  }
 
  // Mark client as inactive and stop all threads
  // CRITICAL: Must stop render threads when client disconnects
  // OPTIMIZED: Use atomic operations for thread control flags (lock-free)
  atomic_store(&client->active, false);
  atomic_store(&client->send_thread_running, false);
  atomic_store(&client->video_render_thread_running, false);
  atomic_store(&client->audio_render_thread_running, false);
 
  // Don't call remove_client() from the receive thread itself - this causes a deadlock
  // because main thread may be trying to join this thread via remove_client()
  // The main cleanup code will handle client removal after threads exit
 
  log_debug("Receive thread for client %u terminated, signaled all threads to stop", client->client_id);
 
  // Clean up thread-local error context before exit
  asciichat_errno_cleanup();
 
  return NULL;
}

References acip_server_receive_and_dispatch(), client_info::active, asciichat_errno_cleanup(), ASCIICHAT_OK, client_info::audio_render_thread_running, client_info::client_id, asciichat_error_context_t::code, asciichat_error_context_t::context_message, client_info::display_name, ERROR_CRYPTO, ERROR_NETWORK, g_server_should_exit, HAS_ERRNO, INVALID_SOCKET_VALUE, log_debug, log_error, log_error_client, log_warn, client_info::protocol_disconnect_requested, client_info::send_thread_running, should_exit(), client_info::socket, client_info::transport, and client_info::video_render_thread_running.

find_client_by_id()

client_info_t * find_client_by_id

(

uint32_t

client_id

)

Referenced by broadcast_server_state_to_all_clients(), crypto_server_cleanup_client(), crypto_server_decrypt_packet(), crypto_server_encrypt_packet(), crypto_server_get_context(), and crypto_server_is_ready().

find_client_by_socket()

client_info_t * find_client_by_socket

(

socket_t

socket

)

Find client by socket descriptor using linear search.

This function provides socket-based client lookup, primarily used during connection establishment before client IDs are assigned. Less efficient than find_client_by_id() but necessary for socket-based operations.

PERFORMANCE CHARACTERISTICS:

• Time Complexity: O(n) where n = number of active clients
• Space Complexity: O(1)
• Thread Safety: Internally acquires read lock on g_client_manager_rwlock

USAGE PATTERNS:

• Connection establishment during add_client() processing
• Socket error handling and cleanup operations
• Debugging and diagnostic functions

Parameters

socket

Platform-abstracted socket descriptor to search for

Returns

Pointer to client_info_t if found, NULL if not found

Note

Only searches active clients (avoids returning stale entries)

Caller should use snapshot pattern when accessing returned client data

Definition at line 289 of file src/server/client.c.

                                                      {
  rwlock_rdlock(&g_client_manager_rwlock);
 
  for (int i = 0; i < MAX_CLIENTS; i++) {
    if (g_client_manager.clients[i].socket == socket && atomic_load(&g_client_manager.clients[i].active)) {
      client_info_t *client = &g_client_manager.clients[i];
      rwlock_rdunlock(&g_client_manager_rwlock);
      return client;
    }
  }
 
  rwlock_rdunlock(&g_client_manager_rwlock);
  return NULL;
}

References client_info::active, client_manager_t::clients, g_client_manager, g_client_manager_rwlock, MAX_CLIENTS, rwlock_rdlock, rwlock_rdunlock, and client_info::socket.

initialize_client_info()

void initialize_client_info

(

client_info_t *

client

)

process_decrypted_packet()

void process_decrypted_packet	(	client_info_t *	client,
		packet_type_t	type,
		void *	data,
		size_t	len
	)

Process a decrypted packet from a client

Parameters

client	Client info structure
type	Packet type
data	Packet data
len	Packet length

Definition at line 2390 of file src/server/client.c.

                                                                                                 {
  // Rate limiting: Check and record packet-specific rate limits
  if (g_rate_limiter) {
    if (!check_and_record_packet_rate_limit(g_rate_limiter, client->client_ip, client->socket, type)) {
      // Rate limit exceeded - error response already sent by utility function
      return;
    }
  }
 
  switch (type) {
  case PACKET_TYPE_PROTOCOL_VERSION:
    handle_protocol_version_packet(client, data, len);
    break;
 
  case PACKET_TYPE_IMAGE_FRAME:
    handle_image_frame_packet(client, data, len);
    break;
 
  case PACKET_TYPE_AUDIO:
    handle_audio_packet(client, data, len);
    break;
 
  case PACKET_TYPE_AUDIO_BATCH:
    handle_audio_batch_packet(client, data, len);
    break;
 
  case PACKET_TYPE_AUDIO_OPUS:
    // Single-frame Opus packet: 16-byte header (sample_rate + frame_duration + reserved) + Opus data
    // Extract metadata and forward to mixer
    if (len >= 16) {
      const uint8_t *payload = (const uint8_t *)data;
      // Use unaligned read helpers - network data may not be aligned
      int sample_rate = (int)NET_TO_HOST_U32(read_u32_unaligned(payload));
      int frame_duration = (int)NET_TO_HOST_U32(read_u32_unaligned(payload + 4));
      // Reserved bytes at offset 8-15
      size_t opus_size = len - 16;
 
      if (opus_size > 0 && opus_size <= 1024 && sample_rate == 48000 && frame_duration == 20) {
        // Create a synthetic Opus batch packet (frame_count=1) and process it
        // This reuses the batch handler logic
        uint8_t batch_buffer[1024 + 20]; // Max Opus + header
        uint8_t *batch_ptr = batch_buffer;
 
        // Write batch header (batch_buffer is stack-aligned, writes are safe)
        write_u32_unaligned(batch_ptr, HOST_TO_NET_U32((uint32_t)sample_rate));
        batch_ptr += 4;
        write_u32_unaligned(batch_ptr, HOST_TO_NET_U32((uint32_t)frame_duration));
        batch_ptr += 4;
        write_u32_unaligned(batch_ptr, HOST_TO_NET_U32(1)); // frame_count = 1
        batch_ptr += 4;
        memset(batch_ptr, 0, 4); // reserved
        batch_ptr += 4;
 
        // Write frame size
        write_u16_unaligned(batch_ptr, HOST_TO_NET_U16((uint16_t)opus_size));
        batch_ptr += 2;
 
        // Write Opus data
        memcpy(batch_ptr, payload + 16, opus_size);
        batch_ptr += opus_size;
 
        // Process as batch packet
        size_t batch_size = (size_t)(batch_ptr - batch_buffer);
        handle_audio_opus_batch_packet(client, batch_buffer, batch_size);
      }
    }
    break;
 
  case PACKET_TYPE_AUDIO_OPUS_BATCH:
    handle_audio_opus_batch_packet(client, data, len);
    break;
 
  case PACKET_TYPE_CLIENT_JOIN:
    handle_client_join_packet(client, data, len);
    break;
 
  case PACKET_TYPE_CLIENT_LEAVE:
    handle_client_leave_packet(client, data, len);
    break;
 
  case PACKET_TYPE_STREAM_START:
    handle_stream_start_packet(client, data, len);
    break;
 
  case PACKET_TYPE_STREAM_STOP:
    handle_stream_stop_packet(client, data, len);
    break;
 
  case PACKET_TYPE_CLIENT_CAPABILITIES:
    handle_client_capabilities_packet(client, data, len);
    break;
 
  case PACKET_TYPE_PING: {
    // Respond with PONG using ACIP transport
    // CRITICAL: Protect socket write with send_mutex to prevent concurrent writes
    mutex_lock(&client->send_mutex);
    asciichat_error_t pong_result = acip_send_pong(client->transport);
    mutex_unlock(&client->send_mutex);
    if (pong_result != ASCIICHAT_OK) {
      SET_ERRNO(ERROR_NETWORK, "Failed to send PONG response to client %u: %s", client->client_id,
                asciichat_error_string(pong_result));
    }
    break;
  }
 
  case PACKET_TYPE_PONG:
    // Client acknowledged our PING - no action needed
    break;
 
  case PACKET_TYPE_REMOTE_LOG:
    handle_remote_log_packet_from_client(client, data, len);
    break;
 
  default:
    disconnect_client_for_bad_data(client, "Unknown packet type: %d (len=%zu)", type, len);
    break;
  }
}

References acip_send_pong(), ASCIICHAT_OK, check_and_record_packet_rate_limit(), client_info::client_id, client_info::client_ip, disconnect_client_for_bad_data(), ERROR_NETWORK, g_rate_limiter, handle_audio_batch_packet(), handle_audio_opus_batch_packet(), handle_audio_packet(), handle_client_capabilities_packet(), handle_client_join_packet(), handle_client_leave_packet(), handle_image_frame_packet(), handle_protocol_version_packet(), handle_remote_log_packet_from_client(), handle_stream_start_packet(), handle_stream_stop_packet(), HOST_TO_NET_U16, HOST_TO_NET_U32, mutex_lock, mutex_unlock, NET_TO_HOST_U32, PACKET_TYPE_AUDIO, PACKET_TYPE_AUDIO_BATCH, PACKET_TYPE_AUDIO_OPUS, PACKET_TYPE_AUDIO_OPUS_BATCH, PACKET_TYPE_CLIENT_CAPABILITIES, PACKET_TYPE_CLIENT_JOIN, PACKET_TYPE_CLIENT_LEAVE, PACKET_TYPE_IMAGE_FRAME, PACKET_TYPE_PING, PACKET_TYPE_PONG, PACKET_TYPE_PROTOCOL_VERSION, PACKET_TYPE_REMOTE_LOG, PACKET_TYPE_STREAM_START, PACKET_TYPE_STREAM_STOP, read_u32_unaligned, client_info::send_mutex, SET_ERRNO, client_info::socket, client_info::transport, write_u16_unaligned, and write_u32_unaligned.

process_encrypted_packet()

int process_encrypted_packet	(	client_info_t *	client,
		packet_type_t *	type,
		void **	data,
		size_t *	len,
		uint32_t *	sender_id
	)

Process an encrypted packet from a client

Parameters

client	Client info structure
type	Pointer to packet type (will be updated with decrypted type)
data	Pointer to packet data (will be updated with decrypted data)
len	Pointer to packet length (will be updated with decrypted length)
sender_id	Pointer to sender ID (will be updated with decrypted sender ID)

Returns

0 on success, -1 on error

Definition at line 1923 of file src/server/client.c.

                                                  {
  if (!crypto_server_is_ready(client->client_id)) {
    log_error("Received encrypted packet but crypto not ready for client %u", client->client_id);
    buffer_pool_free(NULL, *data, *len);
    *data = NULL;
    return -1;
  }
 
  // Store original allocation size before it gets modified
  size_t original_alloc_size = *len;
  void *decrypted_data = buffer_pool_alloc(NULL, original_alloc_size);
  size_t decrypted_len;
  int decrypt_result = crypto_server_decrypt_packet(client->client_id, (const uint8_t *)*data, *len,
                                                    (uint8_t *)decrypted_data, original_alloc_size, &decrypted_len);
 
  if (decrypt_result != 0) {
    SET_ERRNO(ERROR_CRYPTO, "Failed to process encrypted packet from client %u (result=%d)", client->client_id,
              decrypt_result);
    buffer_pool_free(NULL, *data, original_alloc_size);
    buffer_pool_free(NULL, decrypted_data, original_alloc_size);
    *data = NULL;
    return -1;
  }
 
  // Replace encrypted data with decrypted data
  // Use original allocation size for freeing the encrypted buffer
  buffer_pool_free(NULL, *data, original_alloc_size);
 
  *data = decrypted_data;
  *len = decrypted_len;
 
  // Now process the decrypted packet by parsing its header
  if (*len < sizeof(packet_header_t)) {
    SET_ERRNO(ERROR_CRYPTO, "Decrypted packet too small for header from client %u", client->client_id);
    buffer_pool_free(NULL, *data, *len);
    *data = NULL;
    return -1;
  }
 
  packet_header_t *header = (packet_header_t *)*data;
  *type = (packet_type_t)NET_TO_HOST_U16(header->type);
  *sender_id = NET_TO_HOST_U32(header->client_id);
 
  // Adjust data pointer to skip header
  *data = (uint8_t *)*data + sizeof(packet_header_t);
  *len -= sizeof(packet_header_t);
 
  return 0;
}

References buffer_pool_alloc(), buffer_pool_free(), client_info::client_id, packet_header_t::client_id, crypto_server_decrypt_packet(), crypto_server_is_ready(), ERROR_CRYPTO, log_error, NET_TO_HOST_U16, NET_TO_HOST_U32, SET_ERRNO, and packet_header_t::type.

remove_client()

int remove_client	(	server_context_t *	server_ctx,
		uint32_t	client_id
	)

Referenced by server_main().

stop_client_threads()

void stop_client_threads

(

client_info_t *

client

)

Definition at line 1832 of file src/server/client.c.

                                                {
  if (!client) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Client is NULL");
    return;
  }
 
  // Signal threads to stop
  atomic_store(&client->active, false);
  atomic_store(&client->send_thread_running, false);
 
  // Wait for threads to finish
  if (asciichat_thread_is_initialized(&client->send_thread)) {
    asciichat_thread_join(&client->send_thread, NULL);
  }
  if (asciichat_thread_is_initialized(&client->receive_thread)) {
    asciichat_thread_join(&client->receive_thread, NULL);
  }
}

References client_info::active, asciichat_thread_is_initialized(), asciichat_thread_join(), ERROR_INVALID_PARAM, client_info::receive_thread, client_info::send_thread, client_info::send_thread_running, and SET_ERRNO.

Variable Documentation

g_client_manager

client_manager_t g_client_manager

extern

Global client manager singleton - central coordination point.

This is the primary data structure for managing all connected clients. It serves as the bridge between main.c's connection accept loop and the per-client threading architecture.

STRUCTURE COMPONENTS:

• clients[]: Array backing storage for client_info_t structs
• client_hashtable: O(1) lookup table for client_id -> client_info_t*
• client_count: Current number of active clients
• mutex: Legacy mutex (mostly replaced by rwlock)
• next_client_id: Monotonic counter for unique client identification

THREAD SAFETY: Protected by g_client_manager_rwlock for concurrent access

Definition at line 189 of file src/server/client.c.

{0};

g_client_manager_rwlock

rwlock_t g_client_manager_rwlock

extern

Reader-writer lock protecting the global client manager.

This lock enables high-performance concurrent access patterns:

• Multiple threads can read client data simultaneously (stats, rendering)
• Only one thread can modify client data at a time (add/remove operations)
• Eliminates contention between read-heavy operations

USAGE PATTERN:

• Read operations: rwlock_rdlock() for client lookups, stats gathering
• Write operations: rwlock_wrlock() for add_client(), remove_client()
• Always acquire THIS lock before per-client mutexes (lock ordering)

Definition at line 204 of file src/server/client.c.

{0};