Connection Management

🔗 Server connection establishment, packet transmission, and state tracking More...

Files
file	server.c
	🌐 Client connection manager: TCP connection, reconnection with exponential backoff, and thread-safe transmission
file	server.h
	ascii-chat Client Server Connection Management Interface

Functions
int	server_connection_init ()
	Initialize the server connection management subsystem.
int	server_connection_establish (const char *address, int port, int reconnect_attempt, bool first_connection, bool has_ever_connected)
	Establish connection to ascii-chat server.
bool	server_connection_is_active ()
	Check if server connection is currently active.
socket_t	server_connection_get_socket ()
	Get current socket file descriptor.
acip_transport_t *	server_connection_get_transport (void)
	Get ACIP transport instance.
void	server_connection_set_transport (acip_transport_t *transport)
	Set ACIP transport instance from connection fallback.
uint32_t	server_connection_get_client_id ()
	Get client ID assigned by server.
const char *	server_connection_get_ip ()
	Get resolved server IP address.
void	server_connection_set_ip (const char *ip)
	Set the server IP address.
void	server_connection_set_port (int port)
	Set the server port.
int	server_connection_get_port (void)
	Get the server port.
void	server_connection_close ()
	Close the server connection gracefully.
void	server_connection_shutdown ()
	Emergency connection shutdown for signal handlers.
void	server_connection_lost ()
	Signal that connection has been lost.
bool	server_connection_is_lost ()
	Check if connection loss has been detected.
void	server_connection_cleanup ()
	Cleanup connection management subsystem.
asciichat_error_t	threaded_send_packet (packet_type_t type, const void *data, size_t len)
	Thread-safe packet transmission.
int	threaded_send_audio_batch_packet (const float *samples, int num_samples, int batch_count)
	Thread-safe batched audio packet transmission.
asciichat_error_t	threaded_send_audio_opus (const uint8_t *opus_data, size_t opus_size, int sample_rate, int frame_duration)
	Thread-safe Opus audio frame transmission.
asciichat_error_t	threaded_send_audio_opus_batch (const uint8_t *opus_data, size_t opus_size, const uint16_t *frame_sizes, int frame_count)
	Thread-safe Opus audio batch packet transmission.
asciichat_error_t	threaded_send_image_frame (const void *pixel_data, uint32_t width, uint32_t height, uint32_t pixel_format)
	Thread-safe image frame transmission.
asciichat_error_t	threaded_send_image_frame_h265 (const void *pixel_data, uint32_t width, uint32_t height)
	Send H.265-encoded video frame to server (thread-safe)
int	threaded_send_ping_packet (void)
	Thread-safe ping packet transmission.
int	threaded_send_pong_packet (void)
	Thread-safe pong packet transmission.
asciichat_error_t	threaded_send_stream_start_packet (uint32_t stream_type)
	Thread-safe stream start packet transmission.
asciichat_error_t	threaded_send_terminal_size_with_auto_detect (unsigned short width, unsigned short height)
	Thread-safe terminal size packet transmission with auto-detection.
int	threaded_send_client_join_packet (const char *display_name, uint32_t capabilities)
	Thread-safe client join packet transmission.
int	server_send_packet (packet_type_t type, const void *data, size_t len)
	Send general packet to server.
int	server_send_audio (const float *samples, int num_samples)
	Send audio data to server.
int	server_send_audio_batch (const float *samples, int num_samples, int batch_count)
	Send batched audio data to server.
int	server_send_terminal_capabilities (unsigned short width, unsigned short height)
	Send terminal capabilities to server.
int	server_send_ping ()
	Send ping keepalive packet.
int	server_send_pong ()
	Send pong response packet.
int	server_send_stream_start (uint32_t stream_type)
	Send stream start notification.
int	server_send_stream_stop (uint32_t stream_type)
	Send stream stop notification.

Variables
crypto_handshake_context_t	g_crypto_ctx = {0}
	Per-connection crypto handshake context.

Detailed Description

🔗 Server connection establishment, packet transmission, and state tracking

Connection Management

Overview

The connection management subsystem handles TCP socket creation, connection establishment, cryptographic handshake coordination, and thread-safe packet transmission to the server.

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

Connection State

Global State Variables:

• g_sockfd: Socket file descriptor
• g_client_id: Server-assigned client ID
• g_server_ip: Resolved server IP address
• g_connection_active: Atomic boolean for connection status
• g_connection_lost: Atomic boolean for connection loss detection
• g_send_mutex: Mutex protecting all packet sends

Connection Establishment

Connection Flow

int server_connection_establish(const char *address, int port,
                                int reconnect_attempt, bool first_connection,
                                bool has_ever_connected)
{
  // 1. Create socket
  socket_t sockfd = socket(AF_INET, SOCK_STREAM, 0);
 
  // 2. Resolve address (IPv4/IPv6)
  struct addrinfo *result = resolve_address(address, port);
 
  // 3. Connect with timeout
  if (connect(sockfd, result->ai_addr, result->ai_addrlen) < 0) {
    return CONNECTION_ERROR_GENERIC;
  }
 
  // 4. Perform cryptographic handshake
  crypto_handshake_result_t handshake_result =
    perform_crypto_handshake_client(sockfd, &crypto_ctx, opt_server_key,
                                    server_ip, opt_client_key);
 
  if (handshake_result != HANDSHAKE_SUCCESS &&
      handshake_result != HANDSHAKE_WARNING_NO_CLIENT_AUTH) {
    socket_close(sockfd);
    return map_handshake_error(handshake_result);
  }
 
  // 5. Send client capabilities
  send_client_capabilities();
 
  // 6. Update global state
  g_sockfd = sockfd;
  atomic_store(&g_connection_active, true);
  atomic_store(&g_connection_lost, false);
 
  return CONNECTION_SUCCESS;
}

Connection Error Codes

Error Types:

• CONNECTION_SUCCESS (0): Connection established successfully
• CONNECTION_WARNING_NO_CLIENT_AUTH (1): Connected but server not verifying client
• CONNECTION_ERROR_GENERIC (-1): Network error (allow retry)
• CONNECTION_ERROR_AUTH_FAILED (-2): Client authentication failed (no retry)
• CONNECTION_ERROR_HOST_KEY_FAILED (-3): Server host key verification failed (no retry)

Packet Transmission

Thread-Safe Packet Send

int send_packet_to_server(packet_type_t type, const void *data, size_t data_len,
                         uint32_t client_id)
{
  // Thread-safe send with global mutex
  mutex_lock(&g_send_mutex);
 
  // Check connection status
  if (!server_connection_is_active()) {
    mutex_unlock(&g_send_mutex);
    return -1;
  }
 
  // Send encrypted packet
  int result = send_packet(g_sockfd, &crypto_ctx, type, data, data_len, client_id);
 
  mutex_unlock(&g_send_mutex);
 
  // Detect connection loss on send error
  if (result < 0) {
    server_connection_lost();
  }
 
  return result;
}

Thread Safety:

• ALL packet sends MUST go through send_packet_to_server()
• Global g_send_mutex prevents interleaved packets
• Socket FD checked under mutex protection
• Connection loss detected atomically

Connection Loss Detection

Loss Detection Triggers

Connection loss detected by:

1. Socket write error during send_packet_to_server()
2. Socket read error during receive_packet() in protocol thread
3. Keepalive timeout (no pong for 30 seconds)
4. Decryption failure (corrupted stream)

Loss Handling

void server_connection_lost(void)
{
  // Atomic compare-exchange ensures only first detection triggers action
  bool expected = true;
  if (atomic_compare_exchange_strong(&g_connection_active, &expected, false)) {
    // First thread to detect loss
    atomic_store(&g_connection_lost, true);
    log_warn("Connection lost detected");
  }
}

Connection Cleanup

Graceful Close

void server_connection_close(void)
{
  if (g_sockfd != INVALID_SOCKET_VALUE) {
    socket_shutdown(g_sockfd, SHUT_RDWR);  // Signal shutdown
    socket_close(g_sockfd);                 // Close socket
    g_sockfd = INVALID_SOCKET_VALUE;
  }
 
  atomic_store(&g_connection_active, false);
  g_client_id = 0;
}

Emergency Shutdown

void server_connection_shutdown(void)
{
  // Signal-safe emergency shutdown
  if (g_sockfd != INVALID_SOCKET_VALUE) {
    socket_close(g_sockfd);  // Immediate close (no shutdown)
    g_sockfd = INVALID_SOCKET_VALUE;
  }
}

Best Practices

DO:

• Always use send_packet_to_server() for packet transmission
• Check server_connection_is_active() before operations
• Use atomic operations for connection state flags
• Wait for thread exit before reconnection

DON'T:

• Don't send packets without g_send_mutex
• Don't close socket while threads may be using it
• Don't ignore return values from send operations
• Don't modify g_sockfd directly (use provided functions)

See also

src/client/server.c

src/client/server.h

Client Overview

Function Documentation

server_connection_cleanup()

void server_connection_cleanup

(

)

#include <server.c>

Cleanup connection management subsystem.

Closes any active connection and destroys synchronization objects. Called during client shutdown.

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

                                 {
  if (!GET_OPTION(quiet)) {
    log_set_terminal_output(true);
  }
  server_connection_close();
  mutex_destroy(&g_send_mutex);
}

References GET_OPTION, log_set_terminal_output(), mutex_destroy(), and server_connection_close().

server_connection_close()

void server_connection_close

(

)

#include <server.c>

Close the server connection gracefully.

Close server connection gracefully.

Marks connection as inactive and closes the socket. This function is safe to call multiple times and from multiple threads.

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

                               {
  log_debug("[TRANSPORT_LIFECYCLE] server_connection_close() called");
 
  // Acquire send mutex to prevent race with threaded_send_image_frame()
  // This ensures any in-flight sends complete before we destroy the transport
  mutex_lock(&g_send_mutex);
  atomic_store_bool(&g_connection_active, false);
 
  // Destroy ACIP transport before closing socket
  if (g_client_transport) {
    log_debug("[TRANSPORT_LIFECYCLE] Destroying transport=%p (is_connected=%s) before closing socket",
              (void *)g_client_transport, acip_transport_is_connected(g_client_transport) ? "true" : "false");
    acip_transport_destroy(g_client_transport);
    g_client_transport = NULL;
    log_debug("[TRANSPORT_LIFECYCLE] Transport destroyed, g_client_transport set to NULL");
  }
 
  mutex_unlock(&g_send_mutex);
 
  // The socket belongs to the connection handle's TCP/WebSocket owner. The
  // caller cleans up that owner after protocol workers have stopped; closing
  // g_sockfd here would close the same descriptor a second time.
  g_sockfd = INVALID_SOCKET_VALUE;
 
  g_my_client_id = 0;
 
  // Cleanup crypto context if encryption was enabled
  if (g_encryption_enabled) {
    log_debug("[TRANSPORT_LIFECYCLE] Cleaning up crypto context");
    crypto_handshake_destroy(&g_crypto_ctx);
    g_encryption_enabled = false;
  }
 
  // Turn ON terminal logging when connection is closed (unless it was disabled with --quiet)
  if (!GET_OPTION(quiet)) {
    log_set_terminal_output(true);
  }
  log_debug("[TRANSPORT_LIFECYCLE] server_connection_close() completed");
}

References acip_transport_destroy(), atomic_store_bool(), crypto_handshake_destroy(), g_crypto_ctx, GET_OPTION, INVALID_SOCKET_VALUE, log_debug, log_set_terminal_output(), mutex_lock, and mutex_unlock.

Referenced by server_connection_cleanup().

server_connection_establish()

int server_connection_establish	(	const char *	address,
		int	port,
		int	reconnect_attempt,
		bool	first_connection,
		bool	has_ever_connected
	)

#include <server.c>

Establish connection to ascii-chat server.

Attempts to connect to the specified server with full capability negotiation. Implements reconnection logic with exponential backoff for failed attempts. On successful connection, performs initial handshake including terminal capabilities and client join protocol.

Parameters

address	Server IP address or hostname
port	Server port number
reconnect_attempt	Current reconnection attempt number (0 for first)
first_connection	True if this is the initial connection attempt
has_ever_connected	True if a connection was ever successfully established

Returns

0 on success, negative on error

Establishes a TCP connection to the server and performs the cryptographic handshake. This function handles DNS resolution, socket creation, connection establishment, and authentication. It is designed for use in a reconnection loop with exponential backoff.

Parameters

address	Server IP address, hostname, or ACDS session string (e.g., "localhost", "192.168.1.100", or "blue-mountain-tiger")
port	Server port number (typically 27224)
reconnect_attempt	Current reconnection attempt number (0 for first attempt). Used to track retry count for logging and backoff calculation.
first_connection	Whether this is the client's first attempt to connect. If true, displays more informative messages. If false, this is a reconnection attempt after previous connection loss.
has_ever_connected	Whether the client has EVER successfully connected in this session. Used to distinguish "first attempt ever" from "reconnection attempt".

Returns

Connection establishment status:

• CONNECTION_SUCCESS (0): Connection established and authenticated successfully
• CONNECTION_WARNING_NO_CLIENT_AUTH (1): Connected but server is not verifying client identity
• CONNECTION_ERROR_GENERIC (-1): Network error (resolve failed, connect refused, timeout). Caller should retry with exponential backoff.
• CONNECTION_ERROR_AUTH_FAILED (-2): Authentication failed (wrong password, bad SSH key). Caller should NOT retry - user intervention required.
• CONNECTION_ERROR_HOST_KEY_FAILED (-3): Server host key verification failed. Caller should NOT retry - user must update known_hosts.

Connection Lifecycle

1. Resolution: Resolves hostname/IP to socket address (supports IPv4 and IPv6)
2. Socket Creation: Creates TCP socket with appropriate options
3. Connection: Attempts TCP connect with timeout
4. Handshake: Performs cryptographic handshake (X25519 key exchange, Ed25519 auth)
5. Initialization: Sends client capabilities and client join packet
6. State Update: Updates global connection state atomically

Error Recovery

Retryable (CONNECTION_ERROR_GENERIC):

• Connection refused: Server not listening yet
• Connection timeout: Network slow or firewall blocking
• DNS resolution failure: Temporary DNS issue
• Socket creation failure: System resource exhaustion

Caller should implement exponential backoff:

int result = server_connection_establish(address, port, attempt, first, ever_connected);
if (result == CONNECTION_ERROR_GENERIC) {
  // Exponential backoff: 10ms, 210ms, 410ms, 610ms, ..., capped at 5 seconds
  int delay_ms = 10 + (200 * attempt);
  if (delay_ms > 5000) delay_ms = 5000;
  sleep_ms(delay_ms);
  attempt++;
  continue;  // Retry
}

Non-Retryable (AUTH or HOST_KEY failures):

• CONNECTION_ERROR_AUTH_FAILED: Password or SSH key doesn't match server's expectations
• CONNECTION_ERROR_HOST_KEY_FAILED: Server's public key not in client's known_hosts

These indicate configuration problems that won't be fixed by waiting or retrying.

See also

server_connection_is_active "Check connection status"

server_connection_close "Close connection gracefully"

server_connection_lost "Signal connection loss (called by other threads)"

topic_client_connection "Connection Management Architecture"

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

                                                         {
  (void)first_connection; // Currently unused
  if (!address || port <= 0) {
    log_error("Invalid address or port parameters");
    return -1;
  }
 
  // Close any existing connection
  if (g_sockfd != INVALID_SOCKET_VALUE) {
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
  }
 
  // Apply reconnection delay if this is a retry
  if (reconnect_attempt > 0) {
    unsigned int delay_us = get_reconnect_delay(reconnect_attempt);
    // Reconnection attempt logged only to file
    platform_sleep_us(delay_us);
 
    // Check if user requested exit during reconnection delay
    if (should_exit()) {
      log_debug("Exit requested during reconnection delay");
      return -1;
    }
  } else {
    // Initial connection logged only to file
  }
 
  connection_endpoint_t endpoint = {0};
  asciichat_error_t endpoint_result = connection_endpoint_resolve(address, port, &endpoint);
  if (endpoint_result != ASCIICHAT_OK) {
    log_error("Failed to resolve connection endpoint: %s", asciichat_error_string(endpoint_result));
    return -1;
  }
 
  // Check for WebSocket URL - handle separately from TCP
  if (endpoint.protocol == CONNECTION_ENDPOINT_WEBSOCKET) {
    // WebSocket connection - bypass TCP socket creation
    // Use the original address (URL already contains port if specified)
    const char *ws_url = endpoint.input;
    log_info("Connecting via WebSocket: %s (host=%s, port=%u)", ws_url, endpoint.host, endpoint.port);
 
    // Set server IP and port for crypto handshake
    // This ensures the crypto context has proper server address info for known_hosts verification
    server_connection_set_ip(endpoint.host);
    server_connection_set_port(endpoint.port);
    log_debug("CLIENT_CONNECT: Set server IP=%s, port=%u from WebSocket endpoint", endpoint.host, endpoint.port);
 
    // Initialize crypto if encryption is enabled
    log_debug("CLIENT_CONNECT: Calling client_crypto_init()");
    if (client_crypto_init() != 0) {
      log_error("Failed to initialize crypto (password required or incorrect)");
      log_debug("CLIENT_CONNECT: client_crypto_init() failed");
      return CONNECTION_ERROR_AUTH_FAILED;
    }
 
    // Get crypto context for transport
    const crypto_context_t *crypto_ctx = crypto_client_is_ready() ? crypto_client_get_context() : NULL;
 
    // Create WebSocket transport through the shared factory.
    asciichat_error_t ws_result =
        connection_factory_open("client", ws_url, 0, (crypto_context_t *)crypto_ctx, &g_client_transport, &endpoint);
    if (ws_result != ASCIICHAT_OK) {
      log_error("Failed to create WebSocket ACIP transport");
      return -1;
    }
    if (!g_client_transport) {
      log_error("Failed to create WebSocket ACIP transport");
      return -1;
    }
    log_debug("CLIENT_CONNECT: Created WebSocket ACIP transport with crypto context");
 
    // Set connection as active
    atomic_store_bool(&g_connection_active, true);
    atomic_store_bool(&g_connection_lost, false);
 
    // CRITICAL: Wait for WebSocket connection to be established before sending
    // The service thread is running but may not have completed TLS handshake yet
    // Don't block indefinitely - use timeout loops to allow responsiveness
    log_debug("CLIENT_CONNECT: Waiting for WebSocket connection to be established...");
    const int CONNECT_CHECK_ATTEMPTS = 300; // 300 * 50ms = 15 seconds timeout
    int connect_attempts = 0;
    while (!acip_transport_is_connected(g_client_transport) && connect_attempts < CONNECT_CHECK_ATTEMPTS) {
      platform_sleep_us(50000); // Sleep 50ms between checks
      connect_attempts++;
      if (connect_attempts % 20 == 0) { // Log every 1 second (20 * 50ms)
        log_info("CLIENT_CONNECT: Waiting for connection... (%d seconds elapsed)", connect_attempts / 20);
      }
    }
 
    if (!acip_transport_is_connected(g_client_transport)) {
      log_error("Failed to establish WebSocket connection within 15 seconds");
      acip_transport_destroy(g_client_transport);
      g_client_transport = NULL;
      atomic_store_bool(&g_connection_active, false);
      return -1;
    }
 
    log_info("CLIENT_CONNECT: WebSocket connection established, proceeding with handshake");
 
    // Send initial terminal capabilities to server
    int result = threaded_send_terminal_size_with_auto_detect((int)terminal_get_effective_width(),
                                                              (int)terminal_get_effective_height());
    if (result < 0) {
      log_error("Failed to send initial capabilities to server: %s", network_error_string());
      acip_transport_destroy(g_client_transport);
      g_client_transport = NULL;
      return -1;
    }
 
    // Disable terminal logging after initial setup (for non-snapshot mode)
    if (!GET_OPTION(snapshot_mode) && has_ever_connected) {
      log_set_terminal_output(false);
    }
 
    // Build capabilities flags
    uint32_t my_capabilities = CLIENT_CAP_VIDEO;
    log_debug("GET_OPTION(audio_enabled) = %d (sending CLIENT_JOIN)", GET_OPTION(audio_enabled));
    if (GET_OPTION(audio_enabled)) {
      log_debug("Adding CLIENT_CAP_AUDIO to capabilities");
      my_capabilities |= CLIENT_CAP_AUDIO;
    }
    if (GET_OPTION(color_mode) != COLOR_MODE_NONE) {
      my_capabilities |= CLIENT_CAP_COLOR;
    }
    if (GET_OPTION(stretch)) {
      my_capabilities |= CLIENT_CAP_STRETCH;
    }
 
    // Generate display name from username + PID
    const char *display_name = platform_get_username();
    char my_display_name[MAX_DISPLAY_NAME_LEN];
    int pid = getpid();
    SAFE_SNPRINTF(my_display_name, sizeof(my_display_name), "%s-%d", display_name, pid);
    if (threaded_send_client_join_packet(my_display_name, my_capabilities) < 0) {
      log_error("Failed to send client join packet: %s", network_error_string());
      acip_transport_destroy(g_client_transport);
      g_client_transport = NULL;
      return -1;
    }
 
    log_info("WebSocket connection established successfully");
    return 0;
  }
 
  asciichat_error_t connect_result =
      connection_factory_open("client", address, (uint16_t)port, NULL, &g_client_transport, &endpoint);
  if (connect_result != ASCIICHAT_OK || !g_client_transport) {
    log_error("Failed to establish TCP transport: %s", asciichat_error_string(connect_result));
    return -1;
  }
 
  g_sockfd = g_client_transport->methods->get_socket(g_client_transport);
  if (g_sockfd == INVALID_SOCKET_VALUE) {
    log_error("TCP transport did not expose a valid socket");
    acip_transport_destroy(g_client_transport);
    g_client_transport = NULL;
    return -1;
  }
 
  SAFE_STRNCPY(g_server_ip, endpoint.host, sizeof(g_server_ip));
  log_debug("CLIENT_CONNECT: Resolved TCP endpoint host=%s port=%u", endpoint.host, endpoint.port);
 
  // Connection successful - extract local port for client ID
  struct sockaddr_storage local_addr = {0};
  socklen_t addr_len = sizeof(local_addr);
  if (getsockname(g_sockfd, (struct sockaddr *)&local_addr, &addr_len) == -1) {
    log_error("Failed to get local socket address: %s", network_error_string());
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
 
  // Extract port from either IPv4 or IPv6 address
  int local_port = 0;
  if (((struct sockaddr *)&local_addr)->sa_family == AF_INET) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in *)&local_addr)->sin_port);
  } else if (((struct sockaddr *)&local_addr)->sa_family == AF_INET6) {
    local_port = NET_TO_HOST_U16(((struct sockaddr_in6 *)&local_addr)->sin6_port);
  }
  g_my_client_id = (uint32_t)local_port;
 
  // Mark connection as active immediately after successful socket connection
  atomic_store_bool(&g_connection_active, true);
  atomic_store_bool(&g_connection_lost, false);
  atomic_store_bool(&g_should_reconnect, false);
 
  // Initialize crypto BEFORE starting protocol handshake
  // Note: server IP is already set above in the connection loop
  log_debug("CLIENT_CONNECT: Calling client_crypto_init()");
  if (client_crypto_init() != 0) {
    log_error("Failed to initialize crypto (password required or incorrect)");
    log_debug("CLIENT_CONNECT: client_crypto_init() failed");
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    return CONNECTION_ERROR_AUTH_FAILED; // SSH key password was wrong - no retry
  }
 
  // Create the persistent TCP transport before handshake.
  // It starts with NULL crypto; client_crypto_handshake() sets crypto_ctx on success.
  g_client_transport = acip_tcp_transport_create("client", g_sockfd, NULL);
  if (!g_client_transport) {
    log_error("Failed to create TCP ACIP transport");
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
  log_debug("CLIENT_CONNECT: Created TCP ACIP transport (crypto pending handshake)");
 
  // Perform crypto handshake if encryption is enabled
  log_debug("CLIENT_CONNECT: Calling client_crypto_handshake()");
  int handshake_result = client_crypto_handshake(g_client_transport);
  if (handshake_result != 0) {
    log_error("Crypto handshake failed");
    log_debug("CLIENT_CONNECT: client_crypto_handshake() failed with code %d", handshake_result);
    acip_transport_destroy(g_client_transport);
    g_client_transport = NULL;
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    FATAL(ERROR_CRYPTO_HANDSHAKE,
          "Crypto handshake failed with server - this usually indicates a protocol mismatch or network issue");
  }
  log_debug("CLIENT_CONNECT: client_crypto_handshake() succeeded");
 
  // Turn OFF terminal logging when successfully connected to server
  // First connection - we'll disable logging after main.c shows the "Connected successfully" message
  if (!GET_OPTION(snapshot_mode)) {
    log_debug("Connected to server - terminal logging will be disabled after initial setup");
  } else {
    log_debug("Connected to server - terminal logging kept enabled for snapshot mode");
  }
 
  // Configure socket options for optimal performance
  if (socket_set_keepalive(g_sockfd, true) < 0) {
    log_warn("Failed to set socket keepalive: %s", network_error_string());
  }
 
  // Configure socket buffers and TCP_NODELAY for optimal performance
  asciichat_error_t sock_config_result = socket_configure_buffers(g_sockfd);
  if (sock_config_result != ASCIICHAT_OK) {
    log_warn("Failed to configure socket: %s", network_error_string());
  }
 
  // Send initial terminal capabilities to server (this may generate debug logs)
  int result = threaded_send_terminal_size_with_auto_detect((int)terminal_get_effective_width(),
                                                            (int)terminal_get_effective_height());
  if (result < 0) {
    log_error("Failed to send initial capabilities to server: %s", network_error_string());
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
 
  // Now disable terminal logging after capabilities are sent (for reconnections)
  if (!GET_OPTION(snapshot_mode) && has_ever_connected) {
    log_set_terminal_output(false);
    log_debug("Reconnected to server - terminal logging disabled to prevent interference with ASCII display");
  }
 
  // Send client join packet for multi-user support
  uint32_t my_capabilities = CLIENT_CAP_VIDEO; // Basic video capability
  log_debug("GET_OPTION(audio_enabled) = %d (sending CLIENT_JOIN)", GET_OPTION(audio_enabled));
  if (GET_OPTION(audio_enabled)) {
    log_debug("Adding CLIENT_CAP_AUDIO to capabilities");
    my_capabilities |= CLIENT_CAP_AUDIO;
  }
  if (GET_OPTION(color_mode) != COLOR_MODE_NONE) {
    my_capabilities |= CLIENT_CAP_COLOR;
  }
  if (GET_OPTION(stretch)) {
    my_capabilities |= CLIENT_CAP_STRETCH;
  }
 
  // Generate display name from username + PID
  const char *display_name = platform_get_username();
 
  char my_display_name[MAX_DISPLAY_NAME_LEN];
  int pid = getpid();
  SAFE_SNPRINTF(my_display_name, sizeof(my_display_name), "%s-%d", display_name, pid);
 
  if (threaded_send_client_join_packet(my_display_name, my_capabilities) < 0) {
    log_error("Failed to send client join packet: %s", network_error_string());
    close_socket(g_sockfd);
    g_sockfd = INVALID_SOCKET_VALUE;
    return -1;
  }
 
  // Connection already marked as active after socket creation
 
  return 0;
}

References acip_tcp_transport_create(), acip_transport_destroy(), ASCIICHAT_OK, atomic_store_bool(), CLIENT_CAP_AUDIO, CLIENT_CAP_COLOR, CLIENT_CAP_STRETCH, CLIENT_CAP_VIDEO, client_crypto_handshake(), client_crypto_init(), close_socket, COLOR_MODE_NONE, connection_endpoint_resolve(), CONNECTION_ENDPOINT_WEBSOCKET, CONNECTION_ERROR_AUTH_FAILED, connection_factory_open(), crypto_client_get_context(), crypto_client_is_ready(), ERROR_CRYPTO_HANDSHAKE, FATAL, GET_OPTION, acip_transport_methods_t::get_socket, connection_endpoint_t::host, connection_endpoint_t::input, INVALID_SOCKET_VALUE, log_debug, log_error, log_info, log_set_terminal_output(), log_warn, MAX_DISPLAY_NAME_LEN, acip_transport::methods, NET_TO_HOST_U16, network_error_string(), platform_get_username(), platform_sleep_us(), connection_endpoint_t::port, connection_endpoint_t::protocol, SAFE_SNPRINTF, SAFE_STRNCPY, server_connection_set_ip(), server_connection_set_port(), should_exit(), socket_configure_buffers(), socket_set_keepalive(), terminal_get_effective_height(), terminal_get_effective_width(), threaded_send_client_join_packet(), and threaded_send_terminal_size_with_auto_detect().

server_connection_get_client_id()

uint32_t server_connection_get_client_id

(

)

#include <server.c>

Get client ID assigned by server.

Returns

Client ID (based on local port) or 0 if not connected

Client ID or 0 if not connected

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

                                           {
  return g_my_client_id;
}

server_connection_get_ip()

const char * server_connection_get_ip

(

)

#include <server.c>

Get resolved server IP address.

Returns the server's IP address that was resolved during connection establishment. Used for known_hosts verification and logging.

Returns

Server IP address string (IPv4 or IPv6), or empty string if not connected

Server IP address string (IPv4 or IPv6)

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

                                       {
  return g_server_ip;
}

Referenced by client_crypto_init().

server_connection_get_port()

int server_connection_get_port

(

void

)

#include <server.c>

Get the server port.

Returns the currently configured server port.

Returns

Server port number (0 if not set)

Server port number

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

                                     {
  return g_server_port;
}

Referenced by client_crypto_init().

server_connection_get_socket()

socket_t server_connection_get_socket

(

)

#include <server.c>

Get current socket file descriptor.

Returns

Socket file descriptor or INVALID_SOCKET_VALUE if disconnected

Socket FD or INVALID_SOCKET_VALUE if disconnected

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

                                        {
  return g_sockfd;
}

server_connection_get_transport()

struct acip_transport * server_connection_get_transport

(

void

)

#include <server.c>

Get ACIP transport instance.

Returns

Transport instance or NULL if not connected

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

                                                        {
  return g_client_transport;
}

Referenced by crypto_client_initiate_rekey(), crypto_client_send_rekey_complete(), crypto_client_send_rekey_response(), protocol_start_connection(), protocol_stop_connection(), threaded_send_image_frame(), and threaded_send_image_frame_h265().

server_connection_init()

int server_connection_init

(

)

#include <server.c>

Initialize the server connection management subsystem.

Initialize server connection management subsystem.

Sets up the send mutex and initializes connection state variables. Must be called once during client startup before any connection attempts.

Returns

0 on success, non-zero on failure

0 on success, negative on error

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

                             {
  // Initialize mutex for thread-safe packet sending
  if (mutex_init(&g_send_mutex, "send") != 0) {
    log_error("Failed to initialize send mutex");
    return -1;
  }
 
  // Register connection atomics for debug sync state monitoring (one-time registration)
  static bool connection_atomics_registered = false;
  if (!connection_atomics_registered) {
    NAMED_REGISTER_ATOMIC(&g_connection_active, "server_connection_active_flag", NULL);
    NAMED_REGISTER_ATOMIC(&g_connection_lost, "server_connection_lost_flag", NULL);
    NAMED_REGISTER_ATOMIC(&g_should_reconnect, "should_attempt_reconnection_flag", NULL);
    connection_atomics_registered = true;
  }
 
  // Initialize connection state
  g_sockfd = INVALID_SOCKET_VALUE;
  g_client_transport = NULL;
  atomic_store_bool(&g_connection_active, false);
  atomic_store_bool(&g_connection_lost, false);
  atomic_store_bool(&g_should_reconnect, false);
  g_my_client_id = 0;
 
  return 0;
}

References atomic_store_bool(), INVALID_SOCKET_VALUE, log_error, mutex_init(), and NAMED_REGISTER_ATOMIC.

server_connection_is_active()

bool server_connection_is_active

(

)

#include <server.c>

Check if server connection is currently active.

Returns

true if connection is active, false otherwise

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

                                   {
  // For TCP: check socket validity
  // For WebRTC: socket is INVALID_SOCKET_VALUE but transport exists
  return atomic_load_bool(&g_connection_active) && (g_sockfd != INVALID_SOCKET_VALUE || g_client_transport != NULL);
}

References atomic_load_bool(), and INVALID_SOCKET_VALUE.

Referenced by protocol_start_connection(), protocol_stop_connection(), threaded_send_image_frame(), and threaded_send_image_frame_h265().

server_connection_is_lost()

bool server_connection_is_lost

(

)

#include <server.c>

Check if connection loss has been detected.

Check if connection loss was detected.

Returns

true if connection loss was flagged, false otherwise

true if connection lost, false otherwise

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

                                 {
  return atomic_load_bool(&g_connection_lost);
}

References atomic_load_bool().

Referenced by protocol_connection_lost().

server_connection_lost()

void server_connection_lost

(

)

#include <server.c>

Signal that connection has been lost.

Called by other modules (typically protocol handlers) when they detect connection failure. Triggers reconnection logic in main loop.

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

                              {
  atomic_store_bool(&g_connection_lost, true);
  atomic_store_bool(&g_connection_active, false);
 
  // Don't re-enable terminal logging here - let the splash screen handle it
  // The reconnection splash will capture and display logs properly
  display_full_reset();
}

References atomic_store_bool(), and display_full_reset().

Referenced by threaded_send_audio_batch_packet(), threaded_send_audio_opus(), threaded_send_audio_opus_batch(), threaded_send_image_frame(), threaded_send_image_frame_h265(), and threaded_send_packet().

server_connection_set_ip()

void server_connection_set_ip

(

const char *

ip

)

#include <server.c>

Set the server IP address.

Updates the global server IP address for the active transport connection.

Parameters

ip	Server IP address string
ip	Server IP address string

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

                                              {
  if (ip) {
    SAFE_STRNCPY(g_server_ip, ip, sizeof(g_server_ip));
    log_debug("Server IP set to: %s", g_server_ip);
  } else {
    g_server_ip[0] = '\0';
    log_debug("Server IP cleared");
  }
}

References log_debug, and SAFE_STRNCPY.

Referenced by client_main(), connection_attempt_tcp(), and server_connection_establish().

server_connection_set_port()

void server_connection_set_port

(

int

port

)

#include <server.c>

Set the server port.

Updates the global server port for the active transport connection.

Parameters

port	Server port number
port	Server port number

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

                                          {
  g_server_port = port;
  log_debug("Server port set to: %d", g_server_port);
}

References log_debug.

Referenced by client_main(), connection_attempt_tcp(), and server_connection_establish().

server_connection_set_transport()

void server_connection_set_transport

(

acip_transport_t *

transport

)

#include <server.c>

Set ACIP transport instance from connection fallback.

Used to integrate the transport from the 3-stage connection fallback orchestrator (TCP → STUN → TURN) into the server connection management layer.

Parameters

transport	Transport instance created by connection_attempt_with_fallback()
transport	Transport instance created by connection_attempt_with_fallback()

Used to integrate the transport from the 3-stage connection fallback orchestrator (TCP → STUN → TURN) into the server connection management layer.

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

                                                                  {
  log_debug("[TRANSPORT_LIFECYCLE] server_connection_set_transport() called with transport=%p", (void *)transport);
 
  // Clean up any existing transport
  if (g_client_transport) {
    log_warn("[TRANSPORT_LIFECYCLE] Replacing existing transport=%p with new transport=%p (potential premature "
             "destruction?)",
             (void *)g_client_transport, (void *)transport);
    log_debug("[TRANSPORT_LIFECYCLE] OLD transport is_connected=%s before destruction",
              acip_transport_is_connected(g_client_transport) ? "true" : "false");
    acip_transport_destroy(g_client_transport);
    log_debug("[TRANSPORT_LIFECYCLE] OLD transport destroyed");
  }
 
  log_debug("[TRANSPORT_LIFECYCLE] Setting g_client_transport to %p", (void *)transport);
  g_client_transport = transport;
 
  // Mark connection as active when transport is set
  if (transport) {
    log_debug("[TRANSPORT_LIFECYCLE] Transport is non-NULL, extracting socket...");
    g_sockfd = acip_transport_get_socket(transport);
    log_debug("[TRANSPORT_LIFECYCLE] Socket extracted: %d from transport=%p", (int)g_sockfd, (void *)transport);
 
    atomic_store_bool(&g_connection_active, true);
    atomic_store_bool(&g_connection_lost, false); // Reset lost flag for new connection
    log_debug("[TRANSPORT_LIFECYCLE] Server connection transport set and marked active (transport=%p, sockfd=%d, "
              "is_connected=%s)",
              (void *)transport, (int)g_sockfd, acip_transport_is_connected(transport) ? "true" : "false");
  } else {
    g_sockfd = INVALID_SOCKET_VALUE;
    atomic_store_bool(&g_connection_active, false);
    log_debug("[TRANSPORT_LIFECYCLE] Server connection transport cleared and marked inactive");
  }
 
  log_debug("[TRANSPORT_LIFECYCLE] server_connection_set_transport() completed");
}

References acip_transport_destroy(), atomic_store_bool(), INVALID_SOCKET_VALUE, log_debug, and log_warn.

server_connection_shutdown()

void server_connection_shutdown

(

)

#include <server.c>

Emergency connection shutdown for signal handlers.

Emergency shutdown for signal handlers.

Performs immediate connection shutdown without waiting for graceful close procedures. Uses socket shutdown to interrupt any blocking recv() operations in other threads.

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

                                  {
  // NOTE: This function may be called from:
  //   - Signal handlers on Unix (async-signal-safe context)
  //   - SetConsoleCtrlHandler callback thread on Windows (separate thread context)
  // Only use atomic operations and simple system calls - NO mutex locks, NO malloc, NO logging.
 
  atomic_store_bool(&g_connection_active, false);
  atomic_store_bool(&g_connection_lost, true);
 
  if (g_sockfd != INVALID_SOCKET_VALUE) {
    // Only shutdown() the socket to interrupt blocking recv()/send() operations.
    // Do NOT close() here - on Windows, closing the socket while another thread
    // is using it is undefined behavior and can cause STATUS_STACK_BUFFER_OVERRUN.
    // The actual socket close happens in server_connection_close() which is called
    // from the main thread after worker threads have been joined.
    socket_shutdown(g_sockfd, SHUT_RDWR);
  }
 
  // For WebSocket transport: interrupt blocking recv() calls
  // The recv() checks is_connected before waiting for data. Setting this to false
  // will cause any blocked recv() to return immediately with CONNECTION_CLOSED.
  // We use a function that's async-signal-safe (no mutexes) to do this.
  server_connection_interrupt_websocket_recv();
 
  // DO NOT call log_set_terminal_output() here - it uses mutex which is NOT async-signal-safe.
  // The normal cleanup path in shutdown_client() will handle logging state.
}

References atomic_store_bool(), INVALID_SOCKET_VALUE, and socket_shutdown().

Referenced by client_main(), and protocol_stop_connection().

server_send_audio()

int server_send_audio	(	const float *	samples,
		int	num_samples
	)

#include <server.h>

Send audio data to server.

Parameters

samples	Audio sample buffer
num_samples	Number of samples

Returns

0 on success, negative on error

server_send_audio_batch()

int server_send_audio_batch	(	const float *	samples,
		int	num_samples,
		int	batch_count
	)

#include <server.h>

Send batched audio data to server.

Parameters

samples	Batched audio samples
num_samples	Total sample count
batch_count	Number of packets in batch

Returns

0 on success, negative on error

server_send_packet()

int server_send_packet	(	packet_type_t	type,
		const void *	data,
		size_t	len
	)

#include <server.h>

Send general packet to server.

Parameters

type	Packet type identifier
data	Packet payload
len	Payload length

Returns

0 on success, negative on error

server_send_ping()

int server_send_ping

(

)

#include <server.h>

Send ping keepalive packet.

Returns

0 on success, negative on error

server_send_pong()

int server_send_pong

(

)

#include <server.h>

Send pong response packet.

Returns

0 on success, negative on error

server_send_stream_start()

int server_send_stream_start

(

uint32_t

stream_type

)

#include <server.h>

Send stream start notification.

Parameters

stream_type

Type of stream (audio/video)

Returns

0 on success, negative on error

server_send_stream_stop()

int server_send_stream_stop

(

uint32_t

stream_type

)

#include <server.h>

Send stream stop notification.

Parameters

stream_type

Type of stream (audio/video)

Returns

0 on success, negative on error

server_send_terminal_capabilities()

int server_send_terminal_capabilities	(	unsigned short	width,
		unsigned short	height
	)

#include <server.h>

Send terminal capabilities to server.

Parameters

width	Terminal width in characters
height	Terminal height in characters

Returns

0 on success, negative on error

threaded_send_audio_batch_packet()

int threaded_send_audio_batch_packet	(	const float *	samples,
		int	num_samples,
		int	batch_count
	)

#include <server.c>

Thread-safe batched audio packet transmission.

Sends a batched audio packet to the server with proper mutex protection and connection state checking. Automatically handles encryption if crypto is ready.

Parameters

samples	Audio sample buffer containing batched samples
num_samples	Total number of samples in the batch
batch_count	Number of audio chunks in this batch

Returns

0 on success, negative on error

Parameters

samples	Audio sample buffer containing batched samples
num_samples	Total number of samples in the batch
batch_count	Number of audio chunks in this batch

Returns

0 on success, negative on error

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

                                                                                             {
  // Lock mutex for entire send operation to prevent concurrent socket writes
  mutex_lock(&g_send_mutex);
 
  // Check connection status and get transport reference
  if (!atomic_load_bool(&g_connection_active) || !g_client_transport) {
    mutex_unlock(&g_send_mutex);
    return -1;
  }
 
  // Get transport reference - transport has its own internal synchronization
  acip_transport_t *transport = g_client_transport;
 
  // Network I/O happens while holding mutex to prevent concurrent socket writes
  asciichat_error_t result = acip_send_audio_batch(transport, samples, (uint32_t)num_samples, (uint32_t)batch_count);
 
  // Unlock after send completes
  mutex_unlock(&g_send_mutex);
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    server_connection_lost();
    return -1;
  }
 
  return 0;
}

References acip_send_audio_batch(), ASCIICHAT_OK, atomic_load_bool(), mutex_lock, mutex_unlock, and server_connection_lost().

threaded_send_audio_opus()

asciichat_error_t threaded_send_audio_opus	(	const uint8_t *	opus_data,
		size_t	opus_size,
		int	sample_rate,
		int	frame_duration
	)

#include <server.c>

Thread-safe Opus audio frame transmission.

Sends a single Opus-encoded audio frame to the server with proper synchronization and encryption support.

Parameters

opus_data	Opus-encoded audio data
opus_size	Size of encoded frame
sample_rate	Sample rate in Hz
frame_duration	Frame duration in milliseconds

Returns

0 on success, negative on error

Sends a single Opus-encoded audio frame to the server with proper synchronization and encryption support.

Parameters

opus_data	Opus-encoded audio data
opus_size	Size of encoded frame
sample_rate	Sample rate in Hz
frame_duration	Frame duration in milliseconds

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                               {
  // Get transport reference while holding mutex (brief lock)
  mutex_lock(&g_send_mutex);
 
  // Check connection status and get transport reference
  if (!atomic_load_bool(&g_connection_active) || !g_client_transport) {
    mutex_unlock(&g_send_mutex);
    return SET_ERRNO(ERROR_NETWORK, "Connection not active or transport unavailable");
  }
 
  // Get transport reference - transport has its own internal synchronization
  acip_transport_t *transport = g_client_transport;
  mutex_unlock(&g_send_mutex);
 
  // Build Opus packet with header (outside mutex - no blocking I/O yet)
  size_t header_size = 16; // sample_rate (4), frame_duration (4), reserved (8)
  size_t total_size = header_size + opus_size;
  void *packet_data = buffer_pool_alloc(NULL, total_size);
  if (!packet_data) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate buffer for Opus packet: %zu bytes", total_size);
  }
 
  // Write header in network byte order
  uint8_t *buf = (uint8_t *)packet_data;
  uint32_t sr = HOST_TO_NET_U32((uint32_t)sample_rate);
  uint32_t fd = HOST_TO_NET_U32((uint32_t)frame_duration);
  memcpy(buf, &sr, 4);
  memcpy(buf + 4, &fd, 4);
  memset(buf + 8, 0, 8); // Reserved
 
  // Copy Opus data
  memcpy(buf + header_size, opus_data, opus_size);
 
  // Network I/O happens OUTSIDE the mutex to prevent deadlock on TCP buffer full
  asciichat_error_t result =
      packet_send_via_transport(transport, PACKET_TYPE_AUDIO_OPUS_BATCH, packet_data, total_size, 0);
 
  // Clean up
  buffer_pool_free(NULL, packet_data, total_size);
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    server_connection_lost();
    return result;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_load_bool(), buffer_pool_alloc(), buffer_pool_free(), ERROR_MEMORY, ERROR_NETWORK, HOST_TO_NET_U32, mutex_lock, mutex_unlock, packet_send_via_transport(), PACKET_TYPE_AUDIO_OPUS_BATCH, server_connection_lost(), and SET_ERRNO.

threaded_send_audio_opus_batch()

asciichat_error_t threaded_send_audio_opus_batch	(	const uint8_t *	opus_data,
		size_t	opus_size,
		const uint16_t *	frame_sizes,
		int	frame_count
	)

#include <server.c>

Thread-safe Opus audio batch packet transmission.

Sends a batch of Opus-encoded audio frames to the server with proper synchronization and encryption support.

Parameters

opus_data	Opus-encoded audio data (multiple frames concatenated)
opus_size	Total size of Opus data in bytes
frame_sizes	Array of individual frame sizes (variable-length frames)
frame_count	Number of Opus frames in the batch

Returns

0 on success, negative on error

Sends a batch of Opus-encoded audio frames to the server with proper synchronization and encryption support.

Parameters

opus_data	Opus-encoded audio data (multiple frames concatenated)
opus_size	Total size of Opus data in bytes
frame_sizes	Array of individual frame sizes (variable-length frames)
frame_count	Number of Opus frames in the batch

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                                               {
  // Lock mutex for entire send operation to prevent concurrent socket writes
  mutex_lock(&g_send_mutex);
 
  // Check connection status and get transport reference
  if (!atomic_load_bool(&g_connection_active) || !g_client_transport) {
    mutex_unlock(&g_send_mutex);
    return SET_ERRNO(ERROR_NETWORK, "Connection not active or transport unavailable");
  }
 
  // Get transport reference - transport has its own internal synchronization
  acip_transport_t *transport = g_client_transport;
 
  // Network I/O happens while holding mutex to prevent concurrent socket writes
  // Opus uses 20ms frames at 48kHz (960 samples = 20ms)
  asciichat_error_t result =
      acip_send_audio_opus_batch(transport, opus_data, opus_size, frame_sizes, frame_count, 48000, 20);
 
  // Unlock after send completes
  mutex_unlock(&g_send_mutex);
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    server_connection_lost();
    return result;
  }
 
  return ASCIICHAT_OK;
}

References acip_send_audio_opus_batch(), ASCIICHAT_OK, atomic_load_bool(), ERROR_NETWORK, mutex_lock, mutex_unlock, server_connection_lost(), and SET_ERRNO.

threaded_send_client_join_packet()

int threaded_send_client_join_packet	(	const char *	display_name,
		uint32_t	capabilities
	)

#include <server.c>

Thread-safe client join packet transmission.

Sends client join packet with display name and capabilities to the server.

Parameters

display_name	Client display name
capabilities	Client capability flags

Returns

0 on success, negative on error

Parameters

display_name	Client display name
capabilities	Client capability flags

Returns

0 on success, negative on error

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

                                                                                      {
  // Connection and transport availability is checked by threaded_send_packet()
 
  // Build CLIENT_JOIN packet locally
  client_info_packet_t join_packet;
  SAFE_MEMSET(&join_packet, sizeof(join_packet), 0, sizeof(join_packet));
  join_packet.client_id = HOST_TO_NET_U32(0); // Will be assigned by server
  SAFE_SNPRINTF(join_packet.display_name, MAX_DISPLAY_NAME_LEN, "%s", display_name ? display_name : "Unknown");
  join_packet.capabilities = HOST_TO_NET_U32(capabilities);
 
  // Use threaded_send_packet() which handles encryption
  int send_result = threaded_send_packet(PACKET_TYPE_CLIENT_JOIN, &join_packet, sizeof(join_packet));
  if (send_result == 0) {
    mutex_lock(&g_send_mutex);
    bool active = atomic_load_u64(&g_connection_active);
    socket_t socket_snapshot = g_sockfd;
    const crypto_context_t *crypto_ctx = crypto_client_is_ready() ? crypto_client_get_context() : NULL;
    if (active && socket_snapshot != INVALID_SOCKET_VALUE) {
      (void)log_network_message(
          socket_snapshot, (const struct crypto_context_t *)crypto_ctx, LOG_INFO, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER,
          "CLIENT_JOIN sent (display=\"%s\", capabilities=0x%x)", join_packet.display_name, capabilities);
    }
    mutex_unlock(&g_send_mutex);
  }
  return send_result;
}

References atomic_load_u64(), client_info_packet_t::capabilities, client_info_packet_t::client_id, crypto_client_get_context(), crypto_client_is_ready(), client_info_packet_t::display_name, HOST_TO_NET_U32, INVALID_SOCKET_VALUE, LOG_INFO, log_network_message(), MAX_DISPLAY_NAME_LEN, mutex_lock, mutex_unlock, PACKET_TYPE_CLIENT_JOIN, REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER, SAFE_MEMSET, SAFE_SNPRINTF, and threaded_send_packet().

Referenced by server_connection_establish().

threaded_send_image_frame()

asciichat_error_t threaded_send_image_frame	(	const void *	pixel_data,
		uint32_t	width,
		uint32_t	height,
		uint32_t	pixel_format
	)

#include <server.c>

Thread-safe image frame transmission.

Sends image frames with serialization via g_send_mutex to prevent race conditions when multiple threads write to the same TCP socket.

Parameters

pixel_data	Pixel data buffer
width	Frame width in pixels
height	Frame height in pixels
pixel_format	Pixel format (1=RGB24)

Returns

ASCIICHAT_OK on success, error code on failure

Sends image frames with serialization via mutex to prevent race conditions when multiple threads write to the same TCP socket.

Parameters

pixel_data	Pixel data buffer (RGB24 format)
width	Frame width in pixels
height	Frame height in pixels
pixel_format	Pixel format (1=RGB24)

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                   {
  if (!pixel_data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Pixel data is NULL");
  }
 
  mutex_lock(&g_send_mutex);
 
  // Get transport reference - may be NULL if connection was lost
  acip_transport_t *transport = server_connection_get_transport();
  if (!transport || !server_connection_is_active()) {
    mutex_unlock(&g_send_mutex);
    return SET_ERRNO(ERROR_NETWORK, "Transport unavailable");
  }
 
  // Send image frame with socket lock held
  asciichat_error_t result = acip_send_image_frame(transport, pixel_data, width, height, pixel_format);
 
  // Unlock after send completes
  mutex_unlock(&g_send_mutex);
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    server_connection_lost();
    return result;
  }
 
  return ASCIICHAT_OK;
}

References acip_send_image_frame(), ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, mutex_lock, mutex_unlock, server_connection_get_transport(), server_connection_is_active(), server_connection_lost(), and SET_ERRNO.

threaded_send_image_frame_h265()

asciichat_error_t threaded_send_image_frame_h265	(	const void *	pixel_data,
		uint32_t	width,
		uint32_t	height
	)

#include <server.c>

Send H.265-encoded video frame to server (thread-safe)

Encodes RGB frame using H.265 codec before transmission. Much more bandwidth-efficient than raw pixel transmission. Uses mutex to prevent interleaving with other packet sends.

Parameters

pixel_data	RGB pixel data from camera
width	Frame width in pixels
height	Frame height in pixels

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                                                          {
  if (!pixel_data) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Pixel data is NULL");
  }
 
  // Get encoder - may be NULL if not initialized
  h265_encoder_t *encoder = g_h265_encoder;
  if (!encoder) {
    return SET_ERRNO(ERROR_INVALID_STATE, "H.265 encoder not initialized");
  }
 
  // Allocate buffer and encode frame WITHOUT holding the send mutex.
  // This avoids long critical section that can cause deadlocks with named registry operations.
  log_info("[H265_SEND_FRAME_1] Allocating buffer and encoding frame (no mutex held)");
  size_t output_buffer_size = 5 + (width * height * 2);
  uint8_t *output_buffer = buffer_pool_alloc(NULL, output_buffer_size);
  if (!output_buffer) {
    log_error("Failed to allocate output buffer for frame");
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate H.265 output buffer: %zu bytes", output_buffer_size);
  }
 
  // Encode frame
  size_t encoded_size = output_buffer_size - 5;
  asciichat_error_t encode_result = h265_encode(encoder, (uint16_t)width, (uint16_t)height, (const uint8_t *)pixel_data,
                                                output_buffer + 5, &encoded_size);
  log_info("[H265_SEND_FRAME_2] ✅ Frame encoded, encoded_size=%zu, result=%d", encoded_size, encode_result);
 
  if (encode_result != ASCIICHAT_OK) {
    log_error("H.265 encoding failed: %s", asciichat_error_string(encode_result));
    buffer_pool_free(NULL, output_buffer, output_buffer_size);
    return encode_result;
  }
 
  // Prepare packet header: [flags:u8][width:u16][height:u16][h265_data...]
  output_buffer[0] = 0; // flags: no flags set by default
  output_buffer[1] = (width >> 8) & 0xFF;
  output_buffer[2] = width & 0xFF;
  output_buffer[3] = (height >> 8) & 0xFF;
  output_buffer[4] = height & 0xFF;
 
  size_t total_size = 5 + encoded_size;
 
  // NOW acquire the send mutex just for the actual network transmission
  log_info("[H265_SEND_FRAME_3] About to acquire g_send_mutex for network send");
  mutex_lock(&g_send_mutex);
  log_info("[H265_SEND_FRAME_4] ✅ Acquired g_send_mutex, checking transport");
 
  // Get transport reference - may be NULL if connection was lost
  acip_transport_t *transport = server_connection_get_transport();
  if (!transport || !server_connection_is_active()) {
    mutex_unlock(&g_send_mutex);
    log_info("[H265_SEND_FRAME_5] Transport unavailable, releasing mutex");
    buffer_pool_free(NULL, output_buffer, output_buffer_size);
    return SET_ERRNO(ERROR_NETWORK, "Transport unavailable");
  }
 
  // Send H.265 frame with socket lock held (short critical section)
  log_info("[H265_SEND_FRAME_6] Sending packet via transport (%zu bytes)", total_size);
  asciichat_error_t result =
      packet_send_via_transport(transport, PACKET_TYPE_IMAGE_FRAME_H265, output_buffer, total_size, 0);
  log_info("[H265_SEND_FRAME_7] packet_send_via_transport returned: %d", result);
 
  // Unlock after send completes
  mutex_unlock(&g_send_mutex);
  log_info("[H265_SEND_FRAME_8] ✅ Released g_send_mutex");
 
  buffer_pool_free(NULL, output_buffer, output_buffer_size);
  log_info("[H265_SEND_FRAME_9] ✅ Freed output buffer");
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    server_connection_lost();
    return result;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, buffer_pool_alloc(), buffer_pool_free(), ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_MEMORY, ERROR_NETWORK, g_h265_encoder, h265_encode(), log_error, log_info, mutex_lock, mutex_unlock, packet_send_via_transport(), PACKET_TYPE_IMAGE_FRAME_H265, server_connection_get_transport(), server_connection_is_active(), server_connection_lost(), and SET_ERRNO.

threaded_send_packet()

asciichat_error_t threaded_send_packet	(	packet_type_t	type,
		const void *	data,
		size_t	len
	)

#include <server.c>

Thread-safe packet transmission.

Sends a packet to the server with proper mutex protection and connection state checking. Automatically handles encryption if crypto is ready.

Parameters

type	Packet type identifier
data	Packet payload
len	Payload length

Returns

0 on success, negative on error

Sends a packet to the server with proper mutex protection and connection state checking. Automatically handles encryption if crypto is ready.

Parameters

type	Packet type identifier
data	Packet payload
len	Payload length

Returns

ASCIICHAT_OK on success, error code on failure

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

                                                                                         {
  // Lock mutex for entire send operation to prevent concurrent socket writes
  mutex_lock(&g_send_mutex);
 
  // Check connection status and get transport reference
  if (!atomic_load_bool(&g_connection_active) || !g_client_transport) {
    log_debug("[TRANSPORT_LIFECYCLE] threaded_send_packet() check failed: active=%s, transport=%p",
              atomic_load_bool(&g_connection_active) ? "true" : "false", (void *)g_client_transport);
    mutex_unlock(&g_send_mutex);
    return SET_ERRNO(ERROR_NETWORK, "Connection not active or transport unavailable");
  }
 
  // Get transport reference - transport has its own internal synchronization
  acip_transport_t *transport = g_client_transport;
  log_debug_every(LOG_RATE_SLOW, "[TRANSPORT_LIFECYCLE] threaded_send_packet() using transport=%p, is_connected=%s",
                  (void *)transport, acip_transport_is_connected(transport) ? "true" : "false");
 
  // Network I/O happens while holding mutex to prevent concurrent socket writes
  asciichat_error_t result = packet_send_via_transport(transport, type, data, len, 0);
 
  // Unlock after send completes
  mutex_unlock(&g_send_mutex);
 
  // If send failed due to network error, signal connection loss
  if (result != ASCIICHAT_OK) {
    log_debug("[TRANSPORT_LIFECYCLE] threaded_send_packet() send failed, calling server_connection_lost()");
    server_connection_lost();
    return result;
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, atomic_load_bool(), ERROR_NETWORK, log_debug, log_debug_every, LOG_RATE_SLOW, mutex_lock, mutex_unlock, packet_send_via_transport(), server_connection_lost(), and SET_ERRNO.

Referenced by threaded_send_client_join_packet(), threaded_send_ping_packet(), threaded_send_pong_packet(), threaded_send_stream_start_packet(), and threaded_send_terminal_size_with_auto_detect().

threaded_send_ping_packet()

int threaded_send_ping_packet

(

void

)

#include <server.c>

Thread-safe ping packet transmission.

Returns

0 on success, negative on error

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

                                    {
  // Use threaded_send_packet which handles encryption, mutex locking, and connection state
  return threaded_send_packet(PACKET_TYPE_PING, NULL, 0);
}

References PACKET_TYPE_PING, and threaded_send_packet().

threaded_send_pong_packet()

int threaded_send_pong_packet

(

void

)

#include <server.c>

Thread-safe pong packet transmission.

Returns

0 on success, negative on error

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

                                    {
  // Use threaded_send_packet which handles encryption, mutex locking, and connection state
  return threaded_send_packet(PACKET_TYPE_PONG, NULL, 0);
}

References PACKET_TYPE_PONG, and threaded_send_packet().

threaded_send_stream_start_packet()

asciichat_error_t threaded_send_stream_start_packet

(

uint32_t

stream_type

)

#include <server.c>

Thread-safe stream start packet transmission.

Parameters

stream_type

Type of stream (audio/video)

Returns

0 on success, negative on error

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

                                                                          {
  // Connection and transport availability is checked by threaded_send_packet()
 
  // Build STREAM_START packet locally
  uint32_t type_data = HOST_TO_NET_U32(stream_type);
 
  // Use threaded_send_packet() which handles encryption
  return threaded_send_packet(PACKET_TYPE_STREAM_START, &type_data, sizeof(type_data));
}

References HOST_TO_NET_U32, PACKET_TYPE_STREAM_START, and threaded_send_packet().

Referenced by protocol_start_connection().

threaded_send_terminal_size_with_auto_detect()

asciichat_error_t threaded_send_terminal_size_with_auto_detect	(	unsigned short	width,
		unsigned short	height
	)

#include <server.c>

Thread-safe terminal size packet transmission with auto-detection.

Sends terminal capabilities packet to the server including terminal size, color capabilities, and rendering preferences. Auto-detects terminal capabilities if not explicitly specified.

Parameters

width	Terminal width in characters
height	Terminal height in characters

Returns

0 on success, negative on error

Parameters

width	Terminal width in characters
height	Terminal height in characters

Returns

0 on success, negative on error

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

                                                                                                            {
  // Log the dimensions being sent to server (helps debug dimension mismatch issues)
  log_debug("Sending terminal size to server: %ux%u (auto_width=%d, auto_height=%d)", width, height,
            GET_OPTION(auto_width), GET_OPTION(auto_height));
 
  // Connection and transport availability is checked by threaded_send_packet()
 
  // Build terminal capabilities packet locally
  // Detect terminal capabilities automatically
  terminal_capabilities_t caps = detect_terminal_capabilities();
 
  // Set wants_padding based on snapshot mode and TTY status
  // Disable padding when:
  // - In snapshot mode (one frame and exit)
  // - When stdout is not a TTY (piped/redirected output)
  // Enable padding for interactive terminal sessions
  bool is_snapshot_mode = GET_OPTION(snapshot_mode);
  bool is_interactive = terminal_is_interactive();
  caps.wants_padding = is_interactive && !is_snapshot_mode;
 
  log_debug("Client capabilities: wants_padding=%d (snapshot=%d, interactive=%d, stdin_tty=%d, stdout_tty=%d)",
            caps.wants_padding, is_snapshot_mode, is_interactive, terminal_is_stdin_tty(), terminal_is_stdout_tty());
 
  // Apply user's color mode override
  caps = apply_color_mode_override(caps);
 
  // Check if detection was reliable, use fallback only for auto-detection
  if (!caps.detection_reliable && GET_OPTION(color_mode) == COLOR_MODE_AUTO) {
    log_warn("Terminal capability detection not reliable, using fallback");
    SAFE_MEMSET(&caps, sizeof(caps), 0, sizeof(caps));
    caps.color_level = TERM_COLOR_NONE;
    caps.color_count = 2;
    caps.capabilities = 0;
    SAFE_STRNCPY(caps.term_type, "unknown", sizeof(caps.term_type));
    SAFE_STRNCPY(caps.colorterm, "", sizeof(caps.colorterm));
    caps.detection_reliable = 0;
    // Preserve wants_padding even in fallback mode
    caps.wants_padding = is_interactive && !is_snapshot_mode;
  }
 
  // Convert to network packet format with proper byte order
  terminal_capabilities_packet_t net_packet;
  net_packet.capabilities = HOST_TO_NET_U32(caps.capabilities);
  net_packet.color_level = HOST_TO_NET_U32(caps.color_level);
  net_packet.color_count = HOST_TO_NET_U32(caps.color_count);
  net_packet.render_mode = HOST_TO_NET_U32(caps.render_mode);
  net_packet.width = HOST_TO_NET_U16(width);
  net_packet.height = HOST_TO_NET_U16(height);
  net_packet.palette_type = HOST_TO_NET_U32(GET_OPTION(palette_type));
  net_packet.utf8_support = HOST_TO_NET_U32(caps.utf8_support ? 1 : 0);
 
  const options_t *opts = options_get();
  if (GET_OPTION(palette_type) == PALETTE_CUSTOM && GET_OPTION(palette_custom_set)) {
    const char *palette_custom = opts && opts->palette_custom_set ? opts->palette_custom : "";
    SAFE_STRNCPY(net_packet.palette_custom, palette_custom, sizeof(net_packet.palette_custom));
    net_packet.palette_custom[sizeof(net_packet.palette_custom) - 1] = '\0';
  } else {
    SAFE_MEMSET(net_packet.palette_custom, sizeof(net_packet.palette_custom), 0, sizeof(net_packet.palette_custom));
  }
 
  // Set desired FPS
  int fps = GET_OPTION(fps);
  if (fps > 0) {
    net_packet.desired_fps = (uint8_t)(fps > 144 ? 144 : fps);
  } else {
    net_packet.desired_fps = caps.desired_fps;
  }
 
  if (net_packet.desired_fps == 0) {
    net_packet.desired_fps = DEFAULT_MAX_FPS;
  }
 
  SAFE_STRNCPY(net_packet.term_type, caps.term_type, sizeof(net_packet.term_type));
  net_packet.term_type[sizeof(net_packet.term_type) - 1] = '\0';
 
  SAFE_STRNCPY(net_packet.colorterm, caps.colorterm, sizeof(net_packet.colorterm));
  net_packet.colorterm[sizeof(net_packet.colorterm) - 1] = '\0';
 
  net_packet.detection_reliable = caps.detection_reliable;
  // Send UTF-8 support flag: true for AUTO (default) and TRUE settings, false for FALSE setting
  net_packet.utf8_support = (GET_OPTION(force_utf8) != UTF8_SETTING_FALSE) ? 1 : 0;
 
  // Set wants_padding flag (1=padding enabled, 0=no padding for snapshot/piped modes)
  net_packet.wants_padding = caps.wants_padding ? 1 : 0;
 
  // Set codec capabilities (client supports all codecs by default)
  net_packet.codec_capabilities_video = HOST_TO_NET_U32(VIDEO_CODEC_CAP_ALL);
  net_packet.codec_capabilities_audio = HOST_TO_NET_U32(AUDIO_CODEC_CAP_ALL);
 
  // Use threaded_send_packet() which handles encryption
  return threaded_send_packet(PACKET_TYPE_CLIENT_CAPABILITIES, &net_packet, sizeof(net_packet));
}

References apply_color_mode_override(), AUDIO_CODEC_CAP_ALL, auto_height, auto_width, terminal_capabilities_packet_t::capabilities, terminal_capabilities_t::capabilities, terminal_capabilities_packet_t::codec_capabilities_audio, terminal_capabilities_packet_t::codec_capabilities_video, terminal_capabilities_packet_t::color_count, terminal_capabilities_t::color_count, terminal_capabilities_packet_t::color_level, terminal_capabilities_t::color_level, COLOR_MODE_AUTO, terminal_capabilities_packet_t::colorterm, terminal_capabilities_t::colorterm, DEFAULT_MAX_FPS, terminal_capabilities_packet_t::desired_fps, terminal_capabilities_t::desired_fps, detect_terminal_capabilities(), terminal_capabilities_packet_t::detection_reliable, terminal_capabilities_t::detection_reliable, GET_OPTION, terminal_capabilities_packet_t::height, HOST_TO_NET_U16, HOST_TO_NET_U32, log_debug, log_warn, options_get(), PACKET_TYPE_CLIENT_CAPABILITIES, terminal_capabilities_packet_t::palette_custom, PALETTE_CUSTOM, terminal_capabilities_packet_t::palette_type, terminal_capabilities_packet_t::render_mode, terminal_capabilities_t::render_mode, SAFE_MEMSET, SAFE_STRNCPY, TERM_COLOR_NONE, terminal_capabilities_packet_t::term_type, terminal_capabilities_t::term_type, terminal_is_interactive(), terminal_is_stdin_tty(), terminal_is_stdout_tty(), threaded_send_packet(), UTF8_SETTING_FALSE, terminal_capabilities_packet_t::utf8_support, terminal_capabilities_t::utf8_support, VIDEO_CODEC_CAP_ALL, terminal_capabilities_packet_t::wants_padding, terminal_capabilities_t::wants_padding, and terminal_capabilities_packet_t::width.

Referenced by protocol_start_connection(), and server_connection_establish().

Variable Documentation

g_crypto_ctx

crypto_handshake_context_t g_crypto_ctx = {0}

#include <server.c>

Per-connection crypto handshake context.

Global crypto handshake context for this client connection.

Maintains the cryptographic state for the current connection, including key exchange state, encryption keys, and handshake progress.

Note

This is not static because it may be accessed from crypto.c

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

{0};

Referenced by client_crypto_handshake(), client_crypto_init(), crypto_client_cleanup(), crypto_client_decrypt_packet(), crypto_client_encrypt_packet(), crypto_client_get_context(), crypto_client_initiate_rekey(), crypto_client_is_ready(), crypto_client_process_rekey_request(), crypto_client_process_rekey_response(), crypto_client_send_rekey_complete(), crypto_client_send_rekey_response(), crypto_client_should_rekey(), and server_connection_close().