protocol.c File Reference

📡 Server packet processor: client communication handling, protocol state management, and packet dispatch More...

Go to the source code of this file.

Macros
#define	OPUS_DECODE_STATIC_MAX_SAMPLES   (32 * 960)

Functions
void	disconnect_client_for_bad_data (client_info_t *client, const char *format,...)
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_client_leave_packet (client_info_t *client, const void *data, size_t len)
	Process CLIENT_LEAVE packet - handle clean client disconnect.
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_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_audio_packet (client_info_t *client, const void *data, size_t len)
	Process AUDIO packet - store single audio sample batch (legacy format)
void	handle_remote_log_packet_from_client (client_info_t *client, const void *data, size_t len)
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_client_capabilities_packet (client_info_t *client, const void *data, size_t len)
	Process CLIENT_CAPABILITIES packet - configure client-specific rendering.
void	handle_size_packet (client_info_t *client, const void *data, size_t len)
	Process terminal size update packet - handle client window resize.
void	handle_ping_packet (client_info_t *client)
	Process PING packet - respond with PONG for keepalive.
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.

Variables
atomic_bool	g_server_should_exit
	Global shutdown flag from main.c - used to avoid error spam during shutdown.

Detailed Description

📡 Server packet processor: client communication handling, protocol state management, and packet dispatch

CORE RESPONSIBILITIES

1. Parse and validate incoming packets from clients
2. Update client state based on received packet data
3. Coordinate with other modules for media processing
4. Generate appropriate server responses to client requests
5. Maintain protocol compliance and packet format standards

PACKET PROCESSING ARCHITECTURE:

The protocol processing follows a clear pattern:

1. PACKET RECEPTION (in client.c receive thread):
   • Receives raw packet data from socket
   • Validates packet header and CRC
   • Dispatches to appropriate handler function
2. HANDLER FUNCTION (this module):
   • Validates packet payload structure
   • Updates client state with thread-safe patterns
   • Processes media data (stores in buffers)
   • Generates any necessary responses
3. RESPONSE GENERATION (via packet queues):
   • Queues response packets for delivery
   • Uses client's outgoing packet queues
   • Send thread delivers responses asynchronously

SUPPORTED PACKET TYPES:

CLIENT LIFECYCLE:

• PACKET_TYPE_CLIENT_JOIN: Initial client capabilities and identity
• PACKET_TYPE_CLIENT_LEAVE: Clean disconnect notification
• PACKET_TYPE_CLIENT_CAPABILITIES: Terminal capabilities and preferences

MEDIA STREAMING:

• PACKET_TYPE_STREAM_START: Begin sending audio/video
• PACKET_TYPE_STREAM_STOP: Stop sending audio/video
• PACKET_TYPE_IMAGE_FRAME: Raw RGB video frame data
• PACKET_TYPE_AUDIO: Single audio sample packet (legacy)
• PACKET_TYPE_AUDIO_BATCH: Batched audio samples (efficient)

CONTROL PROTOCOL:

• PACKET_TYPE_PING: Client keepalive request
• PACKET_TYPE_PONG: Server keepalive response

THREAD SAFETY AND STATE MANAGEMENT:

CLIENT STATE SYNCHRONIZATION: All client state modifications use the snapshot pattern:

1. Acquire client->client_state_mutex
2. Update client state fields
3. Release mutex immediately
4. Process using local copies if needed

MEDIA BUFFER COORDINATION: Video frames: Stored in client->incoming_video_buffer (thread-safe) Audio samples: Stored in client->incoming_audio_buffer (lock-free) Both buffers are processed by render threads in render.c

PACKET VALIDATION STRATEGY: All handlers validate:

• Packet size matches expected structure size
• Client capabilities permit the operation
• Buffer pointers are valid before access
• Network byte order conversion where needed

ERROR HANDLING PHILOSOPHY:

• Invalid packets are logged but don't disconnect clients
• Buffer allocation failures are handled gracefully
• Network errors during responses don't affect client state
• Shutdown conditions are detected and avoid error spam

INTEGRATION WITH OTHER MODULES:

• client.c: Called by receive threads, manages client lifecycle
• render.c: Consumes video/audio data stored by handlers
• stream.c: Uses client capabilities for frame generation
• main.c: Provides global state (g_server_should_exit, etc.)

WHY THIS MODULAR DESIGN:

The original server.c mixed protocol handling with connection management and rendering logic, making it difficult to:

• Add new packet types
• Modify protocol behavior
• Debug packet-specific issues
• Test protocol compliance

This separation provides:

• Clear protocol specification
• Easier protocol evolution
• Better error isolation
• Improved testability

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

September 2025

Version

2.0 (Post-Modularization)

See also

client.c For client receive thread implementation

render.c For media buffer consumption

network.h For Packet Types structure definitions

Definition in file server/protocol.c.

Macro Definition Documentation

OPUS_DECODE_STATIC_MAX_SAMPLES

#define OPUS_DECODE_STATIC_MAX_SAMPLES   (32 * 960)

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

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

References ERROR_INVALID_STATE, log_warn, and SET_ERRNO.

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

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

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

Referenced by process_decrypted_packet().

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

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

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

Referenced by process_decrypted_packet().

handle_client_capabilities_packet()

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

Process CLIENT_CAPABILITIES packet - configure client-specific rendering.

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

PACKET STRUCTURE EXPECTED:

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

STATE CHANGES PERFORMED:

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

PALETTE INITIALIZATION: The function performs critical palette setup:

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

THREAD SAFETY:

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

VALIDATION PERFORMED:

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

ERROR HANDLING:

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

INTEGRATION IMPACT:

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

Parameters

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

Note

This packet is typically sent once after CLIENT_JOIN

Capabilities can be updated during the session

Changes affect all subsequent ASCII frame generation

See also

initialize_client_palette() For Character Palettes setup details

terminal_color_level_name() For color level descriptions

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

                                                                                            {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(terminal_capabilities_packet_t), "CLIENT_CAPABILITIES");
 
  const terminal_capabilities_packet_t *caps = (const terminal_capabilities_packet_t *)data;
 
  // Extract and validate dimensions
  uint16_t width = NET_TO_HOST_U16(caps->width);
  uint16_t height = NET_TO_HOST_U16(caps->height);
 
  VALIDATE_NONZERO(client, width, "width", "CLIENT_CAPABILITIES");
  VALIDATE_NONZERO(client, height, "height", "CLIENT_CAPABILITIES");
  VALIDATE_RANGE(client, width, 1, 4096, "width", "CLIENT_CAPABILITIES");
  VALIDATE_RANGE(client, height, 1, 4096, "height", "CLIENT_CAPABILITIES");
 
  // Extract and validate color level (0=none, 1=16, 2=256, 3=truecolor)
  uint32_t color_level = NET_TO_HOST_U32(caps->color_level);
  VALIDATE_RANGE(client, color_level, 0, 3, "color_level", "CLIENT_CAPABILITIES");
 
  // Extract and validate render mode (0=foreground, 1=background, 2=half-block)
  uint32_t render_mode = NET_TO_HOST_U32(caps->render_mode);
  VALIDATE_RANGE(client, render_mode, 0, 2, "render_mode", "CLIENT_CAPABILITIES");
 
  // Extract and validate palette type (0-5 are valid, 5=PALETTE_CUSTOM)
  uint32_t palette_type = NET_TO_HOST_U32(caps->palette_type);
  VALIDATE_RANGE(client, palette_type, 0, 5, "palette_type", "CLIENT_CAPABILITIES");
 
  // Validate desired FPS (1-144)
  VALIDATE_RANGE(client, caps->desired_fps, 1, 144, "desired_fps", "CLIENT_CAPABILITIES");
 
  mutex_lock(&client->client_state_mutex);
 
  atomic_store(&client->width, width);
  atomic_store(&client->height, height);
 
  log_debug("Client %u dimensions: %ux%u, desired_fps=%u", atomic_load(&client->client_id), client->width,
            client->height, caps->desired_fps);
 
  client->terminal_caps.capabilities = NET_TO_HOST_U32(caps->capabilities);
  client->terminal_caps.color_level = color_level;
  client->terminal_caps.color_count = NET_TO_HOST_U32(caps->color_count);
  client->terminal_caps.render_mode = render_mode;
  client->terminal_caps.detection_reliable = caps->detection_reliable;
  client->terminal_caps.wants_background = (render_mode == RENDER_MODE_BACKGROUND);
 
  SAFE_STRNCPY(client->terminal_caps.term_type, caps->term_type, sizeof(client->terminal_caps.term_type));
  SAFE_STRNCPY(client->terminal_caps.colorterm, caps->colorterm, sizeof(client->terminal_caps.colorterm));
 
  client->terminal_caps.utf8_support = NET_TO_HOST_U32(caps->utf8_support);
  client->terminal_caps.palette_type = palette_type;
  SAFE_STRNCPY(client->terminal_caps.palette_custom, caps->palette_custom,
               sizeof(client->terminal_caps.palette_custom));
 
  client->terminal_caps.desired_fps = caps->desired_fps;
 
  const char *custom_chars =
      (client->terminal_caps.palette_type == PALETTE_CUSTOM && client->terminal_caps.palette_custom[0])
          ? client->terminal_caps.palette_custom
          : NULL;
 
  if (initialize_client_palette((palette_type_t)client->terminal_caps.palette_type, custom_chars,
                                client->client_palette_chars, &client->client_palette_len,
                                client->client_luminance_palette) == 0) {
    client->client_palette_type = (palette_type_t)client->terminal_caps.palette_type;
    client->client_palette_initialized = true;
    log_info("Client %d palette initialized: type=%u, %zu chars, utf8=%u", atomic_load(&client->client_id),
             client->terminal_caps.palette_type, client->client_palette_len, client->terminal_caps.utf8_support);
  } else {
    SET_ERRNO(ERROR_INVALID_STATE, "Failed to initialize palette for client %d", atomic_load(&client->client_id));
    client->client_palette_initialized = false;
  }
 
  client->has_terminal_caps = true;
 
  log_info("Client %u capabilities: %ux%u, color_level=%s (%u colors), caps=0x%x, term=%s, colorterm=%s, "
           "render_mode=%s, reliable=%s, fps=%u",
           atomic_load(&client->client_id), client->width, client->height,
           terminal_color_level_name(client->terminal_caps.color_level), client->terminal_caps.color_count,
           client->terminal_caps.capabilities, client->terminal_caps.term_type, client->terminal_caps.colorterm,
           (client->terminal_caps.render_mode == RENDER_MODE_HALF_BLOCK
                ? "half-block"
                : (client->terminal_caps.render_mode == RENDER_MODE_BACKGROUND ? "background" : "foreground")),
           client->terminal_caps.detection_reliable ? "yes" : "no", client->terminal_caps.desired_fps);
 
  // Send capabilities acknowledgment to client
  log_info_client(client, "Terminal configured: %ux%u, %s, %s mode, %u fps", client->width, client->height,
                  terminal_color_level_name(client->terminal_caps.color_level),
                  (client->terminal_caps.render_mode == RENDER_MODE_HALF_BLOCK
                       ? "half-block"
                       : (client->terminal_caps.render_mode == RENDER_MODE_BACKGROUND ? "background" : "foreground")),
                  client->terminal_caps.desired_fps);
 
  mutex_unlock(&client->client_state_mutex);
}

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

Referenced by process_decrypted_packet().

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

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

Referenced by process_decrypted_packet().

handle_client_leave_packet()

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

Process CLIENT_LEAVE packet - handle clean client disconnect.

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

PACKET STRUCTURE EXPECTED:

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

PROTOCOL BEHAVIOR:

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

ERROR HANDLING:

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

Parameters

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

Note

This handler doesn't trigger immediate disconnect

Actual disconnect occurs when socket closes

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

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

References client_info::active, client_info::client_id, ERROR_INVALID_STATE, log_info, log_warn, and SET_ERRNO.

Referenced by process_decrypted_packet().

handle_image_frame_packet()

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

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

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

PACKET STRUCTURE EXPECTED:

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

PERFORMANCE CHARACTERISTICS:

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

STATE CHANGES PERFORMED:

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

BUFFER MANAGEMENT:

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

VALIDATION PERFORMED:

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

ERROR HANDLING:

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

PERFORMANCE OPTIMIZATIONS:

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

Parameters

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

Note

This function is called by client receive threads at high frequency

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

Frame timestamps are added for synchronization purposes

See also

framebuffer_write_multi_frame() For buffer storage implementation

create_mixed_ascii_frame_for_client() For frame consumption

Definition at line 683 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
  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(&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_compare_exchange_strong(&client->is_sending_video, &was_sending_video, true)) {
      log_info("Client %u auto-enabled video stream (received IMAGE_FRAME)", atomic_load(&client->client_id));
      // Notify client that their first video frame was received
      log_info_client(client, "First video frame received - streaming active");
    }
  } else {
    // Log periodically to confirm we're receiving frames
    // Use per-client counter protected by client_state_mutex to avoid race conditions
    mutex_lock(&client->client_state_mutex);
    client->frames_received_logged++;
    if (client->frames_received_logged % 25000 == 0) {
      char pretty[64];
      format_bytes_pretty(len, pretty, sizeof(pretty));
      log_debug("Client %u has sent %u IMAGE_FRAME packets (%s)", atomic_load(&client->client_id),
                client->frames_received_logged, pretty);
    }
    mutex_unlock(&client->client_state_mutex);
  }
 
  // Parse image dimensions (use memcpy to avoid unaligned access)
  uint32_t img_width_net, img_height_net;
  memcpy(&img_width_net, data, sizeof(uint32_t));
  memcpy(&img_height_net, (char *)data + sizeof(uint32_t), sizeof(uint32_t));
  uint32_t img_width = NET_TO_HOST_U32(img_width_net);
  uint32_t img_height = NET_TO_HOST_U32(img_height_net);
 
  log_debug("IMAGE_FRAME packet: width=%u, height=%u, payload_len=%zu", img_width, img_height, len);
 
  // Validate dimensions using image utility functions
  if (image_validate_dimensions((size_t)img_width, (size_t)img_height) != ASCIICHAT_OK) {
    log_error("IMAGE_FRAME validation failed for dimensions: %u x %u", img_width, img_height);
    disconnect_client_for_bad_data(client, "IMAGE_FRAME invalid dimensions");
    return;
  }
 
  // Calculate RGB buffer size with overflow checking
  size_t rgb_size = 0;
  if (image_calc_rgb_size((size_t)img_width, (size_t)img_height, &rgb_size) != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size calculation failed");
    return;
  }
 
  // Validate final buffer size against maximum
  if (image_validate_buffer_size(rgb_size) != ASCIICHAT_OK) {
    disconnect_client_for_bad_data(client, "IMAGE_FRAME buffer size exceeds maximum");
    return;
  }
 
  // Check if this is the new compressed format (has 4 fields) or old format (has 2 fields)
  const size_t legacy_header_size = sizeof(uint32_t) * 2;
  if (rgb_size > SIZE_MAX - legacy_header_size) {
    char size_str[32];
    format_bytes_pretty(rgb_size, size_str, sizeof(size_str));
    disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy packet size overflow: %s", size_str);
    return;
  }
  size_t old_format_size = legacy_header_size + rgb_size;
  bool is_new_format = (len != old_format_size) && (len > sizeof(uint32_t) * 4);
 
  void *rgb_data = NULL;
  size_t rgb_data_size = 0;
  bool needs_free = false;
 
  if (is_new_format) {
    // New format: [width:4][height:4][compressed_flag:4][data_size:4][data:data_size]
    if (len < sizeof(uint32_t) * 4) {
      disconnect_client_for_bad_data(client, "IMAGE_FRAME new-format header too small (%zu bytes)", len);
      return;
    }
 
    // Use memcpy to avoid unaligned access for compressed_flag and data_size
    uint32_t compressed_flag_net, data_size_net;
    memcpy(&compressed_flag_net, (char *)data + sizeof(uint32_t) * 2, sizeof(uint32_t));
    memcpy(&data_size_net, (char *)data + sizeof(uint32_t) * 3, sizeof(uint32_t));
    uint32_t compressed_flag = NET_TO_HOST_U32(compressed_flag_net);
    uint32_t data_size = NET_TO_HOST_U32(data_size_net);
    void *frame_data = (char *)data + sizeof(uint32_t) * 4;
 
    const size_t new_header_size = sizeof(uint32_t) * 4;
    size_t data_size_sz = (size_t)data_size;
    if (data_size_sz > IMAGE_MAX_PIXELS_SIZE) {
      char size_str[32];
      format_bytes_pretty(data_size_sz, size_str, sizeof(size_str));
      disconnect_client_for_bad_data(client, "IMAGE_FRAME compressed data too large: %s", size_str);
      return;
    }
    if (data_size_sz > SIZE_MAX - new_header_size) {
      disconnect_client_for_bad_data(client, "IMAGE_FRAME new-format packet size overflow");
      return;
    }
    size_t expected_total = new_header_size + data_size_sz;
    if (len != expected_total) {
      disconnect_client_for_bad_data(client, "IMAGE_FRAME new-format length mismatch: expected %zu got %zu",
                                     expected_total, len);
      return;
    }
 
    if (compressed_flag) {
      // Decompress the data
      rgb_data = SAFE_MALLOC(rgb_size, void *);
      if (!rgb_data) {
        SET_ERRNO(ERROR_MEMORY, "Failed to allocate decompression buffer for client %u",
                  atomic_load(&client->client_id));
        return;
      }
 
      asciichat_error_t decompress_result = decompress_data(frame_data, data_size, rgb_data, rgb_size);
      if (decompress_result != ASCIICHAT_OK) {
        SAFE_FREE(rgb_data);
        disconnect_client_for_bad_data(client, "IMAGE_FRAME decompression failure for %zu bytes: %s", data_size_sz,
                                       asciichat_error_string(decompress_result));
        return;
      }
 
      rgb_data_size = rgb_size;
      needs_free = true;
    } else {
      // Uncompressed data
      rgb_data = frame_data;
      rgb_data_size = data_size;
      if (rgb_data_size != rgb_size) {
        disconnect_client_for_bad_data(client, "IMAGE_FRAME uncompressed size mismatch: expected %zu got %zu", rgb_size,
                                       rgb_data_size);
        return;
      }
    }
  } else {
    // Old format: [width:4][height:4][rgb_data:w*h*3]
    if (len != old_format_size) {
      disconnect_client_for_bad_data(client, "IMAGE_FRAME legacy length mismatch: expected %zu got %zu",
                                     old_format_size, len);
      return;
    }
    rgb_data = (char *)data + sizeof(uint32_t) * 2;
    rgb_data_size = rgb_size;
  }
 
  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]
      if (rgb_data_size > SIZE_MAX - legacy_header_size) {
        if (needs_free && rgb_data) {
          SAFE_FREE(rgb_data);
        }
        char size_str[32];
        format_bytes_pretty(rgb_data_size, size_str, sizeof(size_str));
        disconnect_client_for_bad_data(client, "IMAGE_FRAME size overflow while repacking: rgb_data_size=%s", size_str);
        return;
      }
      size_t old_packet_size = legacy_header_size + rgb_data_size;
 
      if (old_packet_size <= 2 * 1024 * 1024) { // Max 2MB frame 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_us = (uint64_t)time(NULL) * 1000000;
        frame->sequence_number = ++client->frames_received;
        video_frame_commit(client->incoming_video_buffer);
      } else {
        if (needs_free && rgb_data) {
          SAFE_FREE(rgb_data);
        }
        disconnect_client_for_bad_data(client, "IMAGE_FRAME repacked frame too large (%zu bytes)", old_packet_size);
        return;
      }
    } else {
      log_warn("Failed to get write buffer for client %u (frame=%p, frame->data=%p)", atomic_load(&client->client_id),
               (void *)frame, frame ? frame->data : NULL);
    }
  } else {
    // During shutdown, this is expected - don't spam error logs
    if (!atomic_load(&g_server_should_exit)) {
      SET_ERRNO(ERROR_INVALID_STATE, "Client %u has no incoming video buffer!", atomic_load(&client->client_id));
    } else {
      log_debug("Client %u: ignoring video packet during shutdown", atomic_load(&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_us, client_info::client_id, client_info::client_state_mutex, video_frame_t::data, decompress_data(), disconnect_client_for_bad_data(), ERROR_INVALID_STATE, ERROR_MEMORY, format_bytes_pretty(), client_info::frames_received, client_info::frames_received_logged, g_server_should_exit, video_frame_t::height, HOST_TO_NET_U32, image_calc_rgb_size(), IMAGE_MAX_PIXELS_SIZE, image_validate_buffer_size(), image_validate_dimensions(), client_info::incoming_video_buffer, client_info::is_sending_video, log_debug, log_error, log_info, log_info_client, log_warn, mutex_lock, mutex_unlock, NET_TO_HOST_U32, SAFE_FREE, SAFE_MALLOC, video_frame_t::sequence_number, SET_ERRNO, video_frame_t::size, video_frame_begin_write(), video_frame_commit(), and video_frame_t::width.

Referenced by process_decrypted_packet().

handle_ping_packet()

void handle_ping_packet

(

client_info_t *

client

)

Process PING packet - respond with PONG for keepalive.

Clients send periodic PING packets to verify the connection is still active. The server responds with a PONG packet to confirm bi-directional connectivity. This prevents network equipment from timing out idle connections.

PACKET STRUCTURE:

• PING packets have no payload (header only)
• PONG responses also have no payload

PROTOCOL BEHAVIOR:

• Every PING must be answered with exactly one PONG
• PONG is queued in client's video queue for delivery
• No state changes are made to client

ERROR HANDLING:

• Queue failures are logged but not fatal
• Client disconnection during PONG delivery is handled gracefully
• Excessive PING rate is not rate-limited (client responsibility)

PERFORMANCE CHARACTERISTICS:

• Very low overhead (no payload processing)
• Uses existing packet queue infrastructure
• Send thread delivers PONG asynchronously

Parameters

client

Source client requesting keepalive confirmation

Note

PING/PONG packets help detect network failures

Response is queued, not sent immediately

See also

packet_queue_enqueue() For response delivery mechanism

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

                                               {
  // PONG responses should be handled directly via socket in send thread
  // For now, just log the ping
  (void)client;
}

handle_protocol_version_packet()

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

Process PROTOCOL_VERSION packet - validate protocol compatibility.

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

PACKET STRUCTURE EXPECTED:

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

VALIDATION PERFORMED:

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

ERROR HANDLING:

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

Parameters

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

Note

This is typically the first packet in the handshake

Protocol version validation ensures compatibility

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

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

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

Referenced by process_decrypted_packet().

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 948 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)";
  uint32_t client_id = atomic_load(&client->client_id);
 
  if (truncated) {
    log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %u \"%s\"] %s [message truncated]", client_id,
            display_name, message);
  } else {
    log_msg(remote_level, __FILE__, __LINE__, __func__, "[REMOTE CLIENT %u \"%s\"] %s", client_id, display_name,
            message);
  }
}

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

Referenced by process_decrypted_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 1592 of file server/protocol.c.

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

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

handle_stream_start_packet()

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

Process STREAM_START packet - client requests to begin media transmission.

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

PACKET STRUCTURE EXPECTED:

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

STATE CHANGES PERFORMED:

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

PROTOCOL BEHAVIOR:

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

ERROR HANDLING:

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

Parameters

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

Note

Changes take effect immediately for subsequent media packets

Render threads will detect the state change on their next cycle

See also

handle_stream_stop_packet() For stopping media transmission

handle_image_frame_packet() For Video to ASCII Conversion data processing

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

                                                                                     {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_START");
 
  uint32_t stream_type_net;
  memcpy(&stream_type_net, data, sizeof(uint32_t));
  uint32_t stream_type = NET_TO_HOST_U32(stream_type_net);
 
  // 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_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) {
    // Wait for first IMAGE_FRAME before marking sending_video true (avoids race)
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    atomic_store(&client->is_sending_audio, true);
 
    // Create Opus decoder for this client if not already created
    if (!client->opus_decoder) {
      client->opus_decoder = opus_codec_create_decoder(48000);
      if (client->opus_decoder) {
        log_info("Client %u: Opus decoder created (48kHz)", atomic_load(&client->client_id));
      } else {
        log_error("Client %u: Failed to create Opus decoder", atomic_load(&client->client_id));
      }
    }
  }
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    log_info("Client %u announced video stream (waiting for first frame)", atomic_load(&client->client_id));
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %u started audio stream", atomic_load(&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");
  log_info_client(client, "Stream started: %s", streams);
}

References client_info::client_id, client_info::is_sending_audio, log_error, log_info, log_info_client, NET_TO_HOST_U32, opus_codec_create_decoder(), client_info::opus_decoder, STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, VALIDATE_CAPABILITY_FLAGS, VALIDATE_FLAGS_MASK, and VALIDATE_PACKET_SIZE.

Referenced by process_decrypted_packet().

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

                                                                                    {
  VALIDATE_PACKET_SIZE(client, data, len, sizeof(uint32_t), "STREAM_STOP");
 
  uint32_t stream_type_net;
  memcpy(&stream_type_net, data, sizeof(uint32_t));
  uint32_t stream_type = NET_TO_HOST_U32(stream_type_net);
 
  // 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(&client->is_sending_video, false);
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    atomic_store(&client->is_sending_audio, false);
  }
 
  if (stream_type & STREAM_TYPE_VIDEO) {
    log_info("Client %u stopped video stream", atomic_load(&client->client_id));
  }
  if (stream_type & STREAM_TYPE_AUDIO) {
    log_info("Client %u stopped audio stream", atomic_load(&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");
  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, VALIDATE_CAPABILITY_FLAGS, VALIDATE_FLAGS_MASK, and VALIDATE_PACKET_SIZE.

Referenced by process_decrypted_packet().

send_server_state_to_client()

int send_server_state_to_client

(

client_info_t *

client

)

Send current server state to a specific client.

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

PACKET CONTENT GENERATED:

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

USAGE SCENARIOS:

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

IMPLEMENTATION DETAILS:

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

THREAD SAFETY:

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

ERROR HANDLING:

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

Parameters

client

Target client to receive server state information

Returns

0 on successful queuing, -1 on error

Note

Packet delivery happens asynchronously via send thread

Client count may change between queuing and delivery

See also

broadcast_server_state_to_all_clients() For multi-client updates

Definition at line 1704 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(&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
  // CRITICAL: Protect socket writes with send_mutex to prevent race with send_thread
  mutex_lock(&client->send_mutex);
  asciichat_error_t result = acip_send_server_state(client->transport, &net_state);
  mutex_unlock(&client->send_mutex);
 
  if (result != ASCIICHAT_OK) {
    SET_ERRNO(ERROR_NETWORK, "Failed to send server state to client %u: %s", client->client_id,
              asciichat_error_string(result));
    return -1;
  }
 
  log_debug("Sent server state to client %u: %u connected, %u active", client->client_id, state.connected_client_count,
            state.active_client_count);
  return 0;
}

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

Variable Documentation

g_server_should_exit

atomic_bool g_server_should_exit

extern

Global shutdown flag from main.c - used to avoid error spam during shutdown.

When the server is shutting down, certain packet processing errors become expected (e.g., buffer allocation failures, queue shutdowns). This flag helps handlers distinguish between genuine errors and shutdown conditions.

Global shutdown flag from main.c - used to avoid error spam during shutdown.

Global shutdown flag from main.c.

This flag is the primary coordination mechanism for clean server shutdown. It's atomic to ensure thread-safe access without mutexes, as it's checked frequently in tight loops across all worker threads.

USAGE PATTERN:

• Set to true by signal handlers (SIGINT/SIGTERM) or main loop on error
• Checked by all worker threads to know when to exit gracefully
• Must be atomic to prevent race conditions during shutdown cascade

Definition at line 135 of file server/main.c.

Referenced by handle_image_frame_packet().