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 initialization (display, capture, audio)
• Server connection with reconnection logic
• Media streaming and frame display
• Graceful shutdown and cleanup

Options are already parsed by the main dispatcher before this function is called, so they are available via global opt_* variables.

Returns

0 on success, non-zero error code on failure

Example

# Invoked by dispatcher after options are parsed:
ascii-chat client --address localhost --audio
# Options parsed in main.c, then client_main() called

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

                      {
  log_debug("client_main() starting");
 
  // 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");
 
    discovery_tui_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;
    discovery_tui_server_t *discovered_servers = discovery_tui_query(&lan_config, &discovered_count);
 
    // Use TUI for server selection
    int selected_index = discovery_tui_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) {
        discovery_tui_free_results(discovered_servers);
      }
      return 1; // User cancelled
    }
 
    // Update options with discovered server's address and port
    discovery_tui_server_t *selected = &discovered_servers[selected_index];
    const char *selected_address = discovery_tui_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
    }
 
    discovery_tui_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
  }
 
  log_debug("Client: discovered_address=%s, discovered_port=%d", discovered_address ? discovered_address : "NULL",
            discovered_port);
 
  // 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,
      .tcp_client = NULL,
      .websocket_client = NULL,
      .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: calling session_client_like_run() with %d max reconnection attempts", reconnect_attempts);
  asciichat_error_t session_result = session_client_like_run(&config);
  log_debug("Client: session_client_like_run() returned %d", session_result);
 
  // Cleanup connection context
  connection_context_cleanup(&g_client_session.connection_ctx);
 
  // Cleanup session log buffer (used by splash screen in session_client_like)
  session_log_buffer_destroy();
 
  log_debug("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
  shutdown_client();
 
  // Cleanup remaining shared subsystems (buffer pool, platform, etc.)
  // Note: atexit(asciichat_shared_destroy) is registered in main.c,
  // but won't run if interrupted by signals (SIGTERM from timeout/killall)
  asciichat_shared_destroy();
 
  return (session_result == ASCIICHAT_OK) ? 0 : 1;
}

References asciichat_shared_destroy(), connection_context_cleanup(), connection_context_init(), client_session_state_t::connection_ctx, client_session_state_t::discovered_address, client_session_state_t::discovered_port, discovery_tui_free_results(), discovery_tui_get_best_address(), discovery_tui_query(), discovery_tui_select(), is_localhost_ipv4(), log_lock_terminal(), options_get(), options_set_bool(), server_connection_shutdown(), session_client_like_run(), session_log_buffer_destroy(), set_interrupt_callback(), 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 151 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 139 of file client/main.c.

Referenced by 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 159 of file client/main.c.