protocol.h File Reference

Server packet processing and protocol implementation. More...

Go to the source code of this file.

Functions
void	handle_image_frame_packet (client_info_t *client, void *data, size_t len)
	Process IMAGE_FRAME packet - store client's video data for rendering.
void	handle_image_frame_h265_packet (client_info_t *client, const void *data, size_t len)
	Process H.265-encoded image frame from client.
void	handle_audio_batch_packet (client_info_t *client, const void *data, size_t len)
	Process AUDIO_BATCH packet - store efficiently batched audio samples.
void	handle_audio_opus_batch_packet (client_info_t *client, const void *data, size_t len)
	Process AUDIO_OPUS_BATCH packet - efficient Opus-encoded audio batch from client.
void	handle_audio_opus_packet (client_info_t *client, const void *data, size_t len)
	Process AUDIO_OPUS packet - decode single Opus frame from client.
void	handle_audio_packet (client_info_t *client, const void *data, size_t len)
	Process AUDIO packet - store single audio sample batch (legacy format)
void	handle_client_capabilities_packet (client_info_t *client, const void *data, size_t len)
	Process CLIENT_CAPABILITIES packet - configure client-specific rendering.
void	handle_size_packet (client_info_t *client, const void *data, size_t len)
	Process terminal size update packet - handle client window resize.
void	handle_ping_packet (client_info_t *client, const void *data, size_t len)
	Handle PING packet - respond with PONG.
void	handle_pong_packet (client_info_t *client, const void *data, size_t len)
	Handle PONG packet - client acknowledged our PING.
void	handle_client_join_packet (client_info_t *client, const void *data, size_t len)
	Process CLIENT_JOIN packet - client announces identity and capabilities.
void	handle_protocol_version_packet (client_info_t *client, const void *data, size_t len)
	Process PROTOCOL_VERSION packet - validate protocol compatibility.
void	handle_stream_start_packet (client_info_t *client, const void *data, size_t len)
	Process STREAM_START packet - client requests to begin media transmission.
void	handle_stream_stop_packet (client_info_t *client, const void *data, size_t len)
	Process STREAM_STOP packet - client requests to halt media transmission.
void	handle_client_leave_packet (client_info_t *client, const void *data, size_t len)
	Process CLIENT_LEAVE packet - handle clean client disconnect.
void	handle_remote_log_packet_from_client (client_info_t *client, const void *data, size_t len)
void	disconnect_client_for_bad_data (client_info_t *client, const char *format,...)
int	send_server_state_to_client (client_info_t *client)
	Send current server state to a specific client.
void	broadcast_clear_console_to_all_clients (void)
	Signal all active clients to clear their displays before next video frame.

Detailed Description

Server packet processing and protocol implementation.

Definition in file src/server/protocol.h.

Function Documentation

broadcast_clear_console_to_all_clients()

void broadcast_clear_console_to_all_clients

(

void

)

Signal all active clients to clear their displays before next video frame.

Sets the needs_display_clear flag for all currently connected and active clients. This is used when the grid layout changes (clients join/leave) to ensure all clients clear their displays before receiving frames with the new layout.

ARCHITECTURE:

• Uses atomic flag (needs_display_clear) instead of packet queue
• Send thread checks flag and sends CLEAR_CONSOLE before next video frame
• Guarantees CLEAR_CONSOLE arrives before new grid layout frame

SYNCHRONIZATION:

• Acquires g_client_manager_rwlock for reading
• Uses atomic operations for flag setting (no mutex needed)
• Thread-safe access to client list

USAGE SCENARIO:

• Called when active video source count changes
• Ensures all clients clear before new grid layout is sent
• Prevents visual artifacts from old content

Note

This function iterates all clients but only flags active ones

Non-blocking - just sets atomic flags

Definition at line 1954 of file server/protocol.c.

                                                  {
  SET_ERRNO(ERROR_INVALID_STATE, "broadcast_clear_console_to_all_clients() called - unexpected usage");
  log_warn("CLEAR_CONSOLE is now sent from render threads, not broadcast");
}

References ERROR_INVALID_STATE, log_warn, and SET_ERRNO.

disconnect_client_for_bad_data()

void disconnect_client_for_bad_data	(	client_info_t *	client,
		const char *	format,
			...
	)

Definition at line 156 of file server/protocol.c.

                                                                                    {
  if (!client) {
    return;
  }
 
  protocol_cleanup_thread_locals();
 
  // Atomically set the disconnect flag and get the old value
  // This ensures only one thread proceeds to disconnect (the first one)
  bool already_requested = atomic_exchange_bool(&client->protocol_disconnect_requested, true);
  if (already_requested) {
    return; // Already disconnecting, don't do it again
  }
 
  char reason[BUFFER_SIZE_SMALL] = {0};
  if (format) {
    va_list args;
    va_start(args, format);
    safe_vsnprintf(reason, sizeof(reason), format, args);
    va_end(args);
  } else {
    SAFE_STRNCPY(reason, "Protocol violation", sizeof(reason));
  }
 
  const char *reason_str = reason[0] != '\0' ? reason : "Protocol violation";
  const char *client_id = client->client_id;
 
  socket_t socket_snapshot = INVALID_SOCKET_VALUE;
  const crypto_context_t *crypto_ctx = NULL;
  acip_transport_t *transport_snapshot = NULL;
 
  mutex_lock(&client->client_state_mutex);
  if (client->socket != INVALID_SOCKET_VALUE) {
    socket_snapshot = client->socket;
    if (client->crypto_initialized) {
      crypto_ctx = crypto_handshake_get_context(&client->crypto_handshake_ctx);
    }
  }
  mutex_unlock(&client->client_state_mutex);
 
  // Get transport reference for WebSocket clients
  mutex_lock(&client->send_mutex);
  transport_snapshot = client->transport;
  mutex_unlock(&client->send_mutex);
 
  // NOTE: Disconnecting a client due to the client's own bad behavior isn't an
  // error for us, it's desired behavior for us, so we simply warn and do not
  // have a need for asciichat_errno here.
  log_warn("Disconnecting client %u due to protocol violation: %s", client_id, reason_str);
 
  if (socket_snapshot != INVALID_SOCKET_VALUE) {
    // Protect socket writes with send_mutex to prevent race with send_thread.
    // This receive_thread and send_thread both write to same socket.
    mutex_lock(&client->send_mutex);
 
    asciichat_error_t log_result =
        log_network_message(socket_snapshot, (const struct crypto_context_t *)crypto_ctx, LOG_ERROR,
                            REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT, "Protocol violation: %s", reason_str);
    if (log_result != ASCIICHAT_OK) {
      log_warn("Failed to send remote log to client %u: %s", client_id, asciichat_error_string(log_result));
    }
 
    asciichat_error_t send_result = packet_send_error(socket_snapshot, crypto_ctx, ERROR_NETWORK_PROTOCOL, reason_str);
    if (send_result != ASCIICHAT_OK) {
      log_warn("Failed to send error packet to client %u: %s", client_id, asciichat_error_string(send_result));
    }
 
    mutex_unlock(&client->send_mutex);
  } else if (transport_snapshot) {
    // For WebSocket clients, try to send error via transport
    log_debug("Sending error to WebSocket client %u via transport", client_id);
    acip_send_error(transport_snapshot, ERROR_NETWORK_PROTOCOL, reason_str);
  }
 
  APP_CALLBACK_VOID(platform_pump_events);
  platform_sleep_ms(500);
 
  log_debug("Setting active=false in disconnect_client_for_bad_data (client_id=%u, reason=%s)", client_id, reason_str);
  atomic_store_bool(&client->active, false);
  atomic_store_bool(&client->shutting_down, true);
  atomic_store_bool(&client->send_thread_running, false);
  atomic_store_bool(&client->video_render_thread_running, false);
  atomic_store_bool(&client->audio_render_thread_running, false);
 
  if (client->audio_queue) {
    packet_queue_stop(client->audio_queue);
  }
 
  mutex_lock(&client->client_state_mutex);
  if (client->socket != INVALID_SOCKET_VALUE) {
    socket_shutdown(client->socket, 2);
    socket_close(client->socket);
    client->socket = INVALID_SOCKET_VALUE;
  }
  mutex_unlock(&client->client_state_mutex);
}

handle_audio_batch_packet()

void handle_audio_batch_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process AUDIO_BATCH packet - store efficiently batched audio samples.

Handles the optimized audio packet format that bundles multiple sample chunks into a single packet. This reduces packet overhead and improves network efficiency for audio streaming.

PACKET STRUCTURE EXPECTED:

• audio_batch_packet_t header:
  • uint32_t batch_count: Number of sample chunks in this batch
  • uint32_t total_samples: Total number of float samples
  • uint32_t sample_rate: Samples per second (typically 44100)
  • uint32_t channels: Number of audio channels (1 = mono)
• float samples[total_samples]: IEEE 754 sample data

PERFORMANCE ADVANTAGES:

• Reduces packet count by 5-10x compared to single audio packets
• Lower network overhead and CPU context switching
• Better burst tolerance with larger buffers

VALIDATION PERFORMED:

• Header size matches audio_batch_packet_t
• Total packet size matches header + samples
• Sample count is within reasonable bounds
• Client is authorized to send audio

BUFFER MANAGEMENT:

• Extracts samples from packet payload
• Stores in client->incoming_audio_buffer (same as single format)
• Ring buffer automatically handles overflow
• mixer.c consumes batched samples identically

ERROR HANDLING:

• Invalid batch headers are logged and packet dropped
• Oversized batches are rejected (prevents DoS)
• Buffer allocation failures are handled gracefully

Parameters

client	Source client providing batched audio data
data	Packet payload containing batch header and samples
len	Total size of packet payload in bytes

Note

This is the preferred audio packet format

Batching is transparent to audio processing pipeline

See also

handle_audio_packet() For legacy single-batch format

AUDIO_BATCH_SAMPLES For maximum batch size constant

Definition at line 1206 of file server/protocol.c.

                                                                                    {
  // Log every audio batch packet reception
  log_debug_every(LOG_RATE_DEFAULT, "Received audio batch packet from client %u (len=%zu, is_sending_audio=%d)",
                  client->client_id, len, atomic_load_bool(&client->is_sending_audio));
 
  VALIDATE_NOTNULL_DATA(client, data, "AUDIO_BATCH");
  VALIDATE_MIN_SIZE(client, len, sizeof(audio_batch_packet_t), "AUDIO_BATCH");
  VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO_BATCH");
 
  // Parse batch header using utility function
  audio_batch_info_t batch_info;
  asciichat_error_t parse_result = audio_parse_batch_header(data, len, &batch_info);
  if (parse_result != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "Failed to parse audio batch header");
    return;
  }
 
  uint32_t packet_batch_count = batch_info.batch_count;
  uint32_t total_samples = batch_info.total_samples;
  uint32_t sample_rate = batch_info.sample_rate;
 
  (void)packet_batch_count;
  (void)sample_rate;
 
  VALIDATE_NONZERO(client, packet_batch_count, "batch_count", "AUDIO_BATCH");
  VALIDATE_NONZERO(client, total_samples, "total_samples", "AUDIO_BATCH");
 
  size_t samples_bytes = 0;
  if (safe_size_mul(total_samples, sizeof(uint32_t), &samples_bytes)) {
    disconnect_client_for_bad_data(client, "AUDIO_BATCH sample size overflow (samples=%u)", total_samples);
    return;
  }
 
  size_t expected_size = sizeof(audio_batch_packet_t) + samples_bytes;
  if (len != expected_size) {
    disconnect_client_for_bad_data(client, "AUDIO_BATCH length mismatch: got %zu expected %zu", len, expected_size);
    return;
  }
 
  // Bounds check to prevent integer overflow on allocation
  // Maximum allowed samples: AUDIO_BATCH_SAMPLES * 2 (2048 samples)
  // This prevents total_samples * sizeof(float) from exceeding 8KB
  const uint32_t MAX_AUDIO_SAMPLES = AUDIO_BATCH_SAMPLES * 2;
  if (total_samples > MAX_AUDIO_SAMPLES) {
    disconnect_client_for_bad_data(client, "AUDIO_BATCH too many samples: %u (max: %u)", total_samples,
                                   MAX_AUDIO_SAMPLES);
    return;
  }
 
  const uint8_t *samples_ptr = (const uint8_t *)data + sizeof(audio_batch_packet_t);
 
  // Safe allocation: total_samples is bounded above, so multiplication won't overflow
  size_t alloc_size = (size_t)total_samples * sizeof(float);
  float *samples = SAFE_MALLOC(alloc_size, float *);
  if (!samples) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for audio sample conversion");
    return;
  }
 
  // Use helper function to dequantize samples
  asciichat_error_t dq_result = audio_dequantize_samples(samples_ptr, total_samples, samples);
  if (dq_result != ASCIICHAT_OK) {
    SAFE_FREE(samples);
    return;
  }
 
#ifndef NDEBUG
  static int recv_count = 0;
  recv_count++;
  if (recv_count % 100 == 0) {
    uint32_t raw0 = bytes_read_u32_unaligned(samples_ptr + 0 * sizeof(uint32_t));
    uint32_t raw1 = bytes_read_u32_unaligned(samples_ptr + 1 * sizeof(uint32_t));
    uint32_t raw2 = bytes_read_u32_unaligned(samples_ptr + 2 * sizeof(uint32_t));
    int32_t scaled0 = (int32_t)NET_TO_HOST_U32(raw0);
    int32_t scaled1 = (int32_t)NET_TO_HOST_U32(raw1);
    int32_t scaled2 = (int32_t)NET_TO_HOST_U32(raw2);
    log_info("RECV: network[0]=0x%08x, network[1]=0x%08x, network[2]=0x%08x", raw0, raw1, raw2);
    log_info("RECV: scaled[0]=%d, scaled[1]=%d, scaled[2]=%d", scaled0, scaled1, scaled2);
    log_info("RECV: samples[0]=%.6f, samples[1]=%.6f, samples[2]=%.6f", samples[0], samples[1], samples[2]);
  }
#endif
 
  if (client->incoming_audio_buffer) {
    asciichat_error_t write_result = audio_ring_buffer_write(client->incoming_audio_buffer, samples, total_samples);
    if (write_result != ASCIICHAT_OK) {
      log_error("Failed to write decoded audio batch to buffer: %s", asciichat_error_string(write_result));
    }
  }
 
  SAFE_FREE(samples);
}

References ASCIICHAT_OK, atomic_load_bool(), AUDIO_BATCH_SAMPLES, audio_dequantize_samples(), audio_parse_batch_header(), audio_ring_buffer_write(), audio_batch_info_t::batch_count, client_info::client_id, disconnect_client_for_bad_data(), ERROR_MEMORY, client_info::incoming_audio_buffer, client_info::is_sending_audio, log_debug_every, log_error, log_info, LOG_RATE_DEFAULT, NET_TO_HOST_U32, SAFE_FREE, SAFE_MALLOC, safe_size_mul, audio_batch_info_t::sample_rate, SET_ERRNO, audio_batch_info_t::total_samples, VALIDATE_AUDIO_STREAM_ENABLED, VALIDATE_MIN_SIZE, VALIDATE_NONZERO, and VALIDATE_NOTNULL_DATA.

handle_audio_packet()

void handle_audio_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process AUDIO packet - store single audio sample batch (legacy format)

Handles the original audio packet format that sends one batch of float samples per packet. This format is less efficient than AUDIO_BATCH but still supported for backward compatibility.

PACKET STRUCTURE:

• float samples[len/sizeof(float)] (IEEE 754 format)
• Sample rate assumed to be 44100 Hz
• Mono audio (single channel)

PERFORMANCE CHARACTERISTICS:

• Less efficient than handle_audio_batch_packet()
• Higher packet overhead per sample
• Still real-time capable for typical loads

BUFFER MANAGEMENT:

• Stores samples in client->incoming_audio_buffer (lock-free ring buffer)
• Buffer overflow drops oldest samples to maintain real-time behavior
• mixer.c consumes samples for multi-client audio mixing

STATE VALIDATION:

• Only processes if client->is_sending_audio is true
• Requires valid buffer pointer and non-zero length
• Handles buffer pointer safely during shutdown

ERROR HANDLING:

• Invalid packets are silently ignored
• Buffer overflow is handled by ring buffer (drops old data)
• Graceful shutdown behavior

Parameters

client	Source client providing audio data
data	Packet payload containing float audio samples
len	Size of packet payload in bytes

Note

Prefer AUDIO_BATCH format for better efficiency

Audio processing happens in mixer threads, not here

See also

handle_audio_batch_packet() For efficient batched format

audio_ring_buffer_write() For storage implementation

Definition at line 1109 of file server/protocol.c.

                                                                              {
  VALIDATE_NOTNULL_DATA(client, data, "AUDIO");
  VALIDATE_AUDIO_ALIGNMENT(client, len, sizeof(float), "AUDIO");
  VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO");
 
  int num_samples = (int)(len / sizeof(float));
  VALIDATE_AUDIO_SAMPLE_COUNT(client, num_samples, AUDIO_SAMPLES_PER_PACKET, "AUDIO");
  VALIDATE_RESOURCE_INITIALIZED(client, client->incoming_audio_buffer, "audio buffer");
 
  const float *samples = (const float *)data;
  asciichat_error_t result = audio_ring_buffer_write(client->incoming_audio_buffer, samples, num_samples);
  if (result != ASCIICHAT_OK) {
    log_error("Failed to write audio samples to buffer: %s", asciichat_error_string(result));
  }
}

References ASCIICHAT_OK, audio_ring_buffer_write(), AUDIO_SAMPLES_PER_PACKET, client_info::incoming_audio_buffer, log_error, VALIDATE_AUDIO_ALIGNMENT, VALIDATE_AUDIO_SAMPLE_COUNT, VALIDATE_AUDIO_STREAM_ENABLED, VALIDATE_NOTNULL_DATA, and VALIDATE_RESOURCE_INITIALIZED.

handle_client_capabilities_packet()

void handle_client_capabilities_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process CLIENT_CAPABILITIES packet - configure client-specific rendering.

This packet contains detailed information about the client's terminal capabilities and preferences. The server uses this data to generate appropriately formatted ASCII art and ANSI escape sequences.

PACKET STRUCTURE EXPECTED:

• terminal_capabilities_packet_t containing:
  • width, height: Terminal dimensions in characters
  • capabilities: Bitmask of terminal features
  • color_level: ANSI color support level (1, 8, 16, 256, 24-bit)
  • color_count: Number of supported colors
  • render_mode: Foreground, background, or half-block rendering
  • term_type: $TERM environment variable value
  • colorterm: $COLORTERM environment variable value
  • utf8_support: Whether terminal supports UTF-8
  • palette_type: ASCII character palette preference
  • palette_custom: Custom character set if PALETTE_CUSTOM

STATE CHANGES PERFORMED:

• Updates client dimensions (width, height)
• Stores complete terminal capabilities structure
• Initializes per-client ASCII palette cache
• Sets client->has_terminal_caps = true

PALETTE INITIALIZATION: The function performs critical palette setup:

1. Determines character set based on palette_type
2. Handles custom palettes if provided
3. Generates luminance-to-character mapping
4. Caches results for fast ASCII generation

THREAD SAFETY:

• All client state updates are mutex-protected
• Uses client->client_state_mutex for atomicity
• Safe to call concurrently with render threads

VALIDATION PERFORMED:

• Packet size matches expected structure
• String fields are safely copied with bounds checking
• Palette initialization is verified
• Network byte order conversion

ERROR HANDLING:

• Invalid packets are logged and ignored
• Palette initialization failures use server defaults
• Missing capabilities default to safe values

INTEGRATION IMPACT:

• render.c uses capabilities for ASCII generation
• Color output depends on client's color_level
• Character selection uses initialized palette

Parameters

client	Target client whose capabilities are being configured
data	Packet payload containing terminal_capabilities_packet_t
len	Size of packet payload in bytes

Note

This packet is typically sent once after CLIENT_JOIN

Capabilities can be updated during the session

Changes affect all subsequent ASCII frame generation

See also

initialize_client_palette() For Character Palettes setup details

terminal_color_level_name() For color level descriptions

Definition at line 1640 of file server/protocol.c.

                                                                                            {
  const char *client_id = client->client_id;
  log_warn("[CAPS_HANDLER] 🟢 CAPS_RECEIVED: client_id=%u, data_ptr=%p, len=%zu bytes", client_id, data, len);
 
  log_debug("[CAPS_HANDLER] Step 1: Validating packet size (expected=%zu, actual=%zu)",
            sizeof(terminal_capabilities_packet_t), len);
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(terminal_capabilities_packet_t), "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Size validation passed");
 
  const terminal_capabilities_packet_t *caps = (const terminal_capabilities_packet_t *)data;
 
  // Extract and validate dimensions
  uint16_t width = NET_TO_HOST_U16(caps->width);
  uint16_t height = NET_TO_HOST_U16(caps->height);
  log_warn("[CAPS_HANDLER] 📐 DIMENSIONS: width=%u, height=%u", width, height);
 
  log_debug("[CAPS_HANDLER] Step 2: Validating width (value=%u, must be nonzero)", width);
  VALIDATE_NONZERO(client, width, "width", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Width nonzero check passed");
 
  log_debug("[CAPS_HANDLER] Step 3: Validating height (value=%u, must be nonzero)", height);
  VALIDATE_NONZERO(client, height, "height", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Height nonzero check passed");
 
  log_debug("[CAPS_HANDLER] Step 4: Validating width range (value=%u, range=1-4096)", width);
  VALIDATE_RANGE(client, width, 1, 4096, "width", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Width range check passed");
 
  log_debug("[CAPS_HANDLER] Step 5: Validating height range (value=%u, range=1-4096)", height);
  VALIDATE_RANGE(client, height, 1, 4096, "height", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Height range check passed");
 
  // Extract and validate color level (0=none, 1=16, 2=256, 3=truecolor)
  uint32_t color_level = NET_TO_HOST_U32(caps->color_level);
  log_debug("[CAPS_HANDLER] Step 6: Validating color_level (value=%u, range=0-3)", color_level);
  VALIDATE_RANGE(client, color_level, 0, 3, "color_level", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Color level check passed");
 
  // Extract and validate render mode (0=foreground, 1=background, 2=half-block)
  uint32_t render_mode = NET_TO_HOST_U32(caps->render_mode);
  log_debug("[CAPS_HANDLER] Step 7: Validating render_mode (value=%u, range=0-2)", render_mode);
  VALIDATE_RANGE(client, render_mode, 0, 2, "render_mode", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Render mode check passed");
 
  // Extract and validate palette type (0-5 are valid, 5=PALETTE_CUSTOM)
  uint32_t palette_type = NET_TO_HOST_U32(caps->palette_type);
  log_debug("[CAPS_HANDLER] Step 8: Validating palette_type (value=%u, range=0-5)", palette_type);
  VALIDATE_RANGE(client, palette_type, 0, 5, "palette_type", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ Palette type check passed");
 
  // Validate desired FPS (1-144)
  log_debug("[CAPS_HANDLER] Step 9: Validating desired_fps (value=%u, range=1-144)", caps->desired_fps);
  VALIDATE_RANGE(client, caps->desired_fps, 1, 144, "desired_fps", "CLIENT_CAPABILITIES");
  log_debug("[CAPS_HANDLER] ✅ FPS check passed");
 
  mutex_lock(&client->client_state_mutex);
 
  client->width = width;
  client->height = height;
 
  log_debug("Client %u dimensions: %ux%u, desired_fps=%u", client->client_id, client->width, client->height,
            caps->desired_fps);
 
  client->terminal_caps.capabilities = NET_TO_HOST_U32(caps->capabilities);
  client->terminal_caps.color_level = color_level;
  client->terminal_caps.color_count = NET_TO_HOST_U32(caps->color_count);
  client->terminal_caps.render_mode = render_mode;
  client->terminal_caps.detection_reliable = caps->detection_reliable;
  client->terminal_caps.wants_background = (render_mode == RENDER_MODE_BACKGROUND);
 
  SAFE_STRNCPY(client->terminal_caps.term_type, caps->term_type, sizeof(client->terminal_caps.term_type));
  SAFE_STRNCPY(client->terminal_caps.colorterm, caps->colorterm, sizeof(client->terminal_caps.colorterm));
 
  client->terminal_caps.utf8_support = NET_TO_HOST_U32(caps->utf8_support);
  client->terminal_caps.palette_type = palette_type;
  SAFE_STRNCPY(client->terminal_caps.palette_custom, caps->palette_custom,
               sizeof(client->terminal_caps.palette_custom));
 
  client->terminal_caps.desired_fps = caps->desired_fps;
  client->terminal_caps.color_filter = (color_filter_t)caps->color_filter;
 
  // Extract wants_padding flag (1=padding enabled, 0=no padding for snapshot/piped modes)
  client->terminal_caps.wants_padding = (caps->wants_padding != 0);
 
  const char *custom_chars =
      (client->terminal_caps.palette_type == PALETTE_CUSTOM && client->terminal_caps.palette_custom[0])
          ? client->terminal_caps.palette_custom
          : NULL;
 
  if (initialize_client_palette((palette_type_t)client->terminal_caps.palette_type, custom_chars,
                                client->client_palette_chars, &client->client_palette_len,
                                client->client_luminance_palette) == 0) {
    client->client_palette_type = (palette_type_t)client->terminal_caps.palette_type;
    client->client_palette_initialized = true;
    log_info("Client %d palette initialized: type=%u, %zu chars, utf8=%u", client->client_id,
             client->terminal_caps.palette_type, client->client_palette_len, client->terminal_caps.utf8_support);
  } else {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to initialize palette for client %d", client->client_id);
    client->client_palette_initialized = false;
  }
 
  // Extract and store codec capabilities
  client->codec_capabilities_video = NET_TO_HOST_U32(caps->codec_capabilities_video);
  client->codec_capabilities_audio = NET_TO_HOST_U32(caps->codec_capabilities_audio);
  log_info("Client %u codec capabilities: video=0x%x audio=0x%x", client->client_id, client->codec_capabilities_video,
           client->codec_capabilities_audio);
 
  client->has_terminal_caps = true;
 
  log_info("Client %u capabilities: %ux%u, color_level=%s (%u colors), caps=0x%x, term=%s, colorterm=%s, "
           "render_mode=%s, reliable=%s, fps=%u, wants_padding=%d",
           client->client_id, client->width, client->height,
           terminal_color_level_name(client->terminal_caps.color_level), client->terminal_caps.color_count,
           client->terminal_caps.capabilities, client->terminal_caps.term_type, client->terminal_caps.colorterm,
           (client->terminal_caps.render_mode == RENDER_MODE_HALF_BLOCK
                ? "half-block"
                : (client->terminal_caps.render_mode == RENDER_MODE_BACKGROUND ? "background" : "foreground")),
           client->terminal_caps.detection_reliable ? "yes" : "no", client->terminal_caps.desired_fps,
           client->terminal_caps.wants_padding);
 
  // Send capabilities acknowledgment to client
  if (client->socket != INVALID_SOCKET_VALUE) {
    log_info_client(client, "Terminal configured: %ux%u, %s, %s mode, %u fps", client->width, client->height,
                    terminal_color_level_name(client->terminal_caps.color_level),
                    (client->terminal_caps.render_mode == RENDER_MODE_HALF_BLOCK
                         ? "half-block"
                         : (client->terminal_caps.render_mode == RENDER_MODE_BACKGROUND ? "background" : "foreground")),
                    client->terminal_caps.desired_fps);
  }
 
  mutex_unlock(&client->client_state_mutex);
 
  log_warn("[CAPS_HANDLER] ✅ CAPS_COMPLETE: client_id=%u - all validations passed, capabilities stored",
           client->client_id);
}

References terminal_capabilities_packet_t::capabilities, terminal_capabilities_t::capabilities, client_info::client_id, client_info::client_luminance_palette, client_info::client_palette_chars, client_info::client_palette_initialized, client_info::client_palette_len, client_info::client_palette_type, client_info::client_state_mutex, client_info::codec_capabilities_audio, terminal_capabilities_packet_t::codec_capabilities_audio, client_info::codec_capabilities_video, terminal_capabilities_packet_t::codec_capabilities_video, terminal_capabilities_packet_t::color_count, terminal_capabilities_t::color_count, terminal_capabilities_packet_t::color_filter, terminal_capabilities_t::color_filter, terminal_capabilities_packet_t::color_level, terminal_capabilities_t::color_level, terminal_capabilities_packet_t::colorterm, terminal_capabilities_t::colorterm, terminal_capabilities_packet_t::desired_fps, terminal_capabilities_t::desired_fps, terminal_capabilities_packet_t::detection_reliable, terminal_capabilities_t::detection_reliable, ERROR_INVALID_STATE, client_info::has_terminal_caps, client_info::height, terminal_capabilities_packet_t::height, initialize_client_palette(), INVALID_SOCKET_VALUE, log_debug, log_info, log_info_client, log_warn, mutex_lock, mutex_unlock, NET_TO_HOST_U16, NET_TO_HOST_U32, terminal_capabilities_packet_t::palette_custom, terminal_capabilities_t::palette_custom, PALETTE_CUSTOM, terminal_capabilities_packet_t::palette_type, terminal_capabilities_t::palette_type, terminal_capabilities_packet_t::render_mode, terminal_capabilities_t::render_mode, RENDER_MODE_BACKGROUND, RENDER_MODE_HALF_BLOCK, SAFE_STRNCPY, SET_ERRNO, client_info::socket, terminal_capabilities_packet_t::term_type, terminal_capabilities_t::term_type, client_info::terminal_caps, terminal_color_level_name(), terminal_capabilities_packet_t::utf8_support, terminal_capabilities_t::utf8_support, VALIDATE_NONZERO, VALIDATE_PACKET_SIZE, VALIDATE_RANGE, terminal_capabilities_t::wants_background, terminal_capabilities_packet_t::wants_padding, terminal_capabilities_t::wants_padding, client_info::width, and terminal_capabilities_packet_t::width.

Referenced by add_client().

handle_client_join_packet()

void handle_client_join_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process CLIENT_JOIN packet - client announces identity and capabilities.

This is the first substantive packet clients send after establishing a TCP connection. It provides the server with essential information for managing the client throughout its session.

PACKET STRUCTURE EXPECTED:

• client_info_packet_t containing:
  • display_name: Human-readable client identifier
  • capabilities: Bitmask of CLIENT_CAP_* flags

STATE CHANGES PERFORMED:

• Updates client->display_name from packet
• Sets client->can_send_video based on CLIENT_CAP_VIDEO
• Sets client->can_send_audio based on CLIENT_CAP_AUDIO
• Sets client->wants_stretch based on CLIENT_CAP_STRETCH

PROTOCOL BEHAVIOR:

• Does NOT automatically start media streams (requires STREAM_START)
• Does NOT send CLEAR_CONSOLE to other clients (prevents flicker)
• Logs client capabilities for debugging

ERROR HANDLING:

• Silently ignores packets with wrong size
• Invalid display names are truncated safely
• Missing capabilities default to false

Parameters

client	Target client whose state will be updated
data	Packet payload (should be client_info_packet_t)
len	Size of packet payload in bytes

Note

This function should only be called by client receive threads

Client state is already protected by receive thread serialization

See also

handle_stream_start_packet() For enabling Media transmission

Definition at line 295 of file server/protocol.c.

                                                                                    {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(client_info_packet_t), "CLIENT_JOIN");
 
  const client_info_packet_t *join_info = (const client_info_packet_t *)data;
 
  // Validate display name is present and not just whitespace
  if (join_info->display_name[0] == '\0') {
    disconnect_client_for_bad_data(client, "CLIENT_JOIN display_name cannot be empty");
    return;
  }
 
  uint32_t capabilities = NET_TO_HOST_U32(join_info->capabilities);
 
  // Validate at least one capability flag is set
  const uint32_t VALID_CAP_MASK = CLIENT_CAP_VIDEO | CLIENT_CAP_AUDIO | CLIENT_CAP_COLOR | CLIENT_CAP_STRETCH;
  VALIDATE_CAPABILITY_FLAGS(client, capabilities, VALID_CAP_MASK, "CLIENT_JOIN");
 
  // Validate no unknown capability bits are set
  VALIDATE_FLAGS_MASK(client, capabilities, VALID_CAP_MASK, "CLIENT_JOIN");
 
  SAFE_STRNCPY(client->display_name, join_info->display_name, MAX_DISPLAY_NAME_LEN - 1);
 
  client->can_send_video = (capabilities & CLIENT_CAP_VIDEO) != 0;
  client->can_send_audio = (capabilities & CLIENT_CAP_AUDIO) != 0;
  client->wants_stretch = (capabilities & CLIENT_CAP_STRETCH) != 0;
 
  log_info("Client %u joined: %s (video=%d, audio=%d, stretch=%d)", client->client_id, client->display_name,
           client->can_send_video, client->can_send_audio, client->wants_stretch);
 
  // Notify client of successful join (encrypted channel)
  if (client->socket != INVALID_SOCKET_VALUE) {
    log_info_client(client, "Joined as '%s' (video=%s, audio=%s)", client->display_name,
                    client->can_send_video ? "yes" : "no", client->can_send_audio ? "yes" : "no");
  }
}

References client_info::can_send_audio, client_info::can_send_video, client_info_packet_t::capabilities, CLIENT_CAP_AUDIO, CLIENT_CAP_COLOR, CLIENT_CAP_STRETCH, CLIENT_CAP_VIDEO, client_info::client_id, disconnect_client_for_bad_data(), client_info_packet_t::display_name, client_info::display_name, INVALID_SOCKET_VALUE, log_info, log_info_client, MAX_DISPLAY_NAME_LEN, NET_TO_HOST_U32, SAFE_STRNCPY, client_info::socket, VALIDATE_CAPABILITY_FLAGS, VALIDATE_FLAGS_MASK, VALIDATE_PACKET_SIZE, and client_info::wants_stretch.

handle_client_leave_packet()

void handle_client_leave_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process CLIENT_LEAVE packet - handle clean client disconnect.

Clients may send this packet before disconnecting to allow the server to log the disconnect reason and perform clean state management. This is optional but preferred over abrupt disconnects.

PACKET STRUCTURE EXPECTED:

• Optional string containing disconnect reason (0-256 bytes)

PROTOCOL BEHAVIOR:

• Client logs the disconnect reason if provided
• Server continues normal disconnect sequence after receiving packet
• Client remains responsible for closing socket

ERROR HANDLING:

• Empty payload is handled gracefully
• Oversized payloads are rejected
• Invalid UTF-8 in reason is handled gracefully (logged as-is)

Parameters

client	Client that sent the leave packet
data	Packet payload (optional reason string)
len	Size of packet payload in bytes (0-256)

Note

This handler doesn't trigger immediate disconnect

Actual disconnect occurs when socket closes

Definition at line 438 of file server/protocol.c.

                                                                                     {
  if (!client) {
    return;
  }
 
  const char *client_id = client->client_id;
 
  if (len == 0) {
    // Empty reason - client disconnecting without explanation
    log_info("Client %u sent leave notification (no reason)", client_id);
  } else if (len <= 256) {
    // Reason provided - extract and log it
    if (!data) {
      SET_ERRNO(ERROR_INVALID_STATE, "Client %u sent leave notification with non-zero length but NULL data", client_id);
      return;
    }
 
    char reason[257] = {0};
    memcpy(reason, data, len);
    reason[len] = '\0';
 
    // Validate reason is printable (handle potential non-UTF8 gracefully)
    bool all_printable = true;
    for (size_t i = 0; i < len; i++) {
      uint8_t c = (uint8_t)reason[i];
      if (c < 32 && c != '\t' && c != '\n') {
        all_printable = false;
        break;
      }
    }
 
    if (all_printable) {
      log_info("Client %u sent leave notification: %s", client_id, reason);
    } else {
      log_info("Client %u sent leave notification (reason contains non-printable characters)", client_id);
    }
  } else {
    // Oversized reason - shouldn't happen with validation.h checks
    log_warn("Client %u sent oversized leave reason (%zu bytes, max 256)", client_id, len);
  }
 
  // Deactivate client to stop processing packets
  // Sets client->active = false immediately - triggers client cleanup procedures
  log_debug("Setting active=false in handle_client_leave_packet (client_id=%u)", client_id);
  atomic_store_bool(&client->active, false);
 
  // Note: We don't disconnect the client here - that happens when socket closes
  // This is just a clean notification before disconnect
}

References client_info::active, atomic_store_bool(), client_info::client_id, ERROR_INVALID_STATE, log_debug, log_info, log_warn, and SET_ERRNO.

handle_image_frame_h265_packet()

void handle_image_frame_h265_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process H.265-encoded image frame from client.

Handles incoming H.265/HEVC-encoded video frames from clients. Frames are decoded to ASCII art and added to the compositing pipeline.

FLOW:

1. Validate packet structure and minimum size
2. Auto-enable video stream on first frame
3. Decode H.265 packet to ASCII grid
4. Convert ASCII to frame buffer format for rendering
5. Store in client's incoming_video_buffer

Parameters

client	Client connection info
data	H.265 packet payload (includes header with frame dimensions)
len	Payload size in bytes

PACKET FORMAT: [flags: u8][width: u16][height: u16][x265_data...]

• flags: H265_FLAG_KEYFRAME, H265_FLAG_SIZE_CHANGE
• width/height: Frame dimensions in characters
• x265_data: H.265-encoded frame data

Definition at line 951 of file server/protocol.c.

                                                                                         {
  // Validate codec capability for H.265 frames
  if (!VIDEO_CODEC_SUPPORTED(client->codec_capabilities_video, VIDEO_CODEC_H265)) {
    log_error("Client %s sent H.265 frame but does not support VIDEO_CODEC_H265 (capabilities=0x%x)", client->client_id,
              client->codec_capabilities_video);
    disconnect_client_for_bad_data(client, "VIDEO_CODEC_H265 not supported by client (capabilities=0x%x)",
                                   client->codec_capabilities_video);
    return;
  }
 
  if (!data || len < 5) {
    disconnect_client_for_bad_data(client, "H265_FRAME payload too small: %zu bytes (min 5)", len);
    return;
  }
 
  // Auto-enable video stream if not already enabled
  // Use atomic_exchange to atomically set flag and check old value
  bool was_sending_video = atomic_exchange_bool(&client->is_sending_video, true);
  if (!was_sending_video) {
    log_info("Client %s auto-enabled H.265 video stream (received IMAGE_FRAME_H265)", client->client_id);
    if (client->socket != INVALID_SOCKET_VALUE) {
      log_info_client(client, "First H.265 video frame received - streaming active");
    }
  }
 
  uint8_t flags = *(const uint8_t *)data;
  bool is_keyframe = (flags & 0x01) != 0;
  bool size_changed = (flags & 0x02) != 0;
 
  log_debug("H265_FRAME: flags=0x%02x, keyframe=%s, size_change=%s, len=%zu", flags, is_keyframe ? "yes" : "no",
            size_changed ? "yes" : "no", len);
 
  if (!client->incoming_video_buffer) {
    log_error("Client %s has no incoming video buffer for H.265 frames", client->client_id);
    return;
  }
 
  // Get H.265 server context (may be NULL during shutdown)
  h265_server_context_t *h265_ctx = g_h265_server;
  if (!h265_ctx) {
    if (!atomic_load_bool(&g_should_exit)) {
      log_error("H.265 codec server context not initialized");
    }
    return;
  }
 
  // Get or create decoder for this client
  uint32_t client_id_num = 0;
  char *end = NULL;
  unsigned long parsed = strtoul(client->client_id, &end, 10);
  if (end != client->client_id && *end == '\0') {
    client_id_num = (uint32_t)parsed;
  } else {
    // Fallback to string hash if can't parse as number
    client_id_num = 0;
    for (int i = 0; client->client_id[i]; i++) {
      client_id_num = (client_id_num * 31 + (unsigned char)client->client_id[i]) & 0xFFFFFFFF;
    }
  }
 
  h265_server_client_t *client_decoder = h265_server_get_client_decoder(h265_ctx, client_id_num);
  if (!client_decoder) {
    log_error("Failed to get H.265 decoder for client %s", client->client_id);
    disconnect_client_for_bad_data(client, "Failed to initialize H.265 decoder");
    return;
  }
 
  // Allocate temporary RGBA buffer for decoding
  // H.265 frames from client are sent as [flags:u8][width:u16][height:u16][h265_data...]
  // Max frame is (256x256 = 65536 pixels) * 4 bytes/pixel = 262KB
  uint8_t *rgba_buf = SAFE_MALLOC(512 * 512 * 4, uint8_t *);
  if (!rgba_buf) {
    log_error("Failed to allocate RGBA buffer for H.265 decoding");
    disconnect_client_for_bad_data(client, "Out of memory for H.265 frame decoding");
    return;
  }
 
  uint16_t frame_width = 0;
  uint16_t frame_height = 0;
  size_t rgba_size = 512 * 512 * 4;
 
  // Decode H.265 packet to RGBA
  asciichat_error_t decode_result = h265_server_decode_and_convert(client_decoder, (const uint8_t *)data, len, rgba_buf,
                                                                   &frame_width, &frame_height, &rgba_size);
 
  if (decode_result != ASCIICHAT_OK) {
    log_error("H.265 decoding failed for client %s: %s", client->client_id, asciichat_error_string(decode_result));
    SAFE_FREE(rgba_buf);
    disconnect_client_for_bad_data(client, "H.265 frame decode error");
    return;
  }
 
  // Write decoded frame to video buffer
  video_frame_t *frame = video_frame_begin_write(client->incoming_video_buffer);
  if (frame && frame->data) {
    memcpy(frame->data, rgba_buf, rgba_size);
    frame->size = rgba_size;
    frame->width = frame_width;
    frame->height = frame_height;
    frame->is_keyframe = is_keyframe;
 
    // Update frame metadata
    frame->receive_timestamp_ns = time_get_realtime_ns();
    frame->sequence_number = client->frames_received++;
 
    log_info_every(100, "RECV_H265 #%lu: client_id=%s size=%zu dims=%ux%u keyframe=%s", frame->sequence_number,
                   client->client_id, rgba_size, frame_width, frame_height, is_keyframe ? "yes" : "no");
 
    video_frame_commit(client->incoming_video_buffer);
  } else {
    log_warn("Failed to get write buffer for client %s (frame=%p, frame->data=%p)", client->client_id, (void *)frame,
             frame ? frame->data : NULL);
  }
 
  SAFE_FREE(rgba_buf);
}

References ASCIICHAT_OK, atomic_exchange_bool(), atomic_load_bool(), client_info::client_id, client_info::codec_capabilities_video, disconnect_client_for_bad_data(), frame, client_info::frames_received, g_h265_server, g_should_exit, h265_server_decode_and_convert(), h265_server_get_client_decoder(), client_info::incoming_video_buffer, INVALID_SOCKET_VALUE, client_info::is_sending_video, log_debug, log_error, log_info, log_info_client, log_info_every, log_warn, SAFE_FREE, SAFE_MALLOC, client_info::socket, time_get_realtime_ns(), VIDEO_CODEC_H265, VIDEO_CODEC_SUPPORTED, video_frame_begin_write(), and video_frame_commit().

handle_image_frame_packet()

void handle_image_frame_packet	(	client_info_t *	client,
		void *	data,
		size_t	len
	)

Process IMAGE_FRAME packet - store client's video data for rendering.

This is the most performance-critical packet handler, processing real-time video data from clients. It validates, stores, and tracks video frames for subsequent ASCII conversion and grid layout.

PACKET STRUCTURE EXPECTED:

• uint32_t width (network byte order)
• uint32_t height (network byte order)
• rgb_pixel_t pixels[width * height] (RGB888 format)

PERFORMANCE CHARACTERISTICS:

• Called at 30fps per active client
• Uses zero-copy storage when possible
• Validates packet size before processing
• Implements frame counting for debug logging

STATE CHANGES PERFORMED:

• Auto-enables client->is_sending_video if not already set
• Increments client->frames_received counter
• Updates client dimensions if changed

BUFFER MANAGEMENT:

• Stores entire packet (including dimensions) in client->incoming_video_buffer
• Uses multi-frame ringbuffer for burst handling
• Buffer overflow drops oldest frames (maintains real-time performance)
• render.c threads consume frames for ASCII conversion

VALIDATION PERFORMED:

• Packet size matches width * height * 3 + 8 bytes
• Width and height are reasonable (prevents memory exhaustion)
• Buffer pointers are valid before access

ERROR HANDLING:

• Invalid packets are logged and dropped
• Buffer overflow is handled gracefully
• Shutdown conditions don't generate error spam

PERFORMANCE OPTIMIZATIONS:

• Debug logging is throttled (every 25000 frames)
• Fast path for common case (valid packet with buffer space)
• Minimal CPU work in receive thread (storage only)

Parameters

client	Source client providing video data
data	Packet payload containing image dimensions and RGB data
len	Total size of packet payload in bytes

Note

This function is called by client receive threads at high frequency

Actual ASCII conversion happens in render threads (render.c)

Frame timestamps are added for synchronization purposes

See also

framebuffer_write_multi_frame() For buffer storage implementation

create_mixed_ascii_frame_for_client() For frame consumption

Definition at line 749 of file server/protocol.c.

                                                                              {
  // Handle incoming image data from client
  // New format: [width:4][height:4][compressed_flag:4][data_size:4][rgb_data:data_size]
  // Old format: [width:4][height:4][rgb_data:w*h*3] (for backward compatibility)
  // Use atomic compare-and-swap to avoid race condition - ensures thread-safe auto-enabling of video stream
 
  log_info("RECV_IMAGE_FRAME: client_id=%u, len=%zu", client->client_id, len);
 
  // Validate codec capability for RGBA frames
  if (!VIDEO_CODEC_SUPPORTED(client->codec_capabilities_video, VIDEO_CODEC_RGBA)) {
    log_error("Client %s sent RGBA frame but does not support VIDEO_CODEC_RGBA (capabilities=0x%x)", client->client_id,
              client->codec_capabilities_video);
    disconnect_client_for_bad_data(client, "VIDEO_CODEC_RGBA not supported by client (capabilities=0x%x)",
                                   client->codec_capabilities_video);
    return;
  }
 
  if (!data || len < sizeof(uint32_t) * 2) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME payload too small: %zu bytes", len);
    return;
  }
  bool was_sending_video = atomic_load_bool(&client->is_sending_video);
  if (!was_sending_video) {
    // Try to atomically enable video sending
    // Use atomic_compare_exchange_strong to avoid spurious failures
    if (atomic_cas_bool(&client->is_sending_video, &was_sending_video, true)) {
      log_info("Client %u auto-enabled video stream (received IMAGE_FRAME)", client->client_id);
      // Notify client that their first video frame was received
      if (client->socket != INVALID_SOCKET_VALUE) {
        log_info_client(client, "First video frame received - streaming active");
      }
    }
  } else {
    // Log periodically to confirm we're receiving frames
    // Use per-client counter protected by client_state_mutex to avoid race conditions
    mutex_lock(&client->client_state_mutex);
    client->frames_received_logged++;
    if (client->frames_received_logged % 25000 == 0) {
      char pretty[64];
      format_bytes_pretty(len, pretty, sizeof(pretty));
      log_debug("Client %u has sent %u IMAGE_FRAME packets (%s)", client->client_id, client->frames_received_logged,
                pretty);
    }
    mutex_unlock(&client->client_state_mutex);
  }
 
  // Parse image dimensions (use memcpy to avoid unaligned access)
  uint32_t img_width_net, img_height_net;
  memcpy(&img_width_net, data, sizeof(uint32_t));
  memcpy(&img_height_net, (char *)data + sizeof(uint32_t), sizeof(uint32_t));
  uint32_t img_width = NET_TO_HOST_U32(img_width_net);
  uint32_t img_height = NET_TO_HOST_U32(img_height_net);
 
  log_debug("IMAGE_FRAME packet: width=%u, height=%u, payload_len=%zu", img_width, img_height, len);
 
  // Validate dimensions using image utility functions
  if (image_validate_dimensions((size_t)img_width, (size_t)img_height) != ASCIICHAT_OK) {
    log_error("IMAGE_FRAME validation failed for dimensions: %u x %u", img_width, img_height);
    disconnect_client_for_bad_data(client, "IMAGE_FRAME invalid dimensions");
    return;
  }
 
  // Calculate RGB buffer size with overflow checking
  size_t rgb_size = 0;
  if (image_calc_rgb_size((size_t)img_width, (size_t)img_height, &rgb_size) != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size calculation failed");
    return;
  }
 
  // Validate final buffer size against maximum
  if (image_validate_buffer_size(rgb_size) != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size exceeds maximum");
    return;
  }
 
  // Only support legacy format: [width:4][height:4][rgb_data:w*h*3]
  if (rgb_size > SIZE_MAX - FRAME_HEADER_SIZE_LEGACY) {
    char size_str[32];
    format_bytes_pretty(rgb_size, size_str, sizeof(size_str));
    disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy packet size overflow: %s", size_str);
    return;
  }
  size_t expected_size = FRAME_HEADER_SIZE_LEGACY + rgb_size;
 
  if (len != expected_size) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME size mismatch: expected %zu bytes got %zu", expected_size, len);
    return;
  }
 
  // Validate legacy format
  asciichat_error_t validate_result = frame_validate_legacy(len, rgb_size);
  if (validate_result != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy validation failed");
    return;
  }
 
  void *rgb_data = (char *)data + FRAME_HEADER_SIZE_LEGACY;
  size_t rgb_data_size = rgb_size;
  bool needs_free = false;
 
  if (client->incoming_video_buffer) {
    // Get the write buffer
    video_frame_t *frame = video_frame_begin_write(client->incoming_video_buffer);
 
    if (frame && frame->data) {
      // Build the packet in the old format for internal storage: [width:4][height:4][rgb_data:w*h*3]
      // Use frame_check_size_overflow to validate overflow before repacking
      asciichat_error_t overflow_check = frame_check_size_overflow(FRAME_HEADER_SIZE_LEGACY, rgb_data_size);
      if (overflow_check != ASCIICHAT_OK) {
        if (needs_free && rgb_data) {
          SAFE_FREE(rgb_data);
        }
        disconnect_client_for_bad_data(client, "IMAGE_FRAME size overflow while repacking");
        return;
      }
      size_t old_packet_size = FRAME_HEADER_SIZE_LEGACY + rgb_data_size;
 
      if (old_packet_size <= MAX_FRAME_BUFFER_SIZE) { // Max frame buffer size
        uint32_t width_net = HOST_TO_NET_U32(img_width);
        uint32_t height_net = HOST_TO_NET_U32(img_height);
 
        // Pack in old format for internal consistency
        memcpy(frame->data, &width_net, sizeof(uint32_t));
        memcpy((char *)frame->data + sizeof(uint32_t), &height_net, sizeof(uint32_t));
        memcpy((char *)frame->data + sizeof(uint32_t) * 2, rgb_data, rgb_data_size);
 
        frame->size = old_packet_size;
        frame->width = img_width;
        frame->height = img_height;
        frame->capture_timestamp_ns = (uint64_t)time(NULL) * NS_PER_SEC_INT;
        frame->sequence_number = ++client->frames_received;
 
        // DEBUG: Compute hash of incoming RGB data to detect duplicates
        uint32_t incoming_rgb_hash = 0;
        for (size_t i = 0; i < rgb_data_size && i < 1000; i++) {
          incoming_rgb_hash = (uint32_t)((uint64_t)incoming_rgb_hash * 31 + ((unsigned char *)rgb_data)[i]);
        }
 
        // Per-client hash tracking (not static!) to avoid cross-client interference
        const char *client_id = client->client_id;
        bool is_new_frame = (incoming_rgb_hash != client->last_received_frame_hash);
 
        if (is_new_frame) {
          log_info("RECV_FRAME #%u NEW: Client %u size=%zu dims=%ux%u hash=0x%08x (prev=0x%08x)",
                   client->frames_received, client_id, rgb_data_size, img_width, img_height, incoming_rgb_hash,
                   client->last_received_frame_hash);
          client->last_received_frame_hash = incoming_rgb_hash;
        } else {
          log_info("RECV_FRAME #%u DUP: Client %u size=%zu dims=%ux%u hash=0x%08x", client->frames_received, client_id,
                   rgb_data_size, img_width, img_height, incoming_rgb_hash);
        }
 
        video_frame_commit(client->incoming_video_buffer);
      } else {
        if (needs_free && rgb_data) {
          SAFE_FREE(rgb_data);
        }
        disconnect_client_for_bad_data(client, "IMAGE_FRAME repacked frame too large (%zu bytes)", old_packet_size);
        return;
      }
    } else {
      log_warn("Failed to get write buffer for client %u (frame=%p, frame->data=%p)", client->client_id, (void *)frame,
               frame ? frame->data : NULL);
    }
  } else {
    // During shutdown, this is expected - don't spam error logs
    if (!atomic_load_bool(&g_should_exit)) {
      SET_ERRNO(ERROR_INVALID_STATE, "Client %u has no incoming video buffer!", client->client_id);
    } else {
      log_debug("Client %u: ignoring video packet during shutdown", client->client_id);
    }
  }
 
  // Clean up decompressed data if allocated
  if (needs_free && rgb_data) {
    SAFE_FREE(rgb_data);
  }
}

References ASCIICHAT_OK, atomic_cas_bool(), atomic_load_bool(), client_info::client_id, client_info::client_state_mutex, client_info::codec_capabilities_video, disconnect_client_for_bad_data(), ERROR_INVALID_STATE, format_bytes_pretty(), frame, frame_check_size_overflow(), FRAME_HEADER_SIZE_LEGACY, frame_validate_legacy(), client_info::frames_received, client_info::frames_received_logged, g_should_exit, HOST_TO_NET_U32, image_calc_rgb_size(), image_validate_buffer_size(), image_validate_dimensions(), client_info::incoming_video_buffer, INVALID_SOCKET_VALUE, client_info::is_sending_video, client_info::last_received_frame_hash, log_debug, log_error, log_info, log_info_client, log_warn, MAX_FRAME_BUFFER_SIZE, mutex_lock, mutex_unlock, NET_TO_HOST_U32, NS_PER_SEC_INT, SAFE_FREE, SET_ERRNO, client_info::socket, VIDEO_CODEC_RGBA, VIDEO_CODEC_SUPPORTED, video_frame_begin_write(), and video_frame_commit().

handle_ping_packet()

void handle_ping_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Handle PING packet - respond with PONG.

Definition at line 660 of file server/protocol.c.

                                                                             {
  (void)data;
  (void)len;
 
  // Serialize the complete PONG write with the sender. TCP packets cannot be
  // sent concurrently without risking byte-stream interleaving.
  mutex_lock(&client->send_mutex);
  if (atomic_load_bool(&client->shutting_down) || !client->transport) {
    mutex_unlock(&client->send_mutex);
    return;
  }
  acip_transport_t *pong_transport = client->transport;
  asciichat_error_t pong_result = acip_send_pong(pong_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));
  }
}

References acip_send_pong(), ASCIICHAT_OK, atomic_load_bool(), client_info::client_id, ERROR_NETWORK, mutex_lock, mutex_unlock, client_info::send_mutex, SET_ERRNO, client_info::shutting_down, and client_info::transport.

handle_pong_packet()

void handle_pong_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Handle PONG packet - client acknowledged our PING.

Definition at line 683 of file server/protocol.c.

                                                                             {
  (void)client;
  (void)data;
  (void)len;
  // No action needed - client acknowledged our PING
}

handle_protocol_version_packet()

void handle_protocol_version_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process PROTOCOL_VERSION packet - validate protocol compatibility.

Clients send this packet to announce their protocol version and capabilities. The server validates that the major version matches and logs any version mismatches for debugging purposes.

PACKET STRUCTURE EXPECTED:

• protocol_version_packet_t containing:
  • protocol_version: Major version number (must match PROTOCOL_VERSION_MAJOR)
  • protocol_revision: Minor version number
  • supports_encryption: Encryption capability flag
  • compression_algorithms: Supported compression bitmask
  • feature_flags: Optional feature flags

VALIDATION PERFORMED:

• Packet size matches sizeof(protocol_version_packet_t)
• Major protocol version matches (PROTOCOL_VERSION_MAJOR)
• Reserved bytes are zero (future-proofing)

ERROR HANDLING:

• Version mismatch is logged but NOT fatal (backward compatibility)
• Invalid packet size triggers disconnect

Parameters

client	Client that sent the packet
data	Packet payload (protocol_version_packet_t)
len	Size of packet payload in bytes

Note

This is typically the first packet in the handshake

Protocol version validation ensures compatibility

Definition at line 362 of file server/protocol.c.

                                                                                         {
  if (!data) {
    disconnect_client_for_bad_data(client, "PROTOCOL_VERSION payload missing");
    return;
  }
 
  if (len != sizeof(protocol_version_packet_t)) {
    disconnect_client_for_bad_data(client, "PROTOCOL_VERSION invalid size: %zu (expected %zu)", len,
                                   sizeof(protocol_version_packet_t));
    return;
  }
 
  const protocol_version_packet_t *version = (const protocol_version_packet_t *)data;
  uint16_t client_major = NET_TO_HOST_U16(version->protocol_version);
  uint16_t client_minor = NET_TO_HOST_U16(version->protocol_revision);
 
  // Validate major version match (minor version can differ for backward compat)
  if (client_major != PROTOCOL_VERSION_MAJOR) {
    log_warn("Client %u protocol version mismatch: client=%u.%u, server=%u.%u", client->client_id, client_major,
             client_minor, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR);
    // Note: We don't disconnect on version mismatch for backward compatibility
    // Clients may be older or newer than server
  } else if (client_minor != PROTOCOL_VERSION_MINOR) {
    log_info("Client %u has different protocol revision: client=%u.%u, server=%u.%u", client->client_id, client_major,
             client_minor, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR);
  }
 
  // Validate reserved bytes are zero
  for (size_t i = 0; i < sizeof(version->reserved); i++) {
    if (version->reserved[i] != 0) {
      log_warn("Client %u sent non-zero reserved bytes in PROTOCOL_VERSION packet", client->client_id);
      // Don't disconnect - reserved bytes may be used in future versions
      break;
    }
  }
 
  // Log supported features
  if (ACIP_CRYPTO_HAS_ENCRYPT(version->supports_encryption)) {
    log_debug("Client %u supports encryption", client->client_id);
  }
  if (version->compression_algorithms != 0) {
    log_debug("Client %u supports compression: 0x%02x", client->client_id, version->compression_algorithms);
  }
  if (version->feature_flags != 0) {
    uint16_t feature_flags = NET_TO_HOST_U16(version->feature_flags);
    log_debug("Client %u supports features: 0x%04x", client->client_id, feature_flags);
  }
}

References ACIP_CRYPTO_HAS_ENCRYPT, client_info::client_id, protocol_version_packet_t::compression_algorithms, disconnect_client_for_bad_data(), protocol_version_packet_t::feature_flags, log_debug, log_info, log_warn, NET_TO_HOST_U16, protocol_version_packet_t::protocol_revision, protocol_version_packet_t::protocol_version, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, protocol_version_packet_t::reserved, and protocol_version_packet_t::supports_encryption.

handle_remote_log_packet_from_client()

void handle_remote_log_packet_from_client	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Definition at line 1125 of file server/protocol.c.

                                                                                               {
  if (!client) {
    return;
  }
 
  log_level_t remote_level = LOG_INFO;
  remote_log_direction_t direction = REMOTE_LOG_DIRECTION_UNKNOWN;
  uint16_t flags = 0;
  char message[MAX_REMOTE_LOG_MESSAGE_LENGTH + 1] = {0};
 
  asciichat_error_t parse_result =
      packet_parse_remote_log(data, len, &remote_level, &direction, &flags, message, sizeof(message), NULL);
  if (parse_result != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "Invalid REMOTE_LOG packet: %s", asciichat_error_string(parse_result));
    return;
  }
 
  if (direction != REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER) {
    disconnect_client_for_bad_data(client, "REMOTE_LOG direction mismatch: %u", direction);
    return;
  }
 
  const bool truncated = (flags & REMOTE_LOG_FLAG_TRUNCATED) != 0;
  const char *display_name = client->display_name[0] ? client->display_name : "(unnamed)";
  const char *client_id = client->client_id;
 
  if (truncated) {
    log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %u \"%s\"] %s [message truncated]", client_id,
            display_name, message);
  } else {
    log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %u \"%s\"] %s", client_id, display_name,
            message);
  }
}

References ASCIICHAT_OK, client_info::client_id, disconnect_client_for_bad_data(), client_info::display_name, LOG_INFO, log_msg(), MAX_REMOTE_LOG_MESSAGE_LENGTH, packet_parse_remote_log(), REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER, REMOTE_LOG_DIRECTION_UNKNOWN, and REMOTE_LOG_FLAG_TRUNCATED.

handle_size_packet()

void handle_size_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process terminal size update packet - handle client window resize.

Clients send this packet when their terminal window is resized, allowing the server to adjust ASCII frame dimensions accordingly. This ensures optimal use of the client's display area.

PACKET STRUCTURE EXPECTED:

• size_packet_t containing:
  • uint16_t width: New terminal width in characters
  • uint16_t height: New terminal height in characters

STATE CHANGES PERFORMED:

• Updates client->width with new dimensions
• Updates client->height with new dimensions
• Thread-safe update using client state mutex

RENDERING IMPACT:

• Subsequent ASCII frames will use new dimensions
• Grid layout calculations will incorporate new size
• No immediate frame regeneration (happens on next cycle)

ERROR HANDLING:

• Invalid packet sizes are ignored silently
• Extreme dimensions are accepted (client responsibility)
• Concurrent updates are handled safely

Parameters

client	Target client whose terminal was resized
data	Packet payload containing new dimensions
len	Size of packet payload (should be sizeof(size_packet_t))

Note

Changes take effect on the next rendering cycle

No validation of reasonable dimension ranges

Definition at line 1810 of file server/protocol.c.

                                                                             {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(size_packet_t), "SIZE");
 
  const size_packet_t *size_pkt = (const size_packet_t *)data;
 
  // Extract and validate new dimensions
  uint16_t width = NET_TO_HOST_U16(size_pkt->width);
  uint16_t height = NET_TO_HOST_U16(size_pkt->height);
 
  VALIDATE_NONZERO(client, width, "width", "SIZE");
  VALIDATE_NONZERO(client, height, "height", "SIZE");
  VALIDATE_RANGE(client, width, 1, 4096, "width", "SIZE");
  VALIDATE_RANGE(client, height, 1, 4096, "height", "SIZE");
 
  mutex_lock(&client->client_state_mutex);
  client->width = width;
  client->height = height;
  mutex_unlock(&client->client_state_mutex);
 
  log_info("Client %u updated terminal size: %ux%u", client->client_id, width, height);
}

References client_info::client_id, client_info::client_state_mutex, client_info::height, size_packet_t::height, log_info, mutex_lock, mutex_unlock, NET_TO_HOST_U16, VALIDATE_NONZERO, VALIDATE_PACKET_SIZE, VALIDATE_RANGE, client_info::width, and size_packet_t::width.

handle_stream_start_packet()

void handle_stream_start_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process STREAM_START packet - client requests to begin media transmission.

Clients send this packet to indicate they're ready to start sending video and/or audio data. The server updates its internal state to expect and process media packets from this client.

PACKET STRUCTURE EXPECTED:

• uint32_t stream_type (network byte order)
• Bitmask containing STREAM_TYPE_VIDEO and/or STREAM_TYPE_AUDIO

STATE CHANGES PERFORMED:

• VIDEO: Records intention to send video (is_sending_video set by first IMAGE_FRAME)
• AUDIO: Sets client->is_sending_audio = true if STREAM_TYPE_AUDIO present
• Enables render threads to include this client in output generation

PROTOCOL BEHAVIOR:

• Client must have announced capabilities via CLIENT_JOIN first
• Server will start processing IMAGE_FRAME and AUDIO packets
• Render threads will begin generating output for this client
• Grid layout will be recalculated to include this client

ERROR HANDLING:

• Ignores packets with incorrect size
• Invalid stream types are silently ignored
• Graceful handling if client lacks necessary capabilities

Parameters

client	Target client starting media transmission
data	Packet payload containing stream type flags
len	Size of packet payload (should be sizeof(uint32_t))

Note

Changes take effect immediately for subsequent media packets

Render threads will detect the state change on their next cycle

See also

handle_stream_stop_packet() For stopping Media transmission

handle_image_frame_packet() For Video to ASCII Conversion data processing

Definition at line 524 of file server/protocol.c.

                                                                                     {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_START");
 
  uint32_t stream_type;
  memcpy(&stream_type, data, sizeof(uint32_t));
  stream_type = NET_TO_HOST_U32(stream_type);
 
  /* Older browser/WASM packet serializers emitted this control payload in
   * host order while the enclosing ACIP header remained in network order.
   * Accept that unambiguous two-bit form so a connected browser is not
   * disconnected before it can send its first frame. */
  const uint32_t VALID_STREAM_MASK = STREAM_TYPE_VIDEO | STREAM_TYPE_AUDIO;
  if ((stream_type & VALID_STREAM_MASK) == 0) {
    uint32_t host_order_stream_type = HOST_TO_NET_U32(stream_type);
    if ((host_order_stream_type & ~VALID_STREAM_MASK) == 0 && host_order_stream_type != 0) {
      log_debug("Normalizing legacy host-order STREAM_START flags 0x%x", stream_type);
      stream_type = host_order_stream_type;
    }
  }
 
  // Validate at least one stream type flag is set
  VALIDATE_CAPABILITY_FLAGS(client, stream_type, VALID_STREAM_MASK, "STREAM_START");
 
  // Validate no unknown stream type bits are set
  VALIDATE_FLAGS_MASK(client, stream_type, VALID_STREAM_MASK, "STREAM_START");
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    atomic_store_bool(&client->is_sending_video, true);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    atomic_store_bool(&client->is_sending_audio, true);
 
    // Create Opus decoder for this client if not already created
    if (!client->opus_decoder) {
      client->opus_decoder = opus_codec_create_decoder(48000);
      if (client->opus_decoder) {
        log_info("Client %u: Opus decoder created (48kHz)", client->client_id);
      } else {
        log_error("Client %u: Failed to create Opus decoder", client->client_id);
      }
    }
  }
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    log_info("Client %u announced video stream (waiting for first frame)", client->client_id);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %u started audio stream", client->client_id);
  }
 
  // Notify client of stream start acknowledgment
  const char *streams = (stream_type & STREAM_TYPE_VIDEO) && (stream_type & STREAM_TYPE_AUDIO)
                            ? "video+audio"
                            : ((stream_type & STREAM_TYPE_VIDEO) ? "video" : "audio");
  // Only send remote log to TCP clients (WebSocket clients have invalid socket)
  if (client->socket != INVALID_SOCKET_VALUE) {
    log_info_client(client, "Stream started: %s", streams);
  }
}

References atomic_store_bool(), client_info::client_id, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, client_info::is_sending_audio, client_info::is_sending_video, log_debug, log_error, log_info, log_info_client, NET_TO_HOST_U32, opus_codec_create_decoder(), client_info::opus_decoder, client_info::socket, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, VALIDATE_CAPABILITY_FLAGS, VALIDATE_FLAGS_MASK, and VALIDATE_PACKET_SIZE.

handle_stream_stop_packet()

void handle_stream_stop_packet	(	client_info_t *	client,
		const void *	data,
		size_t	len
	)

Process STREAM_STOP packet - client requests to halt media transmission.

Clients send this packet to gracefully stop sending video and/or audio data. The server updates its state to exclude this client from active media processing and grid layout calculations.

PACKET STRUCTURE EXPECTED:

• uint32_t stream_type (network byte order)
• Bitmask containing STREAM_TYPE_VIDEO and/or STREAM_TYPE_AUDIO

STATE CHANGES PERFORMED:

• Sets client->is_sending_video = false if STREAM_TYPE_VIDEO present
• Sets client->is_sending_audio = false if STREAM_TYPE_AUDIO present
• Render threads will stop including this client in output

PROTOCOL BEHAVIOR:

• Client remains connected but won't appear in video grid
• Existing buffered media from this client will still be processed
• Grid layout recalculates to exclude this client
• Client can restart streaming with STREAM_START packet

ERROR HANDLING:

• Ignores packets with incorrect size
• Invalid stream types are silently ignored
• Safe to call multiple times or when not streaming

Parameters

client	Target client stopping media transmission
data	Packet payload containing stream type flags
len	Size of packet payload (should be sizeof(uint32_t))

Note

Changes take effect immediately

Render threads will detect the state change on their next cycle

See also

handle_stream_start_packet() For starting Media transmission

Definition at line 619 of file server/protocol.c.

                                                                                    {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_STOP");
 
  uint32_t stream_type;
  memcpy(&stream_type, data, sizeof(uint32_t));
  stream_type = NET_TO_HOST_U32(stream_type);
 
  // Validate at least one stream type flag is set
  const uint32_t VALID_STREAM_MASK = STREAM_TYPE_VIDEO | STREAM_TYPE_AUDIO;
  VALIDATE_CAPABILITY_FLAGS(client, stream_type, VALID_STREAM_MASK, "STREAM_STOP");
 
  // Validate no unknown stream type bits are set
  VALIDATE_FLAGS_MASK(client, stream_type, VALID_STREAM_MASK, "STREAM_STOP");
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    atomic_store_bool(&client->is_sending_video, false);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    atomic_store_bool(&client->is_sending_audio, false);
  }
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    log_info("Client %u stopped video stream", client->client_id);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %u stopped audio stream", client->client_id);
  }
 
  // Notify client of stream stop acknowledgment
  const char *streams = (stream_type & STREAM_TYPE_VIDEO) && (stream_type & STREAM_TYPE_AUDIO)
                            ? "video+audio"
                            : ((stream_type & STREAM_TYPE_VIDEO) ? "video" : "audio");
  // Only send remote log to TCP clients (WebSocket clients have invalid socket)
  if (client->socket != INVALID_SOCKET_VALUE) {
    log_info_client(client, "Stream stopped: %s", streams);
  }
}

References atomic_store_bool(), client_info::client_id, INVALID_SOCKET_VALUE, client_info::is_sending_audio, client_info::is_sending_video, log_info, log_info_client, NET_TO_HOST_U32, client_info::socket, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, VALIDATE_CAPABILITY_FLAGS, VALIDATE_FLAGS_MASK, and VALIDATE_PACKET_SIZE.

send_server_state_to_client()

int send_server_state_to_client

(

client_info_t *

client

)

Send current server state to a specific client.

Generates and queues a SERVER_STATE packet containing information about the current number of connected and active clients. This helps clients understand the multi-user environment and adjust their behavior accordingly.

PACKET CONTENT GENERATED:

• server_state_packet_t containing:
  • connected_client_count: Total clients connected to server
  • active_client_count: Clients actively sending video/audio
  • reserved: Padding for future extensions

USAGE SCENARIOS:

• Initial state after client joins server
• Periodic updates when client count changes
• Response to client requests for server information

IMPLEMENTATION DETAILS:

• Counts active clients by scanning global client manager
• Converts data to network byte order before queuing
• Uses client's video queue for delivery
• Non-blocking operation (queues for later delivery)

THREAD SAFETY:

• Uses reader lock on global client manager
• Safe to call from any thread
• Atomic snapshot of client counts

ERROR HANDLING:

• Returns -1 if client or queue is invalid
• Queue overflow handled by packet_queue_enqueue()
• No side effects on failure

Parameters

client

Target client to receive server state information

Returns

0 on successful queuing, -1 on error

Note

Packet delivery happens asynchronously via send thread

Client count may change between queuing and delivery

See also

broadcast_server_state_to_all_clients() For multi-client updates

Definition at line 1884 of file server/protocol.c.

                                                       {
  if (!client) {
    return -1;
  }
 
  // Count active clients - LOCK OPTIMIZATION: Use atomic reads, no rwlock needed
  int active_count = 0;
  for (int i = 0; i < MAX_CLIENTS; i++) {
    if (atomic_load_bool(&g_client_manager.clients[i].active)) {
      active_count++;
    }
  }
 
  // Prepare server state packet
  server_state_packet_t state;
  state.connected_client_count = active_count;
  state.active_client_count = active_count; // For now, all connected are active
  memset(state.reserved, 0, sizeof(state.reserved));
 
  // Convert to network byte order
  server_state_packet_t net_state;
  net_state.connected_client_count = HOST_TO_NET_U32(state.connected_client_count);
  net_state.active_client_count = HOST_TO_NET_U32(state.active_client_count);
  memset(net_state.reserved, 0, sizeof(net_state.reserved));
 
  // Send server state via ACIP transport
  // Protect socket writes with send_mutex to prevent race with send_thread.
  mutex_lock(&client->send_mutex);
  asciichat_error_t result = acip_send_server_state(client->transport, &net_state);
  mutex_unlock(&client->send_mutex);
 
  if (result != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_NETWORK, "Failed to send server state to client %u: %s", client->client_id,
              asciichat_error_string(result));
    return -1;
  }
 
  log_debug("Sent server state to client %u: %u connected, %u active", client->client_id, state.connected_client_count,
            state.active_client_count);
  return 0;
}

References acip_send_server_state(), client_info::active, server_state_packet_t::active_client_count, ASCIICHAT_OK, atomic_load_bool(), client_info::client_id, client_manager_t::clients, server_state_packet_t::connected_client_count, ERROR_NETWORK, g_client_manager, HOST_TO_NET_U32, log_debug, MAX_CLIENTS, mutex_lock, mutex_unlock, server_state_packet_t::reserved, client_info::send_mutex, SET_ERRNO, and client_info::transport.

Referenced by add_webrtc_client().