main.c File Reference

ascii-chat Client Main Entry Point More...

Go to the source code of this file.

Data Structures
struct	client_session_state_t
	Client connection session state for session_client_like integration. More...

Functions
int	client_main (void)
	Client mode entry point for unified binary.

Variables
thread_pool_t *	g_client_worker_pool = NULL
	Global client worker thread pool.
app_client_t *	g_client = NULL
	Global client application context.
struct webrtc_peer_manager *	g_peer_manager = NULL
	Global WebRTC peer manager (legacy compatibility)

Detailed Description

ascii-chat Client Main Entry Point

This module serves as the main entry point for the ascii-chat client application. It orchestrates the entire client lifecycle including initialization, connection management, and the primary event loop that manages reconnection logic.

Architecture Overview

The client follows a modular threading architecture:

• Main thread: Connection management and event coordination
• Data reception thread: Handles incoming packets from server
• Ping thread: Maintains connection keepalive
• Webcam capture thread: Captures and transmits video frames
• Audio capture thread: Captures and transmits audio data (optional)

Connection Management

The client implements robust reconnection logic with exponential backoff:

1. Initial connection attempt
2. On connection loss, attempt reconnection with increasing delays
3. Maximum delay cap to prevent excessive wait times
4. Clean thread lifecycle management across reconnections

Thread Lifecycle

Each connection cycle follows this pattern:

1. Connection Establishment: Socket creation and server handshake
2. Thread Spawning: Start all worker threads for the connection
3. Active Monitoring: Monitor connection health and thread status
4. Connection Loss Detection: Detect broken connections via thread exit
5. Cleanup Phase: Join all threads and reset connection state
6. Reconnection Cycle: Repeat from step 1 unless shutdown requested

Integration Points

• server.c: Connection establishment and socket management
• protocol.c: Initial capability negotiation and join packets
• display.c: Terminal initialization and control
• capture.c: Media capture subsystem initialization
• audio.c: Audio subsystem initialization (if enabled)
• keepalive.c: Ping thread management

Error Handling

The main loop implements graceful error recovery:

• Fatal initialization errors cause immediate exit
• Network errors trigger reconnection attempts
• Signal handling for graceful shutdown (SIGINT, SIGWINCH)
• Resource cleanup on all exit paths

Platform Compatibility

Uses platform abstraction layer for:

• Socket operations and network initialization
• Thread management and synchronization
• Signal handling differences between Unix and Windows
• Terminal I/O and control sequences

Author

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

Date

October 2025

Version

2.0

Definition in file client/main.c.

Function Documentation

client_main()

int client_main

(

void

)

Client mode entry point for unified binary.

This function implements the complete client lifecycle including:

• Client-specific subsystem initialization (display, capture, audio)
• Server connection establishment with exponential backoff reconnection
• Main event loop coordinating connection state and thread lifecycle
• Media streaming (webcam frames and optional audio)
• Frame display to terminal
• Graceful shutdown and resource cleanup

Lifecycle Overview

The client follows this high-level state flow:

1. Initialize: Set up display, capture, audio subsystems
2. Connect Loop:
   • Establish TCP connection to server
   • Perform cryptographic handshake
   • Spawn worker threads (data reception, capture, keepalive, audio)
   • Monitor connection health
   • Detect connection loss via thread exit or socket errors
3. Cleanup: Stop threads, close socket, reset terminal
4. Reconnect: Exponential backoff, retry (unless fatal auth error)
5. Exit: On user signal (SIGINT) or fatal error

Connection Failure Handling

Transient Errors (retryable):

• Connection refused, timeout, DNS failure → exponential backoff retry
• Network temporarily unavailable → wait and retry

Fatal Errors (no retry):

• Authentication failed (CONNECTION_ERROR_AUTH_FAILED) → exit immediately
• Host key verification failed (CONNECTION_ERROR_HOST_KEY_FAILED) → exit immediately

Thread Management

The client spawns several worker threads coordinated by the main thread:

• Data Reception Thread: Receives and processes server packets
• Webcam Capture Thread: Captures frames, transmits to server
• Ping/Keepalive Thread: Sends periodic pings, detects timeouts
• Audio Threads (optional): Captures/plays audio with Opus encoding

All threads check the global g_should_exit flag and exit cleanly on shutdown. Main thread waits for all threads to exit before reconnection or final cleanup.

Options

Options are already parsed by the main dispatcher (src/main.c) before this function is called. They are available via the global options API (GET_OPTION, etc.).

Key options affecting behavior:

• opt_address: Server address or session string
• opt_port: Server port (default 27224)
• opt_audio_enabled: Enable audio capture/playback
• opt_snapshot: Capture single frame and exit
• opt_client_key, opt_server_key: SSH keys for authentication

Returns

Exit code:

• 0: Success (clean exit or snapshot completed)
• 1: Initialization/configuration error
• 2: Connection fatal error (auth failed)
• 130: Signal interrupt (SIGINT/Ctrl+C)

Example

# Invoked by dispatcher after options are parsed:
ascii-chat client --address localhost --audio
 
# Dispatcher (src/main.c) handles:
# - Option parsing
# - Log initialization
# - Signal handler setup
 
# Then calls client_main() which handles:
# - Subsystem init (display, capture, audio)
# - Connection loop with reconnection logic
# - Thread coordination
# - Graceful shutdown

See also

topic_client "Client Architecture Overview"

topic_client_main "Client Lifecycle Details"

topic_client_connection "Connection Management"

topic_client_protocol "Packet Processing"

Definition at line 630 of file client/main.c.

                      {
  log_debug("client_main() starting");
 
  // Register client crypto callbacks for TCP connection path
  // The TCP path in lib/network/connection_attempt.c relies on these callbacks
  // to handle cryptographic operations and key exchange
  static const app_callbacks_t client_crypto_callbacks = {
      .should_exit = should_exit,
      .signal_exit = signal_exit,
      .platform_get_monotonic_time_us = platform_get_monotonic_time_us,
      .platform_sleep_ms = platform_sleep_ms,
      .server_connection_set_ip = server_connection_set_ip,
      .server_connection_set_port = server_connection_set_port,
      .client_crypto_set_mode = client_crypto_set_mode,
      .client_crypto_init = client_crypto_init,
      .client_crypto_handshake = client_crypto_handshake,
      .crypto_client_is_ready = crypto_client_is_ready,
      .crypto_client_get_context = crypto_client_get_context,
  };
  app_callbacks_register(&client_crypto_callbacks);
 
  // Initialize client-specific systems (NOT shared with session_client_like)
  // This includes: thread pool, display layer, app client context, server connection
  int init_result = initialize_client_systems();
  if (init_result != 0) {
#ifndef NDEBUG
    // Debug builds: automatically fall back to test pattern if webcam is in use
    if (init_result == ERROR_WEBCAM_IN_USE && !GET_OPTION(test_pattern)) {
      log_warn("Webcam is in use - automatically falling back to test pattern mode (debug build only)");
 
      // Enable test pattern mode via RCU update
      asciichat_error_t update_result = options_set_bool("test_pattern", true);
      if (update_result != ASCIICHAT_OK) {
        log_error("Failed to update options for test pattern fallback");
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
 
      // Retry initialization with test pattern enabled
      init_result = initialize_client_systems();
      if (init_result != 0) {
        log_error("Failed to initialize even with test pattern fallback");
        webcam_print_init_error_help(init_result);
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
      log_debug("Successfully initialized with test pattern fallback");
 
      // Clear the error state since we successfully recovered
      CLEAR_ERRNO();
    } else
#endif
    {
      // Release builds or other errors: print help and exit
      if (init_result == ERROR_WEBCAM || init_result == ERROR_WEBCAM_IN_USE || init_result == ERROR_WEBCAM_PERMISSION) {
        webcam_print_init_error_help(init_result);
        FATAL(init_result, "%s", asciichat_error_string(init_result));
      }
      // For other errors, just exit with the error code
      return init_result;
    }
  }
 
  // Register cleanup function for graceful shutdown
  (void)atexit(shutdown_client);
 
  // Register client interrupt callback (socket shutdown on SIGTERM/Ctrl+C)
  // Global signal handlers (SIGTERM, SIGPIPE, Ctrl+C) are set up in setup_signal_handlers() in src/main.c
  set_interrupt_callback(server_connection_shutdown);
 
#ifndef _WIN32
  // Register SIGWINCH for terminal resize handling (client-specific, not in framework)
  platform_signal(SIGWINCH, client_handle_sigwinch);
#endif
 
  /* ========================================================================
   * Client-Specific: LAN/Session Discovery
   * ========================================================================
   * This phase discovers the server to connect to via:
   * - LAN discovery (mDNS)
   * - Session string lookup (ACDS)
   * - Direct address/port
   */
 
  // LAN Discovery: If --scan flag is set, discover servers on local network
  const options_t *opts = options_get();
  if (opts && opts->lan_discovery &&
      (opts->address[0] == '\0' || is_localhost_ipv4(opts->address) || strcmp(opts->address, "localhost") == 0)) {
    log_debug("LAN discovery: --scan flag set, querying for available servers");
 
    ui_mdns_config_t lan_config;
    memset(&lan_config, 0, sizeof(lan_config));
    lan_config.timeout_ms = 2 * MS_PER_SEC_INT; // Wait up to 2 seconds for responses
    lan_config.max_servers = 20;                // Support up to 20 servers on LAN
    lan_config.quiet = true;                    // Quiet during discovery, TUI will show status
 
    int discovered_count = 0;
    ui_mdns_server_t *discovered_servers = ui_mdns_query(&lan_config, &discovered_count);
 
    // Use TUI for server selection
    int selected_index = ui_mdns_select(discovered_servers, discovered_count);
 
    if (selected_index < 0) {
      // User cancelled or no servers found
      if (discovered_count == 0) {
        // No servers found - log message and prevent any further output
        // Lock the terminal so other threads can't write and our error
        // will be the last message
        log_lock_terminal();
 
        // Log single message with embedded newlines to prevent multiple log entries
        log_error("No ascii-chat servers found on the local network.\nUse 'ascii-chat client <address>' to connect "
                  "manually.");
 
        // Exit without cleanup
        platform_force_exit(1);
      }
      // User cancelled (had servers to choose from but pressed cancel)
      log_debug("LAN discovery: User cancelled server selection");
      if (discovered_servers) {
        ui_mdns_free_results(discovered_servers);
      }
      return 1; // User cancelled
    }
 
    // Update options with discovered server's address and port
    ui_mdns_server_t *selected = &discovered_servers[selected_index];
    const char *selected_address = ui_mdns_get_best_address(selected);
 
    // We need to modify options, but they're immutable via RCU
    // Create a new options copy with updated address/port
    options_t *opts_new = SAFE_MALLOC(sizeof(options_t), options_t *);
    if (opts_new) {
      memcpy(opts_new, opts, sizeof(options_t));
      SAFE_STRNCPY(opts_new->address, selected_address, sizeof(opts_new->address));
 
      opts_new->port = (int)selected->port;
 
      log_debug("LAN discovery: Selected server '%s' at %s:%d", selected->name, opts_new->address, opts_new->port);
 
      // Note: In a real scenario, we'd update the global options via RCU
      // For now, we'll use the updated values directly for connection
      // This is a known limitation - proper RCU update requires more infrastructure
    }
 
    ui_mdns_free_results(discovered_servers);
  }
 
  // =========================================================================
  // Client-Specific: Server Address Resolution
  // =========================================================================
  // Client mode supports:
  // 1. Direct address/port (--address HOST --port PORT) - handled by options
  // 2. LAN discovery (--scan) - handled above
  // 3. WebSocket URL (direct ws:// or wss:// connection string)
  //
  // Note: Session string discovery via ACDS is handled by discovery mode only.
  //       Client mode does NOT use ACDS or session strings.
 
  const char *discovered_address = NULL;
  int discovered_port = 0;
 
  // Check if user provided a WebSocket URL as the server address
  const options_t *opts_websocket = options_get();
  const char *provided_address = opts_websocket && opts_websocket->address[0] != '\0' ? opts_websocket->address : NULL;
 
  if (provided_address && url_is_websocket(provided_address)) {
    // Direct WebSocket connection
    log_debug("Client: Direct WebSocket URL: %s", provided_address);
    discovered_address = provided_address;
    discovered_port = 0; // Port is embedded in the URL
  }
 
  if (discovered_port > 0) {
    log_debug("Client: discovered_address=%s, discovered_port=%d", discovered_address ? discovered_address : "NULL",
              discovered_port);
  } else {
    log_debug("Client: discovered_address=%s", discovered_address ? discovered_address : "NULL");
  }
 
  // Store discovered address/port in session state for client_run() callback
  static char address_storage[BUFFER_SIZE_SMALL];
  if (discovered_address) {
    SAFE_STRNCPY(address_storage, discovered_address, sizeof(address_storage));
    g_client_session.discovered_address = address_storage;
    g_client_session.discovered_port = discovered_port;
  } else {
    const options_t *opts_fallback = options_get();
    if (opts_fallback && opts_fallback->address[0] != '\0') {
      SAFE_STRNCPY(address_storage, opts_fallback->address, sizeof(address_storage));
      g_client_session.discovered_address = address_storage;
      g_client_session.discovered_port = opts_fallback->port;
    } else {
      g_client_session.discovered_address = "localhost";
      g_client_session.discovered_port = 27224;
    }
  }
 
  // Initialize connection context for first attempt
  asciichat_error_t ctx_init_result = connection_context_init(&g_client_session.connection_ctx);
  if (ctx_init_result != ASCIICHAT_OK) {
    log_error("Failed to initialize connection context");
    return 1;
  }
 
  /* ========================================================================
   * Configure and Run Shared Client-Like Session Framework
   * ========================================================================
   * session_client_like_run() handles all shared initialization:
   * - Terminal output management (force stderr if piped)
   * - Keepawake system (platform sleep prevention)
   * - Splash screen lifecycle
   * - Media source selection (webcam, file, URL, test pattern)
   * - FPS probing for media files
   * - Audio initialization and lifecycle
   * - Display context creation
   * - Proper cleanup ordering (critical for PortAudio)
   *
   * Client mode provides:
   * - client_run() callback: connection loop, protocol startup, monitoring
   * - client_should_reconnect() callback: reconnection policy
   * - Reconnection configuration: attempts, delay, callbacks
   */
 
  // Get reconnect attempts setting (-1 = unlimited, 0 = no retry, >0 = retry N times)
  int reconnect_attempts = GET_OPTION(reconnect_attempts);
 
  // Configure session_client_like with client-specific settings
  session_client_like_config_t config = {
      .run_fn = client_run,
      .run_user_data = NULL,
      .kind = SESSION_CLIENT_LIKE_KIND_CLIENT,
      .discovery = NULL,
      .custom_should_exit = NULL,
      .exit_user_data = NULL,
      .keyboard_handler = NULL, // Client mode: server drives display
      .max_reconnect_attempts = reconnect_attempts,
      .should_reconnect_callback = client_should_reconnect,
      .reconnect_user_data = NULL,
      .reconnect_delay_ms = 1000,         // 1 second delay between reconnection attempts
      .print_newline_on_tty_exit = false, // Server/client manages cursor
  };
 
  log_debug("[CLIENT_MAIN] About to call session_client_like_run() with %d attempts", reconnect_attempts);
  asciichat_error_t session_result = session_client_like_run(&config);
  log_debug("[CLIENT_MAIN] session_client_like_run() returned %d", session_result);
 
  // Network client lifecycle is owned by connection_context_cleanup() after the session returns.
 
  // Cleanup connection context
  log_debug("[CLIENT_MAIN] About to call connection_context_cleanup()");
  connection_context_cleanup(&g_client_session.connection_ctx);
  log_debug("[CLIENT_MAIN] connection_context_cleanup() returned");
 
  // Cleanup session log buffer (used by splash screen in session_client_like)
  // NOTE: session_log_buffer_destroy() is already called in session_client_like_run()
  // during its cleanup phase, so we don't call it here to avoid double-destroy of mutex
 
  log_debug("[CLIENT_MAIN] ascii-chat client shutting down");
 
  // IMPORTANT: Stop worker threads and join them BEFORE memory report
  // atexit(shutdown_client) won't run if interrupted by SIGTERM, so call explicitly
  log_debug("[CLIENT_MAIN] About to call shutdown_client()");
  fflush(stderr);
  shutdown_client();
  log_debug("[CLIENT_MAIN] shutdown_client() returned");
  fflush(stderr);
 
  // Cleanup remaining shared subsystems (buffer pool, platform, etc.)
  log_debug("[CLIENT_MAIN] About to call asciichat_shared_destroy()");
  asciichat_shared_destroy();
 
  // Log final session statistics before exit
  // Note: Frame count is logged in protocol_stop_connection() if connection was established
  // This is a fallback in case the connection never started
  return (session_result == ASCIICHAT_OK) ? 0 : 1;
}

References options_state::address, app_callbacks_register(), ASCIICHAT_OK, asciichat_shared_destroy(), BUFFER_SIZE_SMALL, CLEAR_ERRNO, client_crypto_handshake(), client_crypto_init(), client_crypto_set_mode(), connection_context_cleanup(), connection_context_init(), client_session_state_t::connection_ctx, crypto_client_get_context(), crypto_client_is_ready(), client_session_state_t::discovered_address, client_session_state_t::discovered_port, ERROR_WEBCAM, ERROR_WEBCAM_IN_USE, ERROR_WEBCAM_PERMISSION, FATAL, GET_OPTION, is_localhost_ipv4(), options_state::lan_discovery, log_debug, log_error, log_lock_terminal(), log_warn, ui_mdns_config_t::max_servers, MS_PER_SEC_INT, ui_mdns_server_t::name, options_get(), options_set_bool(), platform_force_exit(), platform_get_monotonic_time_us(), platform_signal(), platform_sleep_ms(), options_state::port, ui_mdns_server_t::port, ui_mdns_config_t::quiet, session_client_like_config::run_fn, SAFE_MALLOC, SAFE_STRNCPY, server_connection_set_ip(), server_connection_set_port(), server_connection_shutdown(), SESSION_CLIENT_LIKE_KIND_CLIENT, session_client_like_run(), set_interrupt_callback(), should_exit(), app_callbacks_t::should_exit, signal_exit(), ui_mdns_config_t::timeout_ms, ui_mdns_free_results(), ui_mdns_get_best_address(), ui_mdns_query(), ui_mdns_select(), url_is_websocket(), and webcam_print_init_error_help().

Variable Documentation

g_client

app_client_t* g_client = NULL

Global client application context.

Global application client context

Central connection and application state for the client. Contains transport-agnostic state: audio, threads, display, crypto. Network-specific state (socket, connection flags) is in the active transport client.

Initialized by app_client_create() in client_main(). Destroyed by app_client_destroy() at cleanup.

Definition at line 152 of file client/main.c.

g_client_worker_pool

thread_pool_t* g_client_worker_pool = NULL

Global client worker thread pool.

Global client worker thread pool

Manages all client worker threads including:

• Data reception thread (protocol.c)
• Webcam capture thread (capture.c)
• Ping/keepalive thread (keepalive.c)
• Audio capture thread (audio.c)
• Audio sender thread (audio.c)

Definition at line 140 of file client/main.c.

Referenced by audio_sender_init(), audio_start_thread(), capture_start_thread(), keepalive_start_thread(), protocol_start_connection(), and protocol_stop_connection().

g_peer_manager

struct webrtc_peer_manager* g_peer_manager = NULL

Global WebRTC peer manager (legacy compatibility)

Global WebRTC peer manager for P2P connections.

Client mode no longer uses WebRTC, but protocol.c still references this. Always NULL in client mode.

Definition at line 160 of file client/main.c.