connection_attempt.h File Reference

Connection state machine and attempt logic for TCP/WebSocket clients. More...

Go to the source code of this file.

Data Structures
struct	connection_attempt_context_t
	Context for connection attempts (TCP or WebSocket) More...

Macros
#define	CONN_TIMEOUT_TCP   (3LL * NS_PER_SEC_INT)
	TCP/WebSocket timeout (3s)

Enumerations
enum	connection_state_t {   CONN_STATE_IDLE = 0 , CONN_STATE_ATTEMPTING = 1 , CONN_STATE_CONNECTED = 2 , CONN_STATE_DISCONNECTED = 3 ,   CONN_STATE_FAILED = 4 }
	Simple TCP connection state machine. More...

Functions
asciichat_error_t	connection_context_init (connection_attempt_context_t *ctx)
	Initialize connection attempt context.
asciichat_error_t	connection_state_transition (connection_attempt_context_t *ctx, connection_state_t new_state)
	Transition to next connection state.
bool	connection_check_timeout (const connection_attempt_context_t *ctx)
	Check if connection attempt has exceeded timeout.
const char *	connection_state_name (connection_state_t state)
	Get human-readable state name for logging.
void	connection_context_cleanup (connection_attempt_context_t *ctx)
	Cleanup connection attempt context.
asciichat_error_t	connection_attempt_tcp (connection_attempt_context_t *ctx, const char *server_address, uint16_t server_port)
	Attempt TCP connection.
asciichat_error_t	connection_attempt_websocket (connection_attempt_context_t *ctx, const char *ws_url)
	Attempt WebSocket connection.

Detailed Description

Connection state machine and attempt logic for TCP/WebSocket clients.

Implements direct TCP and WebSocket connections for client mode. Manages connection state transitions, timeouts, and transport lifecycle.

Features:

• Direct TCP connection to server
• WebSocket connection support (ws:// and wss://)
• Timeout management
• Crypto handshake integration (when encryption enabled)
• ACIP transport creation
• Proper resource cleanup

Integration Points:

• Called from src/client/main.c connection loop
• Returns active transport when connection succeeds
• Uses crypto subsystem for optional encryption/authentication

Date

January 2026

Version

2.0

Definition in file connection_attempt.h.

Macro Definition Documentation

CONN_TIMEOUT_TCP

#define CONN_TIMEOUT_TCP   (3LL * NS_PER_SEC_INT)

TCP/WebSocket timeout (3s)

Definition at line 65 of file connection_attempt.h.

Enumeration Type Documentation

connection_state_t

enum connection_state_t

Simple TCP connection state machine.

States:

• IDLE: Not connected, no attempt in progress
• ATTEMPTING: TCP/WebSocket connection in progress
• CONNECTED: Successfully connected
• DISCONNECTED: Clean disconnect (user initiated)
• FAILED: Connection attempt failed

Enumerator
CONN_STATE_IDLE	Not connected, no attempt in progress.
CONN_STATE_ATTEMPTING	Attempting connection.
CONN_STATE_CONNECTED	Successfully connected.
CONN_STATE_DISCONNECTED	Clean disconnect (user initiated)
CONN_STATE_FAILED	Connection attempt failed.

Definition at line 53 of file connection_attempt.h.

             {
  CONN_STATE_IDLE = 0,         
  CONN_STATE_ATTEMPTING = 1,   
  CONN_STATE_CONNECTED = 2,    
  CONN_STATE_DISCONNECTED = 3, 
  CONN_STATE_FAILED = 4,       
} connection_state_t;

Function Documentation

connection_attempt_tcp()

asciichat_error_t connection_attempt_tcp	(	connection_attempt_context_t *	ctx,
		const char *	server_address,
		uint16_t	server_port
	)

Attempt TCP connection.

Attempts a direct TCP connection to the specified server. On success, sets the transport in the context handle.

Handles:

• WebSocket URL detection (ws:// or wss://)
• TCP connection and handshake
• Crypto initialization and handshake (when encryption enabled)
• ACIP transport creation

Parameters

ctx	Connection context (initialized via connection_context_init)
server_address	Server hostname, IP address, or WebSocket URL
server_port	Server port number (ignored if server_address is WebSocket URL)

Returns

ASCIICHAT_OK on successful connection

ERROR_* code on failure

Note

ctx.connection.transport will be set to the transport on success

ctx.current_state will be set to CONN_STATE_CONNECTED on success

Attempt TCP connection.

Connects to server via TCP, performs crypto handshake if enabled, and creates ACIP transport for protocol communication.

Definition at line 168 of file connection_attempt.c.

                                                               {
  log_info("=== connection_attempt_tcp CALLED: address='%s', port=%u ===", server_address, server_port);
 
  if (!ctx || !server_address) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // Check if shutdown was requested before attempting connection (via callback if available)
  if (APP_CALLBACK_BOOL(should_exit)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection attempt aborted due to shutdown request");
  }
 
  // Normalize the endpoint once so TCP and WebSocket paths use the same rules.
  connection_endpoint_t endpoint = {0};
  asciichat_error_t endpoint_result = connection_endpoint_resolve(server_address, server_port, &endpoint);
  if (endpoint_result != ASCIICHAT_OK) {
    return endpoint_result;
  }
 
  log_debug("connection_attempt_tcp: server_address='%s', normalized=%s host=%s port=%u", server_address,
            connection_endpoint_protocol_name(endpoint.protocol), endpoint.host, endpoint.port);
 
  if (endpoint.protocol == CONNECTION_ENDPOINT_WEBSOCKET) {
    // WebSocket connection path
    const char *ws_url = endpoint.input;
 
    // Set server IP/port for crypto handshake known_hosts verification
    APP_CALLBACK_VOID_STR(server_connection_set_ip, endpoint.host);
    APP_CALLBACK_VOID_INT(server_connection_set_port, endpoint.port);
    log_debug("Set server IP=%s, port=%u for WebSocket crypto handshake", endpoint.host, endpoint.port);
 
    log_info("Attempting WebSocket connection to %s", ws_url);
 
    // Transition to attempting state
    asciichat_error_t result = connection_state_transition(ctx, CONN_STATE_ATTEMPTING);
    if (result != ASCIICHAT_OK) {
      return result;
    }
 
    // Set timeout for this attempt
    ctx->attempt_start_time_ns = time_get_realtime_ns();
    ctx->timeout_ns = CONN_TIMEOUT_TCP; // Use same timeout as TCP
 
    // Compute crypto mode from CLI options
    // Determine if client has authentication material (keys or password)
    bool has_auth_material =
        (GET_OPTION(encrypt_key)[0] != '\0' || GET_OPTION(num_identity_keys) > 0 || GET_OPTION(password)[0] != '\0');
    bool no_encrypt = GET_OPTION(no_encrypt);
    bool no_auth = GET_OPTION(no_auth);
 
    uint8_t crypto_mode;
    if (!no_encrypt && !no_auth && !has_auth_material)
      crypto_mode = ACIP_CRYPTO_ENCRYPT; // default: encrypt only
    else if (!no_encrypt && !no_auth && has_auth_material)
      crypto_mode = ACIP_CRYPTO_FULL; // full: encrypt + auth
    else if (no_encrypt && !no_auth && has_auth_material)
      crypto_mode = ACIP_CRYPTO_AUTH; // auth-only mode
    else
      crypto_mode = ACIP_CRYPTO_NONE; // no crypto
 
    log_debug("WebSocket crypto mode computed: 0x%02x (encrypt=%d, auth=%d)", crypto_mode,
              ACIP_CRYPTO_HAS_ENCRYPT(crypto_mode), ACIP_CRYPTO_HAS_AUTH(crypto_mode));
 
    // Set crypto mode before initialization via callback
    // NOTE: Always initialize crypto context, even in NONE mode!
    // The server always sends KEY_EXCHANGE_INIT packets, and the context
    // must be initialized to handle them (even if in disabled/none mode).
    const crypto_context_t *crypto_ctx = NULL;
 
    log_debug("Initializing crypto context for WebSocket with mode 0x%02x...", crypto_mode);
 
    APP_CALLBACK_VOID_UINT8(client_crypto_set_mode, crypto_mode);
 
    if (APP_CALLBACK_INT(client_crypto_init) != 0) {
      log_error("Failed to initialize crypto context");
      return SET_ERRNO(ERROR_CRYPTO, "Crypto initialization failed");
    }
    log_debug("Crypto context initialized successfully");
 
    // Get crypto context if ready
    if (APP_CALLBACK_BOOL(crypto_client_is_ready)) {
      crypto_ctx = APP_CALLBACK_PTR(crypto_client_get_context);
    }
 
    // Create WebSocket client instance
    websocket_client_t *ws_client = websocket_client_create("discovery_connection");
    if (!ws_client) {
      log_error("Failed to create WebSocket client");
      connection_state_transition(ctx, CONN_STATE_FAILED);
      return SET_ERRNO(ERROR_NETWORK, "WebSocket client creation failed");
    }
 
    // Connect via WebSocket
    acip_transport_t *transport = websocket_client_connect(ws_client, ws_url, (crypto_context_t *)crypto_ctx);
    if (!transport) {
      log_error("Failed to create WebSocket ACIP transport");
      websocket_client_destroy(&ws_client);
      connection_state_transition(ctx, CONN_STATE_FAILED);
      return SET_ERRNO(ERROR_NETWORK, "WebSocket connection failed");
    }
 
    // CRITICAL: Wait for the WebSocket handshake to actually complete
    // The transport is created but the TLS/crypto handshake happens in the service thread
    log_info("WebSocket transport created, waiting for TLS handshake completion...");
    const int MAX_HANDSHAKE_WAIT_ITERATIONS = 300; // 300 * 50ms = 15 seconds
    int handshake_wait_count = 0;
    while (!acip_transport_is_connected(transport) && handshake_wait_count < MAX_HANDSHAKE_WAIT_ITERATIONS) {
      platform_sleep_us(50000); // Sleep 50ms between checks
      handshake_wait_count++;
      if (handshake_wait_count % 20 == 0) {
        log_info("WebSocket handshake waiting... (%d seconds elapsed)", handshake_wait_count / 20);
      }
    }
 
    if (!acip_transport_is_connected(transport)) {
      log_error("WebSocket TLS handshake failed or timed out after 15 seconds");
      websocket_client_destroy(&ws_client);
      connection_state_transition(ctx, CONN_STATE_FAILED);
      return SET_ERRNO(ERROR_NETWORK, "WebSocket handshake timeout");
    }
 
    log_info("WebSocket connection established to %s", ws_url);
    connection_state_transition(ctx, CONN_STATE_CONNECTED);
    ctx->connection.transport = transport;
    ctx->connection.transport_type = ACIP_TRANSPORT_WEBSOCKET;
    ctx->connection.owner = ws_client;
    ctx->connection.owner_destroy = destroy_websocket_client_owner;
 
    return ASCIICHAT_OK;
  }
 
  // TCP connection path (original logic)
  log_info("Attempting TCP connection to %s:%u (3s timeout)", endpoint.host, endpoint.port);
 
  // Transition to attempting state
  asciichat_error_t result = connection_state_transition(ctx, CONN_STATE_ATTEMPTING);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Create TCP client internally so connection ownership stays in this layer.
  tcp_client_t *tcp_client = tcp_client_create();
  if (!tcp_client) {
    log_error("Failed to create TCP client");
    connection_state_transition(ctx, CONN_STATE_FAILED);
    return SET_ERRNO(ERROR_NETWORK, "TCP client creation failed");
  }
 
  // Set timeout for this attempt
  ctx->attempt_start_time_ns = time_get_realtime_ns();
  ctx->timeout_ns = CONN_TIMEOUT_TCP;
 
  // Attempt TCP connection (reconnect_attempt is 0-based, convert for tcp_client_connect)
  // Use effective_address/port which may be parsed from tcp:// URL scheme
  int tcp_result = tcp_client_connect(tcp_client, endpoint.host, endpoint.port, (int)ctx->reconnect_attempt,
                                      ctx->reconnect_attempt == 0, ctx->reconnect_attempt > 0);
 
  if (tcp_result != 0) {
    log_debug("TCP connection failed (tcp_client_connect returned %d)", tcp_result);
    tcp_client_destroy(&tcp_client);
    connection_state_transition(ctx, CONN_STATE_FAILED);
    return SET_ERRNO(ERROR_NETWORK, "TCP connection failed after %u attempts", ctx->reconnect_attempt);
  }
 
  // Extract socket from TCP client for crypto handshake
  socket_t sockfd = tcp_client_get_socket(tcp_client);
  if (sockfd == INVALID_SOCKET_VALUE) {
    log_error("Failed to get socket from TCP client");
    tcp_client_destroy(&tcp_client);
    return SET_ERRNO(ERROR_NETWORK, "Invalid socket after TCP connection");
  }
 
  // Note: TCP client stores server IP in tcp_client->server_ip for potential crypto context use
  if (tcp_client->server_ip[0] != '\0') {
    log_debug("Server IP available from TCP client: %s", tcp_client->server_ip);
    APP_CALLBACK_VOID_STR(server_connection_set_ip, tcp_client->server_ip);
  } else {
    log_warn("TCP client did not populate server_ip field");
  }
 
  // Compute crypto mode from CLI options
  // Determine if client has authentication material (keys or password)
  bool has_auth_material =
      (GET_OPTION(encrypt_key)[0] != '\0' || GET_OPTION(num_identity_keys) > 0 || GET_OPTION(password)[0] != '\0');
  bool no_encrypt = GET_OPTION(no_encrypt);
  bool no_auth = GET_OPTION(no_auth);
 
  uint8_t crypto_mode;
  if (!no_encrypt && !no_auth && !has_auth_material)
    crypto_mode = ACIP_CRYPTO_ENCRYPT; // default: encrypt only
  else if (!no_encrypt && !no_auth && has_auth_material)
    crypto_mode = ACIP_CRYPTO_FULL; // full: encrypt + auth
  else if (no_encrypt && !no_auth && has_auth_material)
    crypto_mode = ACIP_CRYPTO_AUTH; // auth-only mode
  else
    crypto_mode = ACIP_CRYPTO_NONE; // no crypto
 
  log_debug("TCP crypto mode computed: 0x%02x (encrypt=%d, auth=%d)", crypto_mode, ACIP_CRYPTO_HAS_ENCRYPT(crypto_mode),
            ACIP_CRYPTO_HAS_AUTH(crypto_mode));
 
  // Setup crypto operations via callbacks
  const crypto_context_t *crypto_ctx = NULL;
  acip_transport_t *transport = NULL;
 
  if (crypto_mode != ACIP_CRYPTO_NONE) {
    APP_CALLBACK_VOID_UINT8(client_crypto_set_mode, crypto_mode);
 
    // Initialize crypto context if mode requires handshake (not ACIP_CRYPTO_NONE)
    // This must happen AFTER setting server IP, as crypto init reads server IP/port
    log_debug("Initializing crypto context...");
    if (APP_CALLBACK_INT(client_crypto_init) != 0) {
      log_error("Failed to initialize crypto context");
      tcp_client_destroy(&tcp_client);
      return SET_ERRNO(ERROR_CRYPTO, "Crypto initialization failed");
    }
    log_debug("Crypto context initialized successfully");
 
    // Create transport before handshake (starts with NULL crypto, set after)
    transport = acip_tcp_transport_create("connection", sockfd, NULL);
    if (!transport) {
      log_error("Failed to create ACIP transport for TCP");
      tcp_client_destroy(&tcp_client);
      return SET_ERRNO(ERROR_NETWORK, "Failed to create ACIP transport");
    }
 
    // Perform crypto handshake with server
    log_debug("Performing crypto handshake with server...");
    if (APP_CALLBACK_INT_TRANSPORT(client_crypto_handshake, transport) != 0) {
      log_error("Crypto handshake failed");
      acip_transport_destroy(transport);
      tcp_client_destroy(&tcp_client);
      return SET_ERRNO(ERROR_NETWORK, "Crypto handshake failed");
    }
    log_debug("Crypto handshake completed successfully");
 
    // Get crypto context after handshake and set it on the transport
    if (APP_CALLBACK_BOOL(crypto_client_is_ready)) {
      crypto_ctx = APP_CALLBACK_PTR(crypto_client_get_context);
      transport->crypto_ctx = (crypto_context_t *)crypto_ctx;
    }
  } else {
    // No crypto — create transport without encryption
    transport = acip_tcp_transport_create("connection", sockfd, NULL);
    if (!transport) {
      log_error("Failed to create ACIP transport for TCP");
      tcp_client_destroy(&tcp_client);
      return SET_ERRNO(ERROR_NETWORK, "Failed to create ACIP transport");
    }
  }
 
  log_info("TCP connection established to %s:%u", endpoint.host, endpoint.port);
  connection_state_transition(ctx, CONN_STATE_CONNECTED);
  ctx->connection.transport = transport;
  ctx->connection.transport_type = ACIP_TRANSPORT_TCP;
  ctx->connection.owner = tcp_client;
  ctx->connection.owner_destroy = destroy_tcp_client_owner;
  log_debug("TCP owner stored in connection context for cleanup");
 
  return ASCIICHAT_OK;
}

References ACIP_CRYPTO_AUTH, ACIP_CRYPTO_ENCRYPT, ACIP_CRYPTO_FULL, ACIP_CRYPTO_HAS_AUTH, ACIP_CRYPTO_HAS_ENCRYPT, ACIP_CRYPTO_NONE, acip_tcp_transport_create(), acip_transport_destroy(), ACIP_TRANSPORT_TCP, ACIP_TRANSPORT_WEBSOCKET, APP_CALLBACK_BOOL, APP_CALLBACK_INT, APP_CALLBACK_INT_TRANSPORT, APP_CALLBACK_PTR, APP_CALLBACK_VOID_INT, APP_CALLBACK_VOID_STR, APP_CALLBACK_VOID_UINT8, ASCIICHAT_OK, connection_attempt_context_t::attempt_start_time_ns, client_crypto_handshake(), client_crypto_init(), client_crypto_set_mode(), CONN_STATE_ATTEMPTING, CONN_STATE_CONNECTED, CONN_STATE_FAILED, CONN_TIMEOUT_TCP, connection_attempt_context_t::connection, connection_endpoint_protocol_name(), connection_endpoint_resolve(), CONNECTION_ENDPOINT_WEBSOCKET, connection_state_transition(), crypto_client_get_context(), crypto_client_is_ready(), acip_transport::crypto_ctx, ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_NETWORK, GET_OPTION, connection_endpoint_t::host, connection_endpoint_t::input, INVALID_SOCKET_VALUE, log_debug, log_error, log_info, log_warn, connection_handle_t::owner, connection_handle_t::owner_destroy, platform_sleep_us(), connection_endpoint_t::port, connection_endpoint_t::protocol, connection_attempt_context_t::reconnect_attempt, server_connection_set_ip(), server_connection_set_port(), tcp_client::server_ip, SET_ERRNO, should_exit(), tcp_client_connect(), tcp_client_create(), tcp_client_destroy(), tcp_client_get_socket(), time_get_realtime_ns(), connection_attempt_context_t::timeout_ns, connection_handle_t::transport, connection_handle_t::transport_type, websocket_client_connect(), websocket_client_create(), and websocket_client_destroy().

connection_attempt_websocket()

asciichat_error_t connection_attempt_websocket	(	connection_attempt_context_t *	ctx,
		const char *	ws_url
	)

Attempt WebSocket connection.

Attempts a WebSocket connection to the specified server (ws:// or wss://). On success, sets the transport in the context handle.

Handles:

• WebSocket URL parsing
• Crypto initialization (when encryption enabled)
• ACIP transport creation

Parameters

ctx	Connection context (initialized via connection_context_init)
ws_url	WebSocket URL (e.g., "ws://localhost:27226" or "wss://server.com")

Returns

ASCIICHAT_OK on successful connection

ERROR_* code on failure

Note

ctx.connection.transport will be set to the WebSocket transport on success

ctx.current_state will be set to CONN_STATE_CONNECTED on success

Attempt WebSocket connection.

Connects to server via WebSocket, performs crypto handshake if enabled, and creates ACIP transport for protocol communication.

Definition at line 436 of file connection_attempt.c.

                                                                                                      {
  log_info("=== connection_attempt_websocket CALLED: url='%s' ===", ws_url);
 
  if (!ctx || !ws_url) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  // Check if shutdown was requested (via callback if available)
  if (APP_CALLBACK_BOOL(should_exit)) {
    return SET_ERRNO(ERROR_NETWORK, "Connection attempt aborted due to shutdown request");
  }
 
  log_info("Attempting WebSocket connection to %s", ws_url);
 
  // Transition to attempting state
  asciichat_error_t result = connection_state_transition(ctx, CONN_STATE_ATTEMPTING);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  // Set timeout for this attempt
  ctx->attempt_start_time_ns = time_get_realtime_ns();
  ctx->timeout_ns = CONN_TIMEOUT_TCP;
 
  // Initialize crypto context if encryption is enabled
  const crypto_context_t *crypto_ctx = NULL;
  if (!GET_OPTION(no_encrypt)) {
    log_debug("Initializing crypto context for WebSocket...");
 
    if (APP_CALLBACK_INT(client_crypto_init) != 0) {
      log_error("Failed to initialize crypto context");
      return SET_ERRNO(ERROR_CRYPTO, "Crypto initialization failed");
    }
    log_debug("Crypto context initialized successfully");
 
    // Get crypto context if ready
    if (APP_CALLBACK_BOOL(crypto_client_is_ready)) {
      crypto_ctx = APP_CALLBACK_PTR(crypto_client_get_context);
    }
  }
 
  // Create WebSocket client instance
  websocket_client_t *ws_client = websocket_client_create("connection");
  if (!ws_client) {
    log_error("Failed to create WebSocket client");
    connection_state_transition(ctx, CONN_STATE_FAILED);
    return SET_ERRNO(ERROR_NETWORK, "WebSocket client creation failed");
  }
 
  // Connect via WebSocket
  acip_transport_t *transport = websocket_client_connect(ws_client, ws_url, (crypto_context_t *)crypto_ctx);
  if (!transport) {
    log_error("Failed to create WebSocket ACIP transport");
    websocket_client_destroy(&ws_client);
    connection_state_transition(ctx, CONN_STATE_FAILED);
    return SET_ERRNO(ERROR_NETWORK, "WebSocket connection failed");
  }
 
  log_info("WebSocket connection established to %s", ws_url);
  connection_state_transition(ctx, CONN_STATE_CONNECTED);
  ctx->connection.transport = transport;
  ctx->connection.transport_type = ACIP_TRANSPORT_WEBSOCKET;
  ctx->connection.owner = ws_client;
  ctx->connection.owner_destroy = destroy_websocket_client_owner;
  log_debug("WebSocket owner stored in connection context");
 
  return ASCIICHAT_OK;
}

References ACIP_TRANSPORT_WEBSOCKET, APP_CALLBACK_BOOL, APP_CALLBACK_INT, APP_CALLBACK_PTR, ASCIICHAT_OK, connection_attempt_context_t::attempt_start_time_ns, client_crypto_init(), CONN_STATE_ATTEMPTING, CONN_STATE_CONNECTED, CONN_STATE_FAILED, CONN_TIMEOUT_TCP, connection_attempt_context_t::connection, connection_state_transition(), crypto_client_get_context(), crypto_client_is_ready(), ERROR_CRYPTO, ERROR_INVALID_PARAM, ERROR_NETWORK, GET_OPTION, log_debug, log_error, log_info, connection_handle_t::owner, connection_handle_t::owner_destroy, SET_ERRNO, should_exit(), time_get_realtime_ns(), connection_attempt_context_t::timeout_ns, connection_handle_t::transport, connection_handle_t::transport_type, websocket_client_connect(), websocket_client_create(), and websocket_client_destroy().

connection_check_timeout()

bool connection_check_timeout

(

const connection_attempt_context_t *

ctx

)

Check if connection attempt has exceeded timeout.

Compares elapsed time since attempt start against timeout.

Parameters

ctx	Connection context

Returns

true if timeout exceeded, false otherwise

Definition at line 141 of file connection_attempt.c.

                                                                       {
  if (!ctx)
    return false;
 
  uint64_t elapsed_ns = time_get_realtime_ns() - ctx->attempt_start_time_ns;
  bool timeout_exceeded = elapsed_ns > ctx->timeout_ns;
 
  if (timeout_exceeded) {
    char elapsed_str[32], timeout_str[32];
    time_pretty(elapsed_ns, -1, elapsed_str, sizeof(elapsed_str));
    time_pretty(ctx->timeout_ns, -1, timeout_str, sizeof(timeout_str));
    log_warn("Connection timeout exceeded: elapsed %s > %s limit", elapsed_str, timeout_str);
  }
 
  return timeout_exceeded;
}

References connection_attempt_context_t::attempt_start_time_ns, log_warn, time_get_realtime_ns(), time_pretty(), and connection_attempt_context_t::timeout_ns.

connection_context_cleanup()

void connection_context_cleanup

(

connection_attempt_context_t *

ctx

)

Cleanup connection attempt context.

Closes and releases any active transports. Called on connection success, failure, or shutdown.

Parameters

ctx	Connection context to cleanup

Definition at line 111 of file connection_attempt.c.

                                                                   {
  if (!ctx)
    return;
 
  connection_handle_cleanup(&ctx->connection);
 
  log_debug("Connection context cleaned up");
}

References connection_attempt_context_t::connection, connection_handle_cleanup(), and log_debug.

Referenced by client_main().

connection_context_init()

asciichat_error_t connection_context_init

(

connection_attempt_context_t *

ctx

)

Initialize connection attempt context.

Sets up initial state, resets timeouts, and prepares for connection attempt.

Parameters

ctx	Connection context to initialize

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 82 of file connection_attempt.c.

                                                                             {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Context pointer is NULL");
  }
 
  // Reset context
  memset(ctx, 0, sizeof(connection_attempt_context_t));
  connection_handle_init(&ctx->connection);
 
  // Initialize state
  ctx->current_state = CONN_STATE_IDLE;
  ctx->previous_state = CONN_STATE_IDLE;
 
  // Initialize timeout
  ctx->attempt_start_time_ns = time_get_realtime_ns();
  ctx->timeout_ns = CONN_TIMEOUT_TCP;
 
  // Initialize counters
  ctx->reconnect_attempt = 1;
  ctx->total_transitions = 0;
 
  log_debug("Connection context initialized");
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, connection_attempt_context_t::attempt_start_time_ns, CONN_STATE_IDLE, CONN_TIMEOUT_TCP, connection_attempt_context_t::connection, connection_handle_init(), connection_attempt_context_t::current_state, ERROR_INVALID_PARAM, ERROR_NOT_SUPPORTED, log_debug, connection_attempt_context_t::previous_state, connection_attempt_context_t::reconnect_attempt, SET_ERRNO, time_get_realtime_ns(), connection_attempt_context_t::timeout_ns, and connection_attempt_context_t::total_transitions.

Referenced by client_main().

connection_state_name()

const char * connection_state_name

(

connection_state_t

state

)

Get human-readable state name for logging.

Parameters

state

Connection state

Returns

Static string representation (e.g., "CONNECTED")

Definition at line 58 of file connection_attempt.c.

                                                            {
  switch (state) {
  case CONN_STATE_IDLE:
    return "IDLE";
  case CONN_STATE_ATTEMPTING:
    return "ATTEMPTING";
  case CONN_STATE_CONNECTED:
    return "CONNECTED";
  case CONN_STATE_DISCONNECTED:
    return "DISCONNECTED";
  case CONN_STATE_FAILED:
    return "FAILED";
  default:
    return "UNKNOWN";
  }
}

References CONN_STATE_ATTEMPTING, CONN_STATE_CONNECTED, CONN_STATE_DISCONNECTED, CONN_STATE_FAILED, and CONN_STATE_IDLE.

Referenced by connection_state_transition().

connection_state_transition()

asciichat_error_t connection_state_transition	(	connection_attempt_context_t *	ctx,
		connection_state_t	new_state
	)

Transition to next connection state.

Updates current/previous states, logs transition, and updates timeout if stage changed. Validates state transitions to prevent invalid sequences.

Parameters

ctx	Connection context
new_state	Next state to transition to

Returns

ASCIICHAT_OK on success, error code on invalid transition

Transition to next connection state.

Definition at line 123 of file connection_attempt.c.

                                                                                                               {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Context pointer is NULL");
  }
 
  // Store previous state
  ctx->previous_state = ctx->current_state;
  ctx->current_state = new_state;
  ctx->total_transitions++;
 
  log_debug("State transition: %s → %s", connection_state_name(ctx->previous_state), connection_state_name(new_state));
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, connection_state_name(), connection_attempt_context_t::current_state, ERROR_INVALID_PARAM, log_debug, connection_attempt_context_t::previous_state, SET_ERRNO, and connection_attempt_context_t::total_transitions.

Referenced by connection_attempt_tcp(), and connection_attempt_websocket().