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.
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 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

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 151 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 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

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