connection_attempt.c File Reference

🎯 Connection fallback orchestrator for Phase 3 WebRTC integration More...

Go to the source code of this file.

Functions
const char *	connection_state_name (connection_state_t state)
	Get human-readable state name for logging.
uint32_t	connection_get_stage (connection_state_t state)
	Get current stage number (1, 2, or 3) from state.
asciichat_error_t	connection_context_init (connection_attempt_context_t *ctx, bool prefer_webrtc, bool no_webrtc, bool webrtc_skip_stun, bool webrtc_disable_turn)
	Initialize connection attempt context.
void	connection_context_cleanup (connection_attempt_context_t *ctx)
	Cleanup connection attempt context.
asciichat_error_t	connection_state_transition (connection_attempt_context_t *ctx, connection_state_t new_state)
	Transition to next connection state with validation.
bool	connection_check_timeout (const connection_attempt_context_t *ctx)
	Check if current stage has exceeded timeout.
asciichat_error_t	connection_attempt_with_fallback (connection_attempt_context_t *ctx, const char *server_address, uint16_t server_port, const char *acds_server, uint16_t acds_port)
	Orchestrate connection attempt with automatic fallback.

Detailed Description

🎯 Connection fallback orchestrator for Phase 3 WebRTC integration

Implements the 3-stage connection fallback sequence:

1. Stage 1: Direct TCP (3s timeout) - Fastest path for accessible servers
2. Stage 2: WebRTC + STUN (8s timeout) - NAT traversal via hole punching
3. Stage 3: WebRTC + TURN (15s timeout) - Last resort relay

Features:

• State machine with 13 states tracking all stages
• Automatic timeout-based progression between stages
• CLI flags to override or force specific connection methods
• Proper resource cleanup on transitions and failures
• Detailed logging of state transitions and errors

Integration Points:

• Called from src/client/main.c connection loop (replaces direct TCP attempt)
• Returns active transport when connection succeeds
• Maintains session context for WebRTC handshake via ACDS

Date

January 2026

Version

1.0

Definition in file connection_attempt.c.

Function Documentation

connection_attempt_with_fallback()

asciichat_error_t connection_attempt_with_fallback	(	connection_attempt_context_t *	ctx,
		const char *	server_address,
		uint16_t	server_port,
		const char *	acds_server,
		uint16_t	acds_port
	)

Orchestrate connection attempt with automatic fallback.

Attempt connection with 3-stage fallback sequence.

Implements 3-stage fallback sequence:

1. Direct TCP (3s) - Fastest for accessible servers
2. WebRTC + STUN (8s) - NAT traversal
3. WebRTC + TURN (15s) - Last resort relay

Each stage is attempted until success or timeout. On timeout, falls back to next stage. Returns ASCIICHAT_OK and sets ctx->active_transport when connection succeeds. Returns error code when all stages fail.

Called from src/client/main.c in the connection loop. Replaces direct TCP connection attempt with automatic fallback.

Parameters

ctx	Connection context (initialized by caller)
server_address	Server IP/hostname
server_port	Server port
acds_server	ACDS discovery server address
acds_port	ACDS discovery server port

Returns

ASCIICHAT_OK on successful connection, error code otherwise

Definition at line 882 of file connection_attempt.c.

                                                                                                                      {
  if (!ctx || !server_address || !acds_server) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  log_info("=== Connection attempt %u: %s:%u (fallback strategy: TCP → STUN → TURN) ===", ctx->reconnect_attempt,
           server_address, server_port);
 
  asciichat_error_t result = ASCIICHAT_OK;
 
  // ─────────────────────────────────────────────────────────────
  // Stage 1: Direct TCP (3s timeout)
  // ─────────────────────────────────────────────────────────────
 
  if (!ctx->prefer_webrtc && !ctx->no_webrtc) {
    // Normal path: try TCP first unless WebRTC preferred
    result = attempt_direct_tcp(ctx, server_address, server_port);
    if (result == ASCIICHAT_OK) {
      log_info("Connection succeeded via Direct TCP");
      connection_state_transition(ctx, CONN_STATE_CONNECTED);
      return ASCIICHAT_OK;
    }
 
    // Check if timeout (fall back to next stage)
    if (connection_check_timeout(ctx)) {
      log_info("Stage 1 timeout, proceeding to Stage 2 (WebRTC+STUN)");
    } else {
      // Actual failure (not just timeout) - could be local error
      log_warn("Stage 1 failed immediately, proceeding to Stage 2");
    }
  } else if (ctx->no_webrtc) {
    // TCP-only mode - don't try WebRTC at all
    result = attempt_direct_tcp(ctx, server_address, server_port);
    if (result == ASCIICHAT_OK) {
      log_info("Connection succeeded via Direct TCP (--no-webrtc)");
      connection_state_transition(ctx, CONN_STATE_CONNECTED);
      return ASCIICHAT_OK;
    }
    log_error("Direct TCP failed with --no-webrtc flag");
    connection_state_transition(ctx, CONN_STATE_FAILED);
    return result;
  }
 
  // ─────────────────────────────────────────────────────────────
  // Stage 2: WebRTC + STUN (8s timeout)
  // ─────────────────────────────────────────────────────────────
 
  result = attempt_webrtc_stun(ctx, server_address, server_port, acds_server, acds_port);
  if (result == ASCIICHAT_OK) {
    log_info("Connection succeeded via WebRTC+STUN");
    connection_state_transition(ctx, CONN_STATE_CONNECTED);
    return ASCIICHAT_OK;
  }
 
  if (result == ERROR_NETWORK) {
    log_debug("WebRTC+STUN stage skipped per CLI flags");
  } else if (connection_check_timeout(ctx)) {
    log_info("Stage 2 timeout, proceeding to Stage 3 (WebRTC+TURN)");
  } else {
    log_warn("Stage 2 failed immediately, proceeding to Stage 3");
  }
 
  // ─────────────────────────────────────────────────────────────
  // Stage 3: WebRTC + TURN (15s timeout)
  // ─────────────────────────────────────────────────────────────
 
  result = attempt_webrtc_turn(ctx, server_address, server_port, acds_server, acds_port);
  if (result == ASCIICHAT_OK) {
    log_info("Connection succeeded via WebRTC+TURN");
    connection_state_transition(ctx, CONN_STATE_CONNECTED);
    return ASCIICHAT_OK;
  }
 
  if (result == ERROR_NETWORK) {
    log_debug("WebRTC+TURN stage skipped per CLI flags");
  } else if (connection_check_timeout(ctx)) {
    log_error("Stage 3 timeout - all fallback stages exhausted");
  } else {
    log_error("Stage 3 failed - all fallback stages exhausted");
  }
 
  // ─────────────────────────────────────────────────────────────
  // All stages failed
  // ─────────────────────────────────────────────────────────────
 
  connection_state_transition(ctx, CONN_STATE_FAILED);
  return SET_ERRNO(ERROR_NETWORK, "All fallback stages exhausted (TCP: failed, STUN: %s, TURN: %s)",
                   ctx->webrtc_skip_stun ? "skipped" : "failed", ctx->webrtc_disable_turn ? "skipped" : "failed");
}

References ASCIICHAT_OK, CONN_STATE_CONNECTED, CONN_STATE_FAILED, connection_check_timeout(), connection_state_transition(), ERROR_INVALID_PARAM, ERROR_NETWORK, log_debug, log_error, log_info, log_warn, connection_attempt_context_t::no_webrtc, connection_attempt_context_t::prefer_webrtc, connection_attempt_context_t::reconnect_attempt, SET_ERRNO, connection_attempt_context_t::webrtc_disable_turn, and connection_attempt_context_t::webrtc_skip_stun.

Referenced by client_main().

connection_check_timeout()

bool connection_check_timeout

(

const connection_attempt_context_t *

ctx

)

Check if current stage has exceeded timeout.

Compares elapsed time since stage_start_time against current_stage_timeout_seconds.

Parameters

ctx	Connection context

Returns

true if timeout exceeded, false otherwise

Definition at line 234 of file connection_attempt.c.

                                                                       {
  if (!ctx)
    return false;
 
  time_t elapsed = time(NULL) - ctx->stage_start_time;
  bool timeout_exceeded = elapsed > (time_t)ctx->current_stage_timeout_seconds;
 
  if (timeout_exceeded) {
    log_warn("Stage timeout exceeded: stage %u, elapsed %ld seconds > %u seconds limit",
             connection_get_stage(ctx->current_state), elapsed, ctx->current_stage_timeout_seconds);
  }
 
  return timeout_exceeded;
}

References connection_get_stage(), connection_attempt_context_t::current_stage_timeout_seconds, connection_attempt_context_t::current_state, log_warn, and connection_attempt_context_t::stage_start_time.

Referenced by connection_attempt_with_fallback().

connection_context_cleanup()

void connection_context_cleanup

(

connection_attempt_context_t *

ctx

)

Cleanup connection attempt context.

Closes and releases any active transports, frees WebRTC peer manager. Called on connection success, failure, or shutdown.

Parameters

ctx	Connection context to cleanup

Definition at line 156 of file connection_attempt.c.

                                                                   {
  if (!ctx)
    return;
 
  // Destroy TCP client instance if created
  if (ctx->tcp_client_instance) {
    tcp_client_destroy(&ctx->tcp_client_instance);
    ctx->tcp_client_instance = NULL;
    log_debug("TCP client instance destroyed");
  }
 
  // Close TCP transport if still open
  if (ctx->tcp_transport) {
    acip_transport_close(ctx->tcp_transport);
    acip_transport_destroy(ctx->tcp_transport);
    ctx->tcp_transport = NULL;
  }
 
  // Close WebRTC transport if still open
  if (ctx->webrtc_transport) {
    acip_transport_close(ctx->webrtc_transport);
    acip_transport_destroy(ctx->webrtc_transport);
    ctx->webrtc_transport = NULL;
  }
 
  // Cleanup peer manager
  if (ctx->peer_manager) {
    webrtc_peer_manager_destroy(ctx->peer_manager);
    ctx->peer_manager = NULL;
  }
 
  ctx->active_transport = NULL;
  log_debug("Connection context cleaned up");
}

References acip_transport_destroy(), connection_attempt_context_t::active_transport, log_debug, connection_attempt_context_t::peer_manager, tcp_client_destroy(), connection_attempt_context_t::tcp_client_instance, connection_attempt_context_t::tcp_transport, webrtc_peer_manager_destroy(), and connection_attempt_context_t::webrtc_transport.

Referenced by client_main().

connection_context_init()

asciichat_error_t connection_context_init	(	connection_attempt_context_t *	ctx,
		bool	prefer_webrtc,
		bool	no_webrtc,
		bool	webrtc_skip_stun,
		bool	webrtc_disable_turn
	)

Initialize connection attempt context.

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

Parameters

ctx	Connection context to initialize
prefer_webrtc	CLI flag: prefer WebRTC over TCP
no_webrtc	CLI flag: disable WebRTC, use TCP only
webrtc_skip_stun	CLI flag: skip STUN stage, go straight to TURN
webrtc_disable_turn	CLI flag: disable TURN stage (use STUN as fallback)

Returns

ASCIICHAT_OK on success, error code otherwise

Definition at line 118 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));
 
  // Initialize state
  ctx->current_state = CONN_STATE_IDLE;
  ctx->previous_state = CONN_STATE_IDLE;
 
  // Set CLI preferences
  ctx->prefer_webrtc = prefer_webrtc;
  ctx->no_webrtc = no_webrtc;
  ctx->webrtc_skip_stun = webrtc_skip_stun;
  ctx->webrtc_disable_turn = webrtc_disable_turn;
 
  // Initialize timeout
  ctx->stage_start_time = time(NULL);
  ctx->current_stage_timeout_seconds = CONN_TIMEOUT_DIRECT_TCP;
 
  // Initialize counters
  ctx->reconnect_attempt = 1;
  ctx->stage_failures = 0;
  ctx->total_transitions = 0;
 
  log_debug(
      "Connection context initialized (prefer_webrtc=%d, no_webrtc=%d, webrtc_skip_stun=%d, webrtc_disable_turn=%d)",
      prefer_webrtc, no_webrtc, webrtc_skip_stun, webrtc_disable_turn);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONN_STATE_IDLE, CONN_TIMEOUT_DIRECT_TCP, connection_attempt_context_t::current_stage_timeout_seconds, connection_attempt_context_t::current_state, ERROR_INVALID_PARAM, log_debug, connection_attempt_context_t::no_webrtc, connection_attempt_context_t::prefer_webrtc, connection_attempt_context_t::previous_state, connection_attempt_context_t::reconnect_attempt, SET_ERRNO, connection_attempt_context_t::stage_failures, connection_attempt_context_t::stage_start_time, connection_attempt_context_t::total_transitions, connection_attempt_context_t::webrtc_disable_turn, and connection_attempt_context_t::webrtc_skip_stun.

Referenced by client_main().

connection_get_stage()

uint32_t connection_get_stage

(

connection_state_t

state

)

Get current stage number (1, 2, or 3) from state.

Get current stage number (1, 2, or 3)

Definition at line 98 of file connection_attempt.c.

                                                        {
  if (state >= CONN_STATE_ATTEMPTING_DIRECT_TCP && state <= CONN_STATE_DIRECT_TCP_FAILED) {
    return 1;
  }
  if (state >= CONN_STATE_ATTEMPTING_WEBRTC_STUN && state <= CONN_STATE_WEBRTC_STUN_FAILED) {
    return 2;
  }
  if (state >= CONN_STATE_ATTEMPTING_WEBRTC_TURN && state <= CONN_STATE_WEBRTC_TURN_FAILED) {
    return 3;
  }
  return 0; // Idle or terminal state
}

References CONN_STATE_ATTEMPTING_DIRECT_TCP, CONN_STATE_ATTEMPTING_WEBRTC_STUN, CONN_STATE_ATTEMPTING_WEBRTC_TURN, CONN_STATE_DIRECT_TCP_FAILED, CONN_STATE_WEBRTC_STUN_FAILED, and CONN_STATE_WEBRTC_TURN_FAILED.

Referenced by connection_check_timeout(), and connection_state_transition().

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., "DIRECT_TCP_CONNECTED")

Definition at line 54 of file connection_attempt.c.

                                                            {
  switch (state) {
  case CONN_STATE_IDLE:
    return "IDLE";
  case CONN_STATE_CONNECTED:
    return "CONNECTED";
  case CONN_STATE_DISCONNECTED:
    return "DISCONNECTED";
  case CONN_STATE_FAILED:
    return "FAILED";
 
  case CONN_STATE_ATTEMPTING_DIRECT_TCP:
    return "ATTEMPTING_DIRECT_TCP";
  case CONN_STATE_DIRECT_TCP_CONNECTED:
    return "DIRECT_TCP_CONNECTED";
  case CONN_STATE_DIRECT_TCP_FAILED:
    return "DIRECT_TCP_FAILED";
 
  case CONN_STATE_ATTEMPTING_WEBRTC_STUN:
    return "ATTEMPTING_WEBRTC_STUN";
  case CONN_STATE_WEBRTC_STUN_SIGNALING:
    return "WEBRTC_STUN_SIGNALING";
  case CONN_STATE_WEBRTC_STUN_CONNECTED:
    return "WEBRTC_STUN_CONNECTED";
  case CONN_STATE_WEBRTC_STUN_FAILED:
    return "WEBRTC_STUN_FAILED";
 
  case CONN_STATE_ATTEMPTING_WEBRTC_TURN:
    return "ATTEMPTING_WEBRTC_TURN";
  case CONN_STATE_WEBRTC_TURN_SIGNALING:
    return "WEBRTC_TURN_SIGNALING";
  case CONN_STATE_WEBRTC_TURN_CONNECTED:
    return "WEBRTC_TURN_CONNECTED";
  case CONN_STATE_WEBRTC_TURN_FAILED:
    return "WEBRTC_TURN_FAILED";
 
  default:
    return "UNKNOWN";
  }
}

References CONN_STATE_ATTEMPTING_DIRECT_TCP, CONN_STATE_ATTEMPTING_WEBRTC_STUN, CONN_STATE_ATTEMPTING_WEBRTC_TURN, CONN_STATE_CONNECTED, CONN_STATE_DIRECT_TCP_CONNECTED, CONN_STATE_DIRECT_TCP_FAILED, CONN_STATE_DISCONNECTED, CONN_STATE_FAILED, CONN_STATE_IDLE, CONN_STATE_WEBRTC_STUN_CONNECTED, CONN_STATE_WEBRTC_STUN_FAILED, CONN_STATE_WEBRTC_STUN_SIGNALING, CONN_STATE_WEBRTC_TURN_CONNECTED, CONN_STATE_WEBRTC_TURN_FAILED, and CONN_STATE_WEBRTC_TURN_SIGNALING.

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

Transition to next connection state.

Definition at line 194 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++;
 
  // Update timeout based on new stage
  uint32_t new_stage = connection_get_stage(new_state);
  uint32_t old_stage = connection_get_stage(ctx->previous_state);
 
  if (new_stage != old_stage && new_stage > 0) {
    ctx->stage_start_time = time(NULL);
    switch (new_stage) {
    case 1:
      ctx->current_stage_timeout_seconds = CONN_TIMEOUT_DIRECT_TCP;
      break;
    case 2:
      ctx->current_stage_timeout_seconds = CONN_TIMEOUT_WEBRTC_STUN;
      break;
    case 3:
      ctx->current_stage_timeout_seconds = CONN_TIMEOUT_WEBRTC_TURN;
      break;
    default:
      break;
    }
  }
 
  log_debug("State transition: %s → %s (stage %u → %u)", connection_state_name(ctx->previous_state),
            connection_state_name(new_state), old_stage, new_stage);
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, CONN_TIMEOUT_DIRECT_TCP, CONN_TIMEOUT_WEBRTC_STUN, CONN_TIMEOUT_WEBRTC_TURN, connection_get_stage(), connection_state_name(), connection_attempt_context_t::current_stage_timeout_seconds, connection_attempt_context_t::current_state, ERROR_INVALID_PARAM, log_debug, connection_attempt_context_t::previous_state, SET_ERRNO, connection_attempt_context_t::stage_start_time, and connection_attempt_context_t::total_transitions.

Referenced by connection_attempt_with_fallback().