Client Handler

📡 Client-side packet processing and data reception thread More...

Files
file	protocol.c
	📡 Client protocol handler: packet reception, parsing, and dispatch with data thread coordination
file	protocol.h
	ascii-chat Client Protocol Handler Interface

Data Structures
struct	remote_client_info_t
	Remote client information structure for multi-user client tracking. More...

Functions
int	protocol_start_connection ()
	Start protocol connection handling.
void	protocol_stop_connection ()
	Stop protocol connection handling.
bool	protocol_connection_lost ()
	Check if connection has been lost.
const acip_client_callbacks_t *	protocol_get_acip_callbacks ()
	Get ACIP client callbacks for packet dispatch.

Detailed Description

📡 Client-side packet processing and data reception thread

Client Protocol README

Overview

The protocol handler manages the data reception thread, processes incoming packets from the server, and dispatches them to appropriate handlers based on packet type.

Implementation: src/client/protocol.c, src/client/protocol.h

Data Reception Thread

static void *data_reception_thread(void *arg)
{
  (void)arg;
 
  socket_t sockfd = server_connection_get_socket();
  const crypto_context_t *crypto_ctx = crypto_client_get_context();
 
  while (!should_exit() && server_connection_is_active()) {
    packet_header_t header;
    void *payload = NULL;
    size_t payload_len = 0;
 
    // Receive and decrypt packet
    int result = receive_packet(sockfd, crypto_ctx, &header, &payload, &payload_len);
 
    if (result < 0) {
      log_debug("receive_packet failed - connection lost");
      server_connection_lost();
      break;
    }
 
    // Dispatch based on packet type
    handle_packet(&header, payload, payload_len);
 
    if (payload) {
      free(payload);
      payload = NULL;
    }
  }
 
  atomic_store(&g_data_thread_exited, true);
  return NULL;
}

Packet Handlers

ASCII Frame Handler

static void handle_ascii_frame(const void *payload, size_t payload_len)
{
  // Render ASCII frame to terminal
  display_render_frame((const char *)payload, opt_snapshot);
 
  // Snapshot mode: exit after displaying frame
  if (opt_snapshot) {
    signal_exit();
  }
}

Audio Batch Handler

static void handle_audio_batch(const void *payload, size_t payload_len)
{
  const float *samples = (const float *)payload;
  int num_samples = payload_len / sizeof(float);
 
  // Process received audio samples
  audio_process_received_samples(samples, num_samples);
}

Pong Handler

static void handle_pong(void)
{
  // Update last pong time for keepalive timeout tracking
  keepalive_record_pong();
}

Clear Console Handler

static void handle_clear_console(void)
{
  // Server requests terminal clear
  display_full_reset();
}

Server State Handler

static void handle_server_state(const void *payload, size_t payload_len)
{
  // Log server state information
  log_debug("Received server state update");
}

Connection Loss Detection

Loss triggers in protocol thread:

• receive_packet() returns error
• Socket read error (connection closed by server)
• Decryption failure (corrupted stream)
• Invalid packet magic number

if (receive_packet(...) < 0) {
  server_connection_lost();  // Signal connection loss
  break;                     // Exit thread
}

See also

src/client/protocol.c

src/client/protocol.h

Client Overview

Function Documentation

protocol_connection_lost()

bool protocol_connection_lost

(

)

#include <protocol.c>

Check if connection has been lost.

Check if connection has been lost

Returns

true if protocol detected connection loss, false otherwise

Atomically checks whether the data reception thread has detected connection loss. Connection loss is detected by:

• Socket read error (recv() returns error)
• Socket closed by server (recv() returns 0)
• Decryption failure (corrupted stream)
• Invalid packet magic number (out of sync)

Once loss is detected, this flag remains true until the next successful connection.

Returns

true if connection lost (detected by protocol thread), false otherwise

Note

This is checked by the main thread to trigger reconnection logic. The flag is set atomically by the protocol thread and checked atomically by main.

See also

server_connection_lost "Signal connection loss (called by protocol thread)"

Definition at line 1429 of file client/protocol.c.

                                {
  return atomic_load_bool(&g_data_thread_exited) || server_connection_is_lost();
}

References atomic_load_bool(), and server_connection_is_lost().

protocol_get_acip_callbacks()

const acip_client_callbacks_t * protocol_get_acip_callbacks

(

)

#include <protocol.h>

Get ACIP client callbacks for packet dispatch.

Returns the packet dispatch callbacks structure used to route received packets to appropriate handlers. This is primarily used for ACDS signaling packet dispatch and WebRTC peer negotiation.

The callbacks structure includes handlers for:

• ASCII frame rendering
• Audio batch processing
• Server state updates
• Connection control commands (clear, reset, etc.)

Returns

Pointer to client callbacks structure (never NULL)

Used by WebRTC sessions to receive and dispatch ACDS signaling packets.

Returns pointer to the global callback structure for use by WebRTC sessions that need to receive ACDS signaling packets.

Returns

Pointer to client callbacks (never NULL)

Definition at line 957 of file client/protocol.c.

                                                             {
  return &g_acip_client_callbacks;
}

protocol_start_connection()

int protocol_start_connection

(

)

#include <protocol.c>

Start protocol connection handling.

Start protocol connection handling

Initializes protocol state and starts the data reception thread. Must be called after successful server connection establishment.

Returns

0 on success, negative on error

Spawns the data reception thread in the global client worker thread pool. The thread begins receiving and processing packets from the server. Must be called after the server connection is established and the cryptographic handshake is complete.

The thread will:

1. Continuously receive packets from the server socket
2. Decrypt packets using the negotiated session key
3. Dispatch packets to appropriate handlers based on type
4. Detect connection loss and signal the main thread

Returns

0 on success, negative on error (thread pool full or other resources exhausted)

Note

Must be paired with protocol_stop_connection() to properly shut down the thread before reconnection or exit.

See also

protocol_stop_connection "Stop data reception thread"

protocol_connection_lost "Check if connection was lost"

Definition at line 1156 of file client/protocol.c.

                                {
  log_warn("[FRAME_RECV_INIT] 🟢 PROTOCOL_START: Starting client protocol initialization");
 
  // Register protocol atomics with named debug registry
  static bool protocol_atomics_registered = false;
  if (!protocol_atomics_registered) {
    NAMED_REGISTER_ATOMIC(&g_data_thread_exited, "protocol_data_reception_thread_exit_confirmation", NULL);
    NAMED_REGISTER_ATOMIC(&g_frames_rendered, "protocol_frames_successfully_rendered", NULL);
    protocol_atomics_registered = true;
  }
 
  // Reset protocol state for new connection
  g_server_state_initialized = false;
  g_last_active_count = 0;
  g_should_clear_before_next_frame = false;
 
  log_info("[FRAME_RECV_INIT] ✅ STATE_RESET: server_initialized=false, active_count=0, clear_flag=false");
 
  // Reset display state for new connection
  display_reset_for_new_connection();
 
  // Check if we're on a WebSocket transport (crypto handshake is async via ACIP callbacks)
  // For WS/WSS, we must start data_reception FIRST so it can handle the crypto handshake,
  // then wait for crypto to complete before sending CAPABILITIES/STREAM_START.
  // For TCP, crypto is already done synchronously before this function is called.
  acip_transport_t *init_transport = server_connection_get_transport();
  bool is_websocket = init_transport && acip_transport_get_type(init_transport) == ACIP_TRANSPORT_WEBSOCKET;
 
  if (is_websocket) {
    // WebSocket: start data reception thread FIRST to handle async crypto handshake.
    // TCP does crypto synchronously in connection_attempt.c, but WS crypto flows
    // asynchronously via ACIP callbacks in the data_reception thread.
    log_debug("[FRAME_RECV_INIT] WS: Starting data_reception for async crypto handshake");
    atomic_store_bool(&g_data_thread_exited, false);
    if (thread_pool_spawn(g_client_worker_pool, data_reception_thread_func, NULL, 1, "data_reception") !=
        ASCIICHAT_OK) {
      log_error("[FRAME_RECV_INIT] Failed to start data reception thread");
      LOG_ERRNO_IF_SET("Data reception thread creation failed");
      return -1;
    }
    log_debug("[FRAME_RECV_INIT] WS: Data thread spawned, waiting for crypto handshake");
 
    // Wait for crypto handshake to complete (CRYPTO_PARAMETERS → KEY_EXCHANGE → HANDSHAKE_COMPLETE)
    // Skip waiting if encryption is disabled (no_encrypt mode)
    if (!GET_OPTION(no_encrypt)) {
      const int MAX_CRYPTO_WAIT_MS = 10000; // 10 seconds
      const int POLL_INTERVAL_MS = 10;
      int waited_ms = 0;
      while (!crypto_client_is_ready() && !should_exit() && server_connection_is_active() &&
             waited_ms < MAX_CRYPTO_WAIT_MS) {
        platform_sleep_us(POLL_INTERVAL_MS * 1000);
        waited_ms += POLL_INTERVAL_MS;
        if (waited_ms % 1000 == 0) {
          log_info("[FRAME_RECV_INIT] WS_CRYPTO: Waiting for handshake... (%d ms elapsed)", waited_ms);
        }
      }
 
      if (!crypto_client_is_ready()) {
        if (should_exit() || !server_connection_is_active()) {
          log_error("[FRAME_RECV_INIT] WS: Connection lost during crypto handshake");
        } else {
          log_error("[FRAME_RECV_INIT] WS: Crypto handshake timed out after %d ms", MAX_CRYPTO_WAIT_MS);
        }
        return -1;
      }
      log_info("[FRAME_RECV_INIT] WS: Crypto handshake completed after %d ms", waited_ms);
    } else {
      log_info("[FRAME_RECV_INIT] WS: Encryption disabled, skipping handshake wait");
    }
  }
 
  // Send CLIENT_CAPABILITIES packet (after crypto is ready for both TCP and WS)
  // Server expects this as the first packet after crypto handshake
  log_debug("[FRAME_RECV_INIT] Sending CLIENT_CAPABILITIES (terminal size)");
  asciichat_error_t cap_result = threaded_send_terminal_size_with_auto_detect((int)terminal_get_effective_width(),
                                                                              (int)terminal_get_effective_height());
  if (cap_result != ASCIICHAT_OK) {
    log_error("[FRAME_RECV_INIT] Failed to send terminal size capabilities");
    return -1;
  }
 
  // Send STREAM_START packet with combined stream types
  uint32_t stream_types = STREAM_TYPE_VIDEO; // Always have video
  if (GET_OPTION(audio_enabled)) {
    stream_types |= STREAM_TYPE_AUDIO; // Add audio if enabled
  }
  log_debug("[FRAME_RECV_INIT] Sending STREAM_START: types=0x%x (video%s)", stream_types,
            (stream_types & STREAM_TYPE_AUDIO) ? "+audio" : "");
  asciichat_error_t stream_result = threaded_send_stream_start_packet(stream_types);
  if (stream_result != ASCIICHAT_OK) {
    log_error("[FRAME_RECV_INIT] Failed to send stream start");
    return -1;
  }
 
  // Start data reception thread (TCP only - WS already started it above for crypto)
  if (!is_websocket) {
    log_debug("[FRAME_RECV_INIT] TCP: Starting data reception thread");
    atomic_store_bool(&g_data_thread_exited, false);
    if (thread_pool_spawn(g_client_worker_pool, data_reception_thread_func, NULL, 1, "data_reception") !=
        ASCIICHAT_OK) {
      log_error("[FRAME_RECV_INIT] Failed to start data reception thread");
      LOG_ERRNO_IF_SET("Data reception thread creation failed");
      return -1;
    }
  }
 
  // Start webcam capture thread
  log_debug("Starting webcam capture thread...");
  if (capture_start_thread() != 0) {
    log_error("Failed to start webcam capture thread");
    return -1;
  }
  log_debug("Webcam capture thread started successfully");
 
  // Start local media audio only after the connection succeeds. Starting the
  // worker during client initialization would consume file audio while dialing.
  audio_context_t *audio_context = audio_get_context();
  if (audio_context && audio_context->initialized) {
    audio_context->capture_media_source = capture_get_media_source();
    if (audio_start_duplex(audio_context) != ASCIICHAT_OK) {
      log_error("Failed to start full-duplex audio");
      return -1;
    }
  }
 
  // Initialize audio sender thread BEFORE starting audio capture
  // This ensures sender is ready when capture thread starts queueing packets
  // Must happen after connection succeeds to prevent deadlock if connection fails
  audio_sender_init();
 
  // Start audio capture thread if audio is enabled
  log_debug("Starting audio capture thread...");
  if (audio_start_thread() != 0) {
    log_error("Failed to start audio capture thread");
    return -1;
  }
  log_debug("Audio capture thread started successfully (or skipped if audio disabled)");
 
  // Start keepalive/ping thread to prevent server timeout
  log_debug("Starting keepalive/ping thread...");
  if (keepalive_start_thread() != 0) {
    log_error("Failed to start keepalive/ping thread");
    return -1;
  }
  log_debug("Keepalive/ping thread started successfully");
 
  g_data_thread_created = true;
  return 0;
}

References ACIP_TRANSPORT_WEBSOCKET, ASCIICHAT_OK, atomic_store_bool(), audio_get_context(), audio_sender_init(), audio_start_duplex(), audio_start_thread(), capture_get_media_source(), audio_context_t::capture_media_source, capture_start_thread(), crypto_client_is_ready(), display_reset_for_new_connection(), g_client_worker_pool, GET_OPTION, audio_context_t::initialized, keepalive_start_thread(), log_debug, LOG_ERRNO_IF_SET, log_error, log_info, log_warn, NAMED_REGISTER_ATOMIC, platform_sleep_us(), server_connection_get_transport(), server_connection_is_active(), should_exit(), STREAM_TYPE_AUDIO, STREAM_TYPE_VIDEO, terminal_get_effective_height(), terminal_get_effective_width(), thread_pool_spawn(), threaded_send_stream_start_packet(), and threaded_send_terminal_size_with_auto_detect().

protocol_stop_connection()

void protocol_stop_connection

(

)

#include <protocol.c>

Stop protocol connection handling.

Stop protocol connection handling

Gracefully shuts down the data reception thread and cleans up protocol state. Safe to call multiple times.

Signals the data reception thread to exit and waits for it to join. Performs proper cleanup to prevent resource leaks and race conditions during reconnection or shutdown.

The function:

1. Closes the server socket (interrupts blocking recv() in data thread)
2. Sets the global shutdown flag (signals thread to exit)
3. Waits for the data reception thread to join (polls for thread exit)

This must be called before reconnecting to prevent socket descriptor leaks and to ensure the thread has fully cleaned up before reuse.

Note

This function blocks until the data reception thread exits. Typical wait time: <100ms (socket closure immediately interrupts recv()).

See also

protocol_start_connection "Start data reception thread"

Definition at line 1314 of file client/protocol.c.

                                {
  // Log final frame count before shutting down (always log for diagnostic purposes)
  int final_frame_count = atomic_load_u64(&g_frames_rendered);
  log_info("📊 CLIENT SESSION STATS: %d unique frames rendered during connection", final_frame_count);
 
  log_debug("[PROTOCOL_STOP] 1. Starting protocol_stop_connection");
 
  // Stop snapshot capture before flushing, then use the shared connection shutdown
  // to wake and join the audio sender and reception threads.
  if (GET_OPTION(snapshot_mode)) {
    log_debug("[PROTOCOL_STOP] Snapshot mode: stopping capture thread before flushing H.265 encoder");
    // The capture thread owns the encoder while it is producing frames. Join it
    // before flushing so shutdown cannot destroy encoder state underneath an
    // in-flight encode operation.
    capture_stop_thread();
 
    // Flush the encoder to output any buffered frames before exiting
    if (g_h265_encoder) {
      // Allocate buffer large enough for worst-case H.265 encoded frame
      // Using 320x240 (typical test resolution) * 2x multiplier + header
      size_t flush_buf_size = 5 + (320 * 240 * 2);
      uint8_t *flush_buf = SAFE_MALLOC(flush_buf_size, uint8_t *);
      size_t flush_size = flush_buf_size;
      asciichat_error_t flush_result = h265_encoder_flush(g_h265_encoder, flush_buf, &flush_size);
      if (flush_result == ASCIICHAT_OK && flush_size > 0) {
        log_info("[PROTOCOL_STOP] Flushed H.265 encoder: got %zu bytes of buffered frames", flush_size);
        // Send the flushed frame if we got one
        acip_transport_t *transport = server_connection_get_transport();
        if (transport && server_connection_is_active()) {
          uint32_t width = 320, height = 240; // TODO: track actual dimensions
          log_debug("[PROTOCOL_STOP] Sending flushed frame: %ux%u, %zu bytes", width, height, flush_size);
        }
      }
      SAFE_FREE(flush_buf);
    }
  }
 
  // Don't call signal_exit() here - that's for global shutdown only!
  // We just want to stop threads for this connection, not exit the entire client
 
  // Shutdown the socket FIRST to interrupt any blocking network operations in worker threads
  // This must happen BEFORE audio_stop_thread() so audio sender thread unblocks from network send
  log_debug("[PROTOCOL_STOP] 2. About to call server_connection_shutdown");
  server_connection_shutdown();
  log_debug("[PROTOCOL_STOP] 3. server_connection_shutdown() returned");
 
  // Signal audio sender thread to exit
  // Must happen after socket shutdown so any blocked network calls fail
  // Snapshot recordings also transmit audio and must stop the sender.
  log_debug("[PROTOCOL_STOP] 4. About to call audio_stop_thread");
  audio_stop_thread();
  log_debug("[PROTOCOL_STOP] 5. audio_stop_thread() returned");
 
  // Early return if data thread was never created (e.g., mirror mode)
  // In mirror mode, we only need to stop the audio sender (done above)
  if (!g_data_thread_created) {
    log_debug("[PROTOCOL_STOP] 6. Data thread not created, returning");
    return;
  }
 
  // Stop keepalive/ping thread - it checks connection status and will exit
  log_debug("[PROTOCOL_STOP] 7. About to call keepalive_stop_thread");
  keepalive_stop_thread();
  log_debug("[PROTOCOL_STOP] 8. keepalive_stop_thread() returned");
 
  // Stop webcam capture thread
  log_debug("[PROTOCOL_STOP] 9. About to call capture_stop_thread");
  capture_stop_thread();
  log_debug("[PROTOCOL_STOP] 10. capture_stop_thread() returned");
 
  // Signal the audio sender while its queue synchronization objects are still valid.
  audio_sender_cleanup();
 
  // Wait for data reception thread to exit gracefully
  log_debug("[PROTOCOL_STOP] 11. Waiting for data thread to exit");
  // Thread checks should_exit() every read cycle (typically <1-5ms), so timeout can be much shorter
  int wait_count = 0;
  while (wait_count < 5 && !atomic_load_bool(&g_data_thread_exited)) {
    platform_sleep_us(10 * US_PER_MS_INT); // 10ms * 5 = 50ms max wait
    wait_count++;
  }
 
  if (!atomic_load_bool(&g_data_thread_exited)) {
    log_warn("Data thread not responding after 50ms - will be joined by thread pool");
  }
  log_debug("[PROTOCOL_STOP] 12. Data thread wait complete");
 
  // Join all threads in the client worker pool (in stop_id order)
  // This handles the data reception thread and (eventually) all other worker threads
  log_debug("[PROTOCOL_STOP] 13. About to call thread_pool_stop_all");
  if (g_client_worker_pool) {
    asciichat_error_t result = thread_pool_stop_all(g_client_worker_pool);
    if (result != ASCIICHAT_OK) {
      log_error("Failed to stop client worker threads");
      LOG_ERRNO_IF_SET("Thread pool stop failed");
    }
  }
  audio_sender_finalize();
  log_debug("[PROTOCOL_STOP] 14. thread_pool_stop_all() returned");
 
  g_data_thread_created = false;
 
#ifdef DEBUG_THREADS
  log_debug("Data reception thread stopped and joined by thread pool");
#endif
  log_debug("[PROTOCOL_STOP] 15. protocol_stop_connection complete");
}

References ASCIICHAT_OK, atomic_load_bool(), atomic_load_u64(), audio_sender_cleanup(), audio_sender_finalize(), audio_stop_thread(), capture_stop_thread(), g_client_worker_pool, g_h265_encoder, GET_OPTION, h265_encoder_flush(), keepalive_stop_thread(), log_debug, LOG_ERRNO_IF_SET, log_error, log_info, log_warn, platform_sleep_us(), SAFE_FREE, SAFE_MALLOC, server_connection_get_transport(), server_connection_is_active(), server_connection_shutdown(), thread_pool_stop_all(), and US_PER_MS_INT.