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_h264_packet (client_info_t *client, const void *data, size_t len)
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)
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.
asciichat_error_t	handle_runtime_settings (client_info_t *client, const void *data, size_t length)

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 1821 of file server/protocol.c.

                                                  {
  SET_ERRNO(ERROR_INVALID_STATE, "Unexpected console clear broadcast");
  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 167 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;
 
  log_warn("Disconnecting client %s due to protocol violation: %s", client_id, reason_str);
  mutex_lock(&client->send_mutex);
  if (client->transport)
    acip_send_error(client->transport, ERROR_NETWORK_PROTOCOL, reason_str);
  mutex_unlock(&client->send_mutex);
 
  log_debug("Setting active=false (client_id=%s, reason=%s)", client_id, reason_str);
  atomic_store_bool(&client->active, false);
  atomic_store_bool(&client->shutting_down, true);
  network_connection_request_stop(client->network_connection);
  atomic_store_bool(&client->video_render_thread_running, false);
  atomic_store_bool(&client->audio_render_thread_running, false);
}

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 1175 of file server/protocol.c.

                                                                                    {
  // Log every audio batch packet reception
  log_debug_every(LOG_RATE_DEFAULT, "Received audio batch packet from client %s (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;
  if (sample_rate != AUDIO_SAMPLE_RATE || (batch_info.channels != 1 && batch_info.channels != 2) ||
      total_samples % batch_info.channels) {
    disconnect_client_for_bad_data(client, "Unsupported PCM audio format");
    return;
  }
 
  (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 * AUDIO_CHANNELS * 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_debug_every(US_PER_SEC_INT, "RECV: network[0]=0x%08x, network[1]=0x%08x, network[2]=0x%08x", raw0, raw1, raw2);
    log_debug_every(US_PER_SEC_INT, "RECV: scaled[0]=%d, scaled[1]=%d, scaled[2]=%d", scaled0, scaled1, scaled2);
    log_debug_every(US_PER_SEC_INT, "RECV: samples[0]=%.6f, samples[1]=%.6f, samples[2]=%.6f", samples[0], samples[1],
                    samples[2]);
  }
#endif
 
  if (client->incoming_audio_buffer) {
    uint32_t frames = total_samples / batch_info.channels;
    (void)audio_convert_channels(samples, frames, batch_info.channels, samples, AUDIO_CHANNELS);
    asciichat_error_t write_result =
        audio_ring_buffer_write(client->incoming_audio_buffer, samples, frames * AUDIO_CHANNELS);
    if (write_result != ASCIICHAT_OK) {
      log_error("Failed to write decoded audio batch to buffer: %s", asciichat_error_format(NULL, write_result));
    }
  }
 
  SAFE_FREE(samples);
}

References asciichat_error_format(), ASCIICHAT_OK, AUDIO_BATCH_SAMPLES, AUDIO_CHANNELS, audio_convert_channels(), audio_dequantize_samples(), audio_parse_batch_header(), audio_ring_buffer_write(), AUDIO_SAMPLE_RATE, audio_batch_info_t::batch_count, audio_batch_info_t::channels, 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_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, US_PER_SEC_INT, VALIDATE_AUDIO_STREAM_ENABLED, VALIDATE_MIN_SIZE, VALIDATE_NONZERO, and VALIDATE_NOTNULL_DATA.

handle_audio_opus_batch_packet()

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.

Handles batched Opus-encoded audio frames sent by the client. This provides ~98% bandwidth reduction compared to raw PCM audio while maintaining excellent audio quality.

PACKET STRUCTURE EXPECTED:

• opus_batch_header_t (16 bytes):
  • sample_rate (4 bytes)
  • frame_duration (4 bytes)
  • frame_count (4 bytes)
  • reserved (4 bytes)
• Opus encoded data (variable size, typically ~60 bytes/frame @ 24kbps)

PROCESSING FLOW:

1. Parse batch header
2. Decode each Opus frame back to PCM samples (OPUS_FRAME_SAMPLES samples/frame @ 48kHz)
3. Write decoded samples to client's incoming audio buffer

PERFORMANCE:

• Bandwidth: ~60 bytes/frame vs ~3840 bytes/frame for raw PCM (64:1 compression)
• Quality: Excellent at 24 kbps VOIP mode
• Latency: 20ms frames for real-time audio

Parameters

client	Client that sent the audio packet
data	Packet payload data
len	Packet payload length

See also

av_receive_audio_opus_batch() For packet parsing

opus_codec_decode() For Opus decoding

handle_audio_batch_packet() For raw PCM Audio batch handling

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

                                                                                         {
  log_debug_every(LOG_RATE_SLOW, "Received Opus audio batch from client %s (len=%zu)", client->client_id, len);
 
  VALIDATE_NOTNULL_DATA(client, data, "AUDIO_OPUS_BATCH");
  VALIDATE_AUDIO_STREAM_ENABLED(client, "AUDIO_OPUS_BATCH");
  VALIDATE_RESOURCE_INITIALIZED(client, client->opus_decoder, "Opus decoder");
 
  // Parse Opus batch packet
  const uint8_t *opus_data = NULL;
  size_t opus_size = 0;
  const uint16_t *frame_sizes = NULL;
  int sample_rate = 0;
  int frame_duration = 0;
  int frame_count = 0;
 
  asciichat_error_t result = packet_parse_opus_batch(data, len, &opus_data, &opus_size, &frame_sizes, &sample_rate,
                                                     &frame_duration, &frame_count);
 
  if (result != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "Failed to parse AUDIO_OPUS_BATCH packet");
    return;
  }
 
  VALIDATE_NONZERO(client, frame_count, "frame_count", "AUDIO_OPUS_BATCH");
  VALIDATE_NONZERO(client, opus_size, "opus_size", "AUDIO_OPUS_BATCH");
 
  // Calculate samples per frame (20ms @ 48kHz = OPUS_FRAME_SAMPLES samples)
  int samples_per_frame = (sample_rate * frame_duration) / 1000 * AUDIO_CHANNELS;
  VALIDATE_RANGE(client, samples_per_frame, 1, AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS, "samples_per_frame",
                 "AUDIO_OPUS_BATCH");
 
  // Use static buffer for common case to avoid malloc in hot path
  // Typical batches: 1-32 frames of OPUS_FRAME_SAMPLES samples = up to 30,720 samples
  // Static buffer holds 32 frames @ 48kHz 20ms = 30,720 samples (120KB)
#define OPUS_DECODE_STATIC_MAX_SAMPLES (32 * OPUS_FRAME_SAMPLES * AUDIO_CHANNELS)
  // Each client receive thread decodes independently. Sharing this scratch
  // buffer lets concurrent clients overwrite one another's PCM before it is
  // written to their source rings.
  static _Thread_local float static_decode_buffer[OPUS_DECODE_STATIC_MAX_SAMPLES];
 
  size_t total_samples = (size_t)samples_per_frame * (size_t)frame_count;
  float *decoded_samples;
  bool used_malloc = false;
 
  if (total_samples <= OPUS_DECODE_STATIC_MAX_SAMPLES) {
    decoded_samples = static_decode_buffer;
  } else {
    // Unusual large batch - fall back to malloc
    log_warn("Client %s: Large audio batch requires malloc (%zu samples)", client->client_id, total_samples);
    decoded_samples = SAFE_MALLOC(total_samples * sizeof(float), float *);
    if (!decoded_samples) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for Opus decoded samples");
      return;
    }
    used_malloc = true;
  }
 
  // Decode each Opus frame using frame_sizes array
  int total_decoded = 0;
  size_t opus_offset = 0;
 
  for (int i = 0; i < frame_count; i++) {
    // Get exact frame size from frame_sizes array (convert from network byte order)
    size_t frame_size = (size_t)NET_TO_HOST_U16(frame_sizes[i]);
 
    // DEBUG: Log the actual bytes of each Opus frame
    if (frame_size > 0) {
      log_debug_every(LOG_RATE_DEFAULT, "Client %s: Opus frame %d: size=%zu, first_bytes=[0x%02x,0x%02x,0x%02x,0x%02x]",
                      client->client_id, i, frame_size, opus_data[opus_offset] & 0xFF,
                      frame_size > 1 ? (opus_data[opus_offset + 1] & 0xFF) : 0,
                      frame_size > 2 ? (opus_data[opus_offset + 2] & 0xFF) : 0,
                      frame_size > 3 ? (opus_data[opus_offset + 3] & 0xFF) : 0);
    }
 
    if (opus_offset + frame_size > opus_size) {
      log_error("Client %s: Frame %d size overflow (offset=%zu, frame_size=%zu, total=%zu)", client->client_id, i + 1,
                opus_offset, frame_size, opus_size);
      if (used_malloc) {
        SAFE_FREE(decoded_samples);
      }
      return;
    }
 
    // SECURITY: Bounds check before writing decoded samples to prevent buffer overflow
    // An attacker could send malicious Opus frames that decode to more samples than expected
    if ((size_t)total_decoded + (size_t)samples_per_frame > total_samples) {
      log_error("Client %s: Opus decode would overflow buffer (decoded=%d, frame_samples=%d, max=%zu)",
                client->client_id, total_decoded, samples_per_frame, total_samples);
      if (used_malloc) {
        SAFE_FREE(decoded_samples);
      }
      return;
    }
 
    int decoded_count = opus_codec_decode((opus_codec_t *)client->opus_decoder, &opus_data[opus_offset], frame_size,
                                          &decoded_samples[total_decoded], samples_per_frame);
 
    if (decoded_count < 0) {
      log_error("Client %s: Opus decoding failed for frame %d/%d (size=%zu)", client->client_id, i + 1, frame_count,
                frame_size);
      if (used_malloc) {
        SAFE_FREE(decoded_samples);
      }
      return;
    }
 
    total_decoded += decoded_count;
    opus_offset += frame_size;
  }
 
  log_debug_every(LOG_RATE_DEFAULT, "Client %s: Decoded %d Opus frames -> %d samples", client->client_id, frame_count,
                  total_decoded);
 
  // DEBUG: Log sample values to detect all-zero issue
  static _Thread_local int server_decode_count = 0;
  server_decode_count++;
  if (total_decoded > 0 && (server_decode_count <= 10 || server_decode_count % 100 == 0)) {
    float peak = 0.0f, rms = 0.0f;
    for (int i = 0; i < total_decoded && i < 100; i++) {
      float abs_val = fabsf(decoded_samples[i]);
      if (abs_val > peak)
        peak = abs_val;
      rms += decoded_samples[i] * decoded_samples[i];
    }
    rms = sqrtf(rms / (total_decoded > 100 ? 100 : total_decoded));
    // Log first 4 bytes of Opus data to compare with client encode
    log_debug_every(
        US_PER_SEC_INT,
        "SERVER OPUS DECODE #%d from client %s: decoded_rms=%.6f, opus_first4=[0x%02x,0x%02x,0x%02x,0x%02x]",
        server_decode_count, client->client_id, rms, opus_size > 0 ? opus_data[0] : 0, opus_size > 1 ? opus_data[1] : 0,
        opus_size > 2 ? opus_data[2] : 0, opus_size > 3 ? opus_data[3] : 0);
  }
 
  // Write decoded samples to client's incoming audio buffer
  // Note: audio_ring_buffer_write returns error code, not sample count
  // Buffer overflow warnings are logged inside audio_ring_buffer_write if buffer is full
  if (client->incoming_audio_buffer && total_decoded > 0) {
    asciichat_error_t result = audio_ring_buffer_write(client->incoming_audio_buffer, decoded_samples, total_decoded);
    if (result != ASCIICHAT_OK) {
      log_error("Client %s: Failed to write decoded audio to buffer: %s", client->client_id,
                asciichat_error_format(NULL, result));
    }
  }
 
  if (used_malloc) {
    SAFE_FREE(decoded_samples);
  }
}

References asciichat_error_format(), ASCIICHAT_OK, AUDIO_CHANNELS, AUDIO_OPUS_MAX_DECODE_SAMPLES, audio_ring_buffer_write(), client_info::client_id, disconnect_client_for_bad_data(), ERROR_MEMORY, client_info::incoming_audio_buffer, log_debug_every, log_error, LOG_RATE_DEFAULT, LOG_RATE_SLOW, log_warn, NET_TO_HOST_U16, opus_codec_decode(), OPUS_DECODE_STATIC_MAX_SAMPLES, client_info::opus_decoder, packet_parse_opus_batch(), SAFE_FREE, SAFE_MALLOC, SET_ERRNO, US_PER_SEC_INT, VALIDATE_AUDIO_STREAM_ENABLED, VALIDATE_NONZERO, VALIDATE_NOTNULL_DATA, VALIDATE_RANGE, and VALIDATE_RESOURCE_INITIALIZED.

handle_audio_opus_packet()

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.

Handles single Opus-encoded audio frames sent by clients. The packet format includes a 16-byte header followed by the Opus-encoded data.

PACKET STRUCTURE:

• Offset 0: sample_rate (uint32_t, native byte order - bug in client)
• Offset 4: frame_duration (uint32_t, native byte order - bug in client)
• Offset 8: reserved (8 bytes)
• Offset 16: Opus-encoded audio data

Parameters

client	Client info structure
data	Packet payload
len	Packet length

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

                                                                                   {
  log_debug_every(LOG_RATE_DEFAULT, "Received Opus audio from client %s (len=%zu)", client->client_id, len);
 
  if (VALIDATE_PACKET_NOT_NULL(client, data, "AUDIO_OPUS")) {
    return;
  }
 
  // Minimum size: 16-byte header + at least 1 byte of Opus data
  if (len < 17) {
    disconnect_client_for_bad_data(client, "AUDIO_OPUS packet too small: %zu bytes", len);
    return;
  }
 
  if (!atomic_load_bool(&client->is_sending_audio)) {
    disconnect_client_for_bad_data(client, "AUDIO_OPUS received before audio stream enabled");
    return;
  }
 
  if (!client->opus_decoder) {
    disconnect_client_for_bad_data(client, "Opus decoder not initialized");
    return;
  }
 
  // Parse header (16 bytes) - convert from network byte order
  const uint8_t *buf = (const uint8_t *)data;
  uint32_t sample_rate_net, frame_duration_net;
  memcpy(&sample_rate_net, buf, 4);
  memcpy(&frame_duration_net, buf + 4, 4);
  uint32_t sample_rate = NET_TO_HOST_U32(sample_rate_net);
  uint32_t frame_duration = NET_TO_HOST_U32(frame_duration_net);
 
  // Extract Opus data (after 16-byte header)
  const uint8_t *opus_data = buf + 16;
  size_t opus_size = len - 16;
 
  // Validate parameters
  if (sample_rate == 0 || sample_rate > 192000) {
    disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid sample_rate: %u", sample_rate);
    return;
  }
 
  if (frame_duration == 0 || frame_duration > 120) {
    disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid frame_duration: %u ms", frame_duration);
    return;
  }
 
  // Calculate expected samples per frame
  int samples_per_frame = (int)((sample_rate * frame_duration) / 1000) * AUDIO_CHANNELS;
  if (samples_per_frame <= 0 ||
      samples_per_frame > AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS) { // Max 120ms @ 48kHz
    disconnect_client_for_bad_data(client, "AUDIO_OPUS invalid samples_per_frame: %d", samples_per_frame);
    return;
  }
 
  // Decode Opus frame
  float decoded_samples[AUDIO_OPUS_MAX_DECODE_SAMPLES * AUDIO_CHANNELS]; // Max Opus frame size (120ms @ 48kHz)
  int decoded_count =
      opus_codec_decode((opus_codec_t *)client->opus_decoder, opus_data, opus_size, decoded_samples, samples_per_frame);
 
  if (decoded_count < 0) {
    log_error("Client %s: Opus decoding failed (size=%zu)", client->client_id, opus_size);
    return;
  }
 
  log_debug_every(LOG_RATE_VERY_FAST, "Client %s: Decoded Opus frame -> %d samples", client->client_id, decoded_count);
 
  // Write decoded samples to client's incoming audio buffer
  if (client->incoming_audio_buffer && decoded_count > 0) {
    asciichat_error_t write_result =
        audio_ring_buffer_write(client->incoming_audio_buffer, decoded_samples, decoded_count);
    if (write_result != ASCIICHAT_OK) {
      log_error("Failed to write decoded Opus samples to buffer: %s", asciichat_error_format(NULL, write_result));
    }
  }
}

References asciichat_error_format(), ASCIICHAT_OK, AUDIO_CHANNELS, AUDIO_OPUS_MAX_DECODE_SAMPLES, audio_ring_buffer_write(), client_info::client_id, disconnect_client_for_bad_data(), client_info::incoming_audio_buffer, client_info::is_sending_audio, log_debug_every, log_error, LOG_RATE_DEFAULT, LOG_RATE_VERY_FAST, NET_TO_HOST_U32, opus_codec_decode(), client_info::opus_decoder, and VALIDATE_PACKET_NOT_NULL.

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 1074 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 = ASCIICHAT_OK;
  float *stereo = SAFE_MALLOC((size_t)num_samples * AUDIO_CHANNELS * sizeof(float), float *);
  if (audio_convert_channels(samples, (size_t)num_samples, 1, stereo, AUDIO_CHANNELS) == ASCIICHAT_OK)
    result = audio_ring_buffer_write(client->incoming_audio_buffer, stereo, num_samples * AUDIO_CHANNELS);
  SAFE_FREE(stereo);
  if (result != ASCIICHAT_OK) {
    log_error("Failed to write audio samples to buffer: %s", asciichat_error_format(NULL, result));
  }
}

References asciichat_error_format(), ASCIICHAT_OK, AUDIO_CHANNELS, audio_convert_channels(), audio_ring_buffer_write(), AUDIO_SAMPLES_PER_PACKET, client_info::incoming_audio_buffer, log_error, SAFE_FREE, SAFE_MALLOC, 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 )

Bootstrap a viewer's rendering state from its initial terminal capabilities. Later advertisements update codecs while SETTINGS_SYNC owns live preferences. Publish under the client mutex, then send the initial effective settings unlocked.

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

                                                                                            {
  if (!data || len != sizeof(terminal_capabilities_packet_t)) {
    disconnect_client_for_bad_data(client, "Invalid capabilities size");
    return;
  }
  terminal_capabilities_packet_t packet;
  memcpy(&packet, data, sizeof(packet));
  mutex_lock(&client->client_state_mutex);
  client->codec_capabilities_video = NET_TO_HOST_U32(packet.codec_capabilities_video);
  client->codec_capabilities_audio = NET_TO_HOST_U32(packet.codec_capabilities_audio);
  // Encoder changes advertise codec support without overwriting live preferences.
  if (client->has_terminal_caps) {
    mutex_unlock(&client->client_state_mutex);
    return;
  }
  client->render_settings.fps_limit = GET_OPTION(fps) > 0 ? GET_OPTION(fps) : DEFAULT_MAX_FPS;
  asciichat_error_t result = acip_render_settings_capabilities(&client->render_settings, &packet);
  if (result == ASCIICHAT_OK) {
    publish_render_settings(client);
    log_info("Client %s rendering configured: %ux%u, color=%u, palette=%u, mode=%u, fps=%u", client->client_id,
             client->width, client->height, client->terminal_caps.color_level, client->terminal_caps.palette_type,
             client->terminal_caps.render_mode, client->terminal_caps.desired_fps);
  }
  mutex_unlock(&client->client_state_mutex);
  if (result != ASCIICHAT_OK)
    disconnect_client_for_bad_data(client, "Invalid render capabilities");
  else {
    uint8_t query[ACIP_SETTINGS_HEADER_SIZE];
    size_t query_length;
    acip_settings_header_t header = {.schema = 1, .expected_revision = UINT32_MAX};
    if (acip_settings_encode(&header, "", query, sizeof(query), &query_length) == ASCIICHAT_OK)
      (void)handle_runtime_settings(client, query, query_length);
  }
}

References acip_render_settings_capabilities(), acip_settings_encode(), ACIP_SETTINGS_HEADER_SIZE, ASCIICHAT_OK, client_info::client_id, 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, DEFAULT_MAX_FPS, disconnect_client_for_bad_data(), acip_render_settings_t::fps_limit, GET_OPTION, handle_runtime_settings(), client_info::has_terminal_caps, client_info::height, log_info, NET_TO_HOST_U32, client_info::render_settings, client_info::terminal_caps, and client_info::width.

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 250 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 %s 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->transport != NULL) {
    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::display_name, client_info_packet_t::display_name, log_info, log_info_client, MAX_DISPLAY_NAME_LEN, NET_TO_HOST_U32, SAFE_STRNCPY, client_info::transport, 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 deactivates the client and requests transport shutdown
• The normal connection-closed callback performs final removal

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

The transport shutdown request is asynchronous; final removal occurs from the connection-closed callback.

Definition at line 397 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 %s 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 %s sent leave notification with non-zero length but NULL data", client_id);
      return;
    }
 
    char reason[SERVER_PROTOCOL_REASON_BUFFER_SIZE] = {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 %s sent leave notification: %s", client_id, reason);
    } else {
      log_info("Client %s sent leave notification (reason contains non-printable characters)", client_id);
    }
  } else {
    // Oversized reason - shouldn't happen with validation.h checks
    log_warn("Client %s 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 (client_id=%s)", client_id);
  atomic_store_bool(&client->active, false);
 
  // Request transport shutdown immediately. This keeps the server's client
  // accounting from depending on the peer closing its socket after sending
  // CLIENT_LEAVE. Final resource removal remains serialized in the normal
  // connection-closed callback.
  if (client->network_connection) {
    network_connection_request_stop(client->network_connection);
  }
}

References client_info::active, client_info::client_id, ERROR_INVALID_STATE, log_debug, log_info, log_warn, client_info::network_connection, network_connection_request_stop(), SERVER_PROTOCOL_REASON_BUFFER_SIZE, and SET_ERRNO.

handle_image_frame_h264_packet()

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

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

                                                                                         {
  asciichat_error_t result = acip_handle_server_packet(client->transport, PACKET_TYPE_IMAGE_FRAME_H264, data, len,
                                                       client, &g_acip_server_callbacks);
  if (result != ASCIICHAT_OK)
    disconnect_client_for_bad_data(client, "Invalid H.264 packet");
}

References acip_handle_server_packet(), ASCIICHAT_OK, disconnect_client_for_bad_data(), PACKET_TYPE_IMAGE_FRAME_H264, and client_info::transport.

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 914 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->transport != NULL) {
      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_every(US_PER_SEC_INT, "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 = (uint32_t)((uint64_t)client_id_num * 31 + (unsigned char)client->client_id[i]);
    }
  }
 
  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...]
  // Existing scratch budget for a 512-by-512 RGBA image.
  uint8_t *rgba_buf = SAFE_MALLOC(SERVER_H265_RGBA_BUFFER_SIZE, 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 = SERVER_H265_RGBA_BUFFER_SIZE;
 
  // 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_format(NULL, 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_debug_every(US_PER_SEC_INT, "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_error_format(), ASCIICHAT_OK, client_info::client_id, client_info::codec_capabilities_video, video_frame_t::data, disconnect_client_for_bad_data(), client_info::frames_received, g_h265_server, g_should_exit, h265_server_decode_and_convert(), h265_server_get_client_decoder(), video_frame_t::height, client_info::incoming_video_buffer, video_frame_t::is_keyframe, client_info::is_sending_video, log_debug_every, log_error, log_info, log_info_client, log_warn, video_frame_t::receive_timestamp_ns, SAFE_FREE, SAFE_MALLOC, video_frame_t::sequence_number, SERVER_H265_RGBA_BUFFER_SIZE, video_frame_t::size, client_info::transport, US_PER_SEC_INT, VIDEO_CODEC_H265, VIDEO_CODEC_SUPPORTED, video_frame_begin_write(), video_frame_commit(), and video_frame_t::width.

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 Owned Buffers storage implementation

create_mixed_ascii_frame_for_client() For frame consumption

Definition at line 711 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_debug_every(US_PER_SEC_INT, "RECV_IMAGE_FRAME: client_id=%s, 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 %s auto-enabled video stream (received IMAGE_FRAME)", client->client_id);
      // Notify client that their first video frame was received
      if (client->transport != NULL) {
        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[SERVER_PROTOCOL_PRETTY_BUFFER_SIZE];
      format_bytes_pretty(len, pretty, sizeof(pretty));
      log_debug("Client %s 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_every(US_PER_SEC_INT, "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[SERVER_PROTOCOL_SIZE_BUFFER_SIZE];
    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_debug_every(US_PER_SEC_INT, "RECV_FRAME #%u NEW: Client %s 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_debug_every(US_PER_SEC_INT, "RECV_FRAME #%u DUP: Client %s 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 %s (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 %s has no incoming video buffer!", client->client_id);
    } else {
      log_debug("Client %s: 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, video_frame_t::capture_timestamp_ns, client_info::client_id, client_info::client_state_mutex, client_info::codec_capabilities_video, video_frame_t::data, disconnect_client_for_bad_data(), ERROR_INVALID_STATE, format_bytes_pretty(), frame_check_size_overflow(), FRAME_HEADER_SIZE_LEGACY, frame_validate_legacy(), client_info::frames_received, client_info::frames_received_logged, g_should_exit, video_frame_t::height, HOST_TO_NET_U32, image_calc_rgb_size(), image_validate_buffer_size(), image_validate_dimensions(), client_info::incoming_video_buffer, client_info::is_sending_video, client_info::last_received_frame_hash, log_debug, log_debug_every, log_error, log_info, log_info_client, log_warn, MAX_FRAME_BUFFER_SIZE, NET_TO_HOST_U32, NS_PER_SEC_INT, SAFE_FREE, video_frame_t::sequence_number, SERVER_PROTOCOL_PRETTY_BUFFER_SIZE, SERVER_PROTOCOL_SIZE_BUFFER_SIZE, SET_ERRNO, video_frame_t::size, client_info::transport, US_PER_SEC_INT, VIDEO_CODEC_RGBA, VIDEO_CODEC_SUPPORTED, video_frame_begin_write(), video_frame_commit(), and video_frame_t::width.

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 622 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 %s: %s", client->client_id,
              asciichat_error_string(pong_result));
  }
}

References acip_send_pong(), ASCIICHAT_OK, client_info::client_id, ERROR_NETWORK, 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 645 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
  • protocol_patch: Patch 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 318 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);
  uint16_t client_patch = NET_TO_HOST_U16(version->protocol_patch);
 
  // Validate major version match (minor version can differ for backward compat)
  if (client_major != PROTOCOL_VERSION_MAJOR) {
    log_warn("Client %s protocol version mismatch: client=%u.%u.%u, server=%u.%u.%u", client->client_id, client_major,
             client_minor, client_patch, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, PROTOCOL_VERSION_PATCH);
    // 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 %s has different protocol revision: client=%u.%u.%u, server=%u.%u.%u", client->client_id,
             client_major, client_minor, client_patch, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR,
             PROTOCOL_VERSION_PATCH);
  }
 
  // Validate reserved bytes are zero
  for (size_t i = 0; i < sizeof(version->reserved); i++) {
    if (version->reserved[i] != 0) {
      log_warn("Client %s 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 %s supports encryption", client->client_id);
  }
  if (version->compression_algorithms != 0) {
    log_debug("Client %s 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);
    atomic_store_bool(&client->supports_recoverable_errors, (feature_flags & PROTOCOL_FEATURE_RECOVERABLE_ERRORS) != 0);
    log_debug("Client %s 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_FEATURE_RECOVERABLE_ERRORS, protocol_version_packet_t::protocol_patch, protocol_version_packet_t::protocol_revision, protocol_version_packet_t::protocol_version, PROTOCOL_VERSION_MAJOR, PROTOCOL_VERSION_MINOR, PROTOCOL_VERSION_PATCH, protocol_version_packet_t::reserved, protocol_version_packet_t::supports_encryption, and client_info::supports_recoverable_errors.

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 1094 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 %s \"%s\"] %s [message truncated]", client_id,
            display_name, message);
  } else {
    log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %s \"%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_runtime_settings()

asciichat_error_t handle_runtime_settings	(	client_info_t *	client,
		const void *	data,
		size_t	length )

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

                                                                                                  {
  uint8_t reply[ACIP_SETTINGS_MAX_SIZE];
  size_t reply_length = 0;
  mutex_lock(&client->client_state_mutex);
  if (!client->has_terminal_caps || atomic_load_bool(&client->shutting_down)) {
    mutex_unlock(&client->client_state_mutex);
    return SET_ERRNO(ERROR_INVALID_STATE, "Settings require an active bootstrapped viewer");
  }
  asciichat_error_t result =
      acip_settings_request(&client->render_settings, data, length, reply, sizeof(reply), &reply_length);
  if (result == ASCIICHAT_OK)
    publish_render_settings(client);
  mutex_unlock(&client->client_state_mutex);
  if (result == ASCIICHAT_OK) {
    // Teardown takes this mutex before releasing the transport.
    mutex_lock(&client->send_mutex);
    if (atomic_load_bool(&client->shutting_down) || !client->transport)
      result = SET_ERRNO(ERROR_INVALID_STATE, "Viewer is shutting down");
    else
      result = packet_send_via_transport(client->transport, PACKET_TYPE_ACIP_SETTINGS_ACK, reply, reply_length, 0);
    mutex_unlock(&client->send_mutex);
  }
  return result;
}

References ACIP_SETTINGS_MAX_SIZE, acip_settings_request(), ASCIICHAT_OK, client_info::client_state_mutex, ERROR_INVALID_STATE, client_info::has_terminal_caps, packet_send_via_transport(), PACKET_TYPE_ACIP_SETTINGS_ACK, client_info::render_settings, client_info::send_mutex, SET_ERRNO, client_info::shutting_down, and client_info::transport.

Referenced by handle_client_capabilities_packet(), and server_dispatch_packet().

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 1677 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 %s updated terminal size: %ux%u", client->client_id, width, height);
}

References client_info::client_id, client_info::client_state_mutex, client_info::height, height, size_packet_t::height, log_info, NET_TO_HOST_U16, VALIDATE_NONZERO, VALIDATE_PACKET_SIZE, VALIDATE_RANGE, client_info::width, size_packet_t::width, and 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 488 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_channels(AUDIO_SAMPLE_RATE, AUDIO_CHANNELS);
      if (client->opus_decoder) {
        log_info("Client %s: Opus decoder created (48kHz)", client->client_id);
      } else {
        log_error("Client %s: Failed to create Opus decoder", client->client_id);
      }
    }
  }
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    log_info("Client %s announced video stream (waiting for first frame)", client->client_id);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %s 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");
  if (client->transport != NULL) {
    log_info_client(client, "Stream started: %s", streams);
  }
}

References AUDIO_CHANNELS, AUDIO_SAMPLE_RATE, client_info::client_id, HOST_TO_NET_U32, 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_channels(), client_info::opus_decoder, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, client_info::transport, 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 582 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 %s stopped video stream", client->client_id);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %s 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");
  if (client->transport != NULL) {
    log_info_client(client, "Stream stopped: %s", streams);
  }
}

References client_info::client_id, client_info::is_sending_audio, client_info::is_sending_video, log_info, log_info_client, NET_TO_HOST_U32, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, client_info::transport, 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_push_copy()
• 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 1751 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 %s: %s", client->client_id,
              asciichat_error_string(result));
    return -1;
  }
 
  log_debug("Sent server state to client %s: %u connected, %u active", client->client_id, state.connected_client_count,
            state.active_client_count);
  return 0;
}

References acip_send_server_state(), server_state_packet_t::active_client_count, ASCIICHAT_OK, client_info::client_id, server_state_packet_t::connected_client_count, ERROR_NETWORK, g_client_manager, HOST_TO_NET_U32, log_debug, MAX_CLIENTS, server_state_packet_t::reserved, client_info::send_mutex, SET_ERRNO, and client_info::transport.