main.h File Reference

ascii-chat Client Mode Entry Point Header More...

Go to the source code of this file.

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

Variables
crypto_handshake_context_t	g_crypto_ctx
	Global crypto handshake context for this client connection.
h265_encoder_t *volatile	g_h265_encoder
	Global H.265 encoder context for client video streaming.
thread_pool_t *	g_client_worker_pool
	Global client worker thread pool.
app_client_t *	g_client
	Global client application context.
struct webrtc_peer_manager *	g_peer_manager
	Global WebRTC peer manager for P2P connections.

Detailed Description

ascii-chat Client Mode Entry Point Header

This header exposes the client mode entry point for the unified binary architecture. The unified binary dispatches to client_main() when invoked as ascii-chat client.

Unified Binary Architecture

The ascii-chat application uses a single binary with multiple operating modes:

• ascii-chat server - Run as server (multi-client connection manager)
• ascii-chat client - Run as client (connects to server, streams video/audio)

This design provides several benefits:

• Simplified distribution (single binary to install)
• Reduced disk space (shared library code)
• Easier testing (one binary to build and deploy)
• Consistent versioning across modes

Mode Entry Point Contract

Each mode entry point (server_main, client_main) must:

• Accept no arguments: int mode_main(void)
• Options are already parsed by main dispatcher (available via global opt_* variables)
• Return 0 on success, non-zero error code on failure
• Perform mode-specific initialization and main loop
• Perform complete cleanup before returning

Implementation Notes

The client_main() function is the original main() from src/client/main.c, adapted to the new dispatcher pattern. Common initialization (options parsing, logging setup, lock debugging, –show-capabilities) now happens in src/main.c before dispatch.

Author

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

Date

2025

Version

2.0

Definition in file client/main.h.

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

extern

Global client application context.

Central state management structure for the client, containing both network and application-layer state.

This instance provides:

• Connection state management via active_transport (TCP or WebSocket)
• Audio queue management for async audio streaming
• Thread handles for worker threads (data reception, capture, ping, audio)
• Display state and terminal capability tracking
• Crypto handshake context for encrypted connections
• Protocol state (client ID, server initialization status)

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

All client modules (protocol.c, audio.c, capture.c, display.c) should use this instance instead of accessing global connection state.

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

extern

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)

This pool is initialized in client_main() and accessible from all client modules for spawning and managing worker threads.

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_h265_encoder

h265_encoder_t* volatile g_h265_encoder

extern

Global H.265 encoder context for client video streaming.

Encodes captured RGB frames to H.265/HEVC format before transmission. Initialized in client_main() and used by capture thread. Set to NULL during shutdown to prevent use-after-free.

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

Referenced by protocol_stop_connection(), and threaded_send_image_frame_h265().

g_peer_manager

struct webrtc_peer_manager* g_peer_manager

extern

Global WebRTC peer manager for P2P connections.

Manages WebRTC peer connections for ACDS session participants. Handles SDP/ICE exchange and DataChannel lifecycle for P2P ACIP transport.

NULL if WebRTC not initialized (TCP-only mode). Initialized when joining/creating ACDS sessions with WebRTC transport.

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.