Protocol Handler

📡 Network packet processing and protocol implementation More...

Files
file	protocol.c
	📡 Server packet processor: client communication handling, protocol state management, and packet dispatch
file	protocol.h
	Server packet processing and protocol implementation.

Functions
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.

Detailed Description

📡 Network packet processing and protocol implementation

Function Documentation

handle_audio_opus_batch_packet()

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

#include <protocol.c>

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 (960 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 Types parsing

opus_codec_decode() For Opus decoding

handle_audio_batch_packet() For raw PCM Audio batch handling

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

                                                                                         {
  log_debug_every(LOG_RATE_SLOW, "Received Opus audio batch from client %u (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 = 960 samples)
  int samples_per_frame = (sample_rate * frame_duration) / 1000;
  VALIDATE_RANGE(client, samples_per_frame, 1, 4096, "samples_per_frame", "AUDIO_OPUS_BATCH");
 
  // Use static buffer for common case to avoid malloc in hot path
  // Typical batches: 1-32 frames of 960 samples = up to 30,720 samples
  // Static buffer holds 32 frames @ 48kHz 20ms = 30,720 samples (120KB)
#define OPUS_DECODE_STATIC_MAX_SAMPLES (32 * 960)
  // 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 %u: 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 %u: 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 %u: 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 %u: 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 %u: 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 %u: 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_info("SERVER OPUS DECODE #%d from client %u: 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 %u: Failed to write decoded audio to buffer: %d", client->client_id, result);
    }
  }
 
  if (used_malloc) {
    SAFE_FREE(decoded_samples);
  }
}

References ASCIICHAT_OK, 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_info, 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, 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
	)

#include <protocol.c>

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

                                                                                   {
  log_debug_every(LOG_RATE_DEFAULT, "Received Opus audio from client %u (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);
  if (samples_per_frame <= 0 || samples_per_frame > 5760) { // 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[5760]; // 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 %u: Opus decoding failed (size=%zu)", client->client_id, opus_size);
    return;
  }
 
  log_debug_every(LOG_RATE_VERY_FAST, "Client %u: 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_string(write_result));
    }
  }
}

References ASCIICHAT_OK, atomic_load_bool(), 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.