Data Structures
struct	host_liveness_t
	When code needs to work with host liveness, it keeps last_ping_sent_ms, last_pong_received_ms, consecutive_failures, max_failures here instead of scattering it across globals. Initialization establishes the handles and sizes; teardown must release any allocation, lock, thread, or callback context recorded in those fields. More...
struct	discovery_session_t
	Discovery session context. More...
struct	discovery_config_t
	Configuration for discovery session. More...

Macros
#define	DISCOVERY_SESSION_ACDS_ADDRESS_BUFFER_SIZE 64
#define	DISCOVERY_SESSION_ACDS_URL_BUFFER_SIZE 512

Typedefs
typedef bool(*	discovery_should_exit_fn) (void *user_data)
	Callback to check if session should exit.

Enumerations
enum	discovery_state_t { DISCOVERY_STATE_INIT , DISCOVERY_STATE_CONNECTING_ACDS , DISCOVERY_STATE_CREATING_SESSION , DISCOVERY_STATE_JOINING_SESSION , DISCOVERY_STATE_WAITING_PEER , DISCOVERY_STATE_NEGOTIATING , DISCOVERY_STATE_STARTING_HOST , DISCOVERY_STATE_CONNECTING_HOST , DISCOVERY_STATE_ACTIVE , DISCOVERY_STATE_MIGRATING , DISCOVERY_STATE_FAILED , DISCOVERY_STATE_ENDED }
	Discovery session state. More...

Functions
discovery_session_t *	discovery_session_create (const discovery_config_t *config)
	Configuration for discovery session.
asciichat_error_t	discovery_session_destroy (discovery_session_t *session)
	Destroy discovery session and free resources.
asciichat_error_t	discovery_session_start (discovery_session_t *session)
	Start the discovery session.
asciichat_error_t	discovery_session_process (discovery_session_t *session, int64_t timeout_ns)
	Process session events (call in main loop).
void	discovery_session_stop (discovery_session_t *session)
	Stop the discovery session.
discovery_state_t	discovery_session_get_state (const discovery_session_t *session)
	Get current session state.
bool	discovery_session_is_active (const discovery_session_t *session)
	Check if session is active (call in progress).
const char *	discovery_session_get_string (const discovery_session_t *session)
	Get session string.
bool	discovery_session_is_host (const discovery_session_t *session)
	Check if we are the host.
session_host_t *	discovery_session_get_host (discovery_session_t *session)
	Get host context (if we are host).
session_participant_t *	discovery_session_get_participant (discovery_session_t *session)
	Get participant context (if we are participant).
asciichat_error_t	discovery_session_check_host_alive (discovery_session_t *session)
	Detect host disconnect (check connection status).
void	discovery_session_host_pong (discovery_session_t *session)
asciichat_error_t	discovery_session_handle_host_disconnect (discovery_session_t *session, uint32_t disconnect_reason)
	Report host disconnect and await the ACDS recovery decision.
asciichat_error_t	discovery_session_apply_handoff (discovery_session_t *session)
	Replace the old role after a committed handoff and media-worker shutdown. Releases borrowed-role resources, resets liveness, and initializes the committed successor connection. Callers must stop media workers before entering this function.

Macro Definition Documentation

◆ DISCOVERY_SESSION_ACDS_ADDRESS_BUFFER_SIZE

#define DISCOVERY_SESSION_ACDS_ADDRESS_BUFFER_SIZE 64

Definition at line 4 of file src/discovery/session.h.

◆ DISCOVERY_SESSION_ACDS_URL_BUFFER_SIZE

#define DISCOVERY_SESSION_ACDS_URL_BUFFER_SIZE 512

Definition at line 5 of file src/discovery/session.h.

Typedef Documentation

◆ discovery_should_exit_fn

typedef bool(* discovery_should_exit_fn) (void *user_data)

Callback to check if session should exit.

Called periodically during blocking operations (e.g., ACDS connect, join). Should return true to gracefully cancel the current operation.

Parameters

user_data Opaque pointer provided by caller

Returns: true to cancel operation, false to continue

Definition at line 76 of file src/discovery/session.h.

Enumeration Type Documentation

◆ discovery_state_t

enum discovery_state_t

Discovery session state.

Enumerator
DISCOVERY_STATE_INIT	Initial state.
DISCOVERY_STATE_CONNECTING_ACDS	Connecting to ACDS.
DISCOVERY_STATE_CREATING_SESSION	Creating new session.
DISCOVERY_STATE_JOINING_SESSION	Joining existing session.
DISCOVERY_STATE_WAITING_PEER	Waiting for peer to join (initiator).
DISCOVERY_STATE_NEGOTIATING	NAT negotiation in progress.
DISCOVERY_STATE_STARTING_HOST	Starting as host.
DISCOVERY_STATE_CONNECTING_HOST	Connecting to host as participant.
DISCOVERY_STATE_ACTIVE	Session active (call in progress).
DISCOVERY_STATE_MIGRATING	Host migration in progress.
DISCOVERY_STATE_FAILED	Session failed.
DISCOVERY_STATE_ENDED	Session ended.

Definition at line 81 of file src/discovery/session.h.

             {
  DISCOVERY_STATE_INIT,             
  DISCOVERY_STATE_CONNECTING_ACDS,  
  DISCOVERY_STATE_CREATING_SESSION, 
  DISCOVERY_STATE_JOINING_SESSION,  
  DISCOVERY_STATE_WAITING_PEER,     
  DISCOVERY_STATE_NEGOTIATING,      
  DISCOVERY_STATE_STARTING_HOST,    
  DISCOVERY_STATE_CONNECTING_HOST,  
  DISCOVERY_STATE_ACTIVE,           
  DISCOVERY_STATE_MIGRATING,        
  DISCOVERY_STATE_FAILED,           
  DISCOVERY_STATE_ENDED             
} discovery_state_t;

Function Documentation

◆ discovery_session_apply_handoff()

asciichat_error_t discovery_session_apply_handoff ( discovery_session_t * session )

Replace the old role after a committed handoff and media-worker shutdown. Releases borrowed-role resources, resets liveness, and initializes the committed successor connection. Callers must stop media workers before entering this function.

Apply a committed role change after media workers have stopped.

Returns: ASCIICHAT_OK if no handoff is pending or initialization succeeds.

Definition at line 1172 of file src/discovery/session.c.

                                                                                {
  if (!session || !session->handoff_pending)
    return ASCIICHAT_OK;
  session->handoff_pending = false;
  if (session->participant_ctx) {
    session_participant_destroy(session->participant_ctx);
    session->participant_ctx = NULL;
  }
  if (session->peer_manager) {
    webrtc_peer_manager_destroy(session->peer_manager);
    session->peer_manager = NULL;
  }
  session->is_host = !memcmp(session->host_id, session->participant_id, SESSION_ID_SIZE);
  if (!session->is_host && session->host_ctx) {
    session_host_destroy(session->host_ctx);
    session->host_ctx = NULL;
  }
  session->webrtc_transport_ready = false;
  session->webrtc_connection_initiated = false;
  session->webrtc_retry_attempt = 0;
  session->webrtc_disconnected_since_ms = 0;
  session->liveness.ping_in_flight = false;
  session->liveness.consecutive_failures = 0;
  session->liveness.last_ping_sent_ms = session_get_current_time_ms();
  atomic_store_u64(&session->liveness.last_pong_received_ms, 0);
  if (session->session_type == SESSION_TYPE_WEBRTC) {
    asciichat_error_t result = initialize_webrtc_peer_manager(session);
    if (result != ASCIICHAT_OK)
      return result;
  }
  ascii_otel_metric(ASCII_OTEL_METRIC_HOST_CHANGES_APPLIED, 1);
  session->host_loss_detected_ms = 0;
 
  set_state(session, session->is_host ? DISCOVERY_STATE_STARTING_HOST : DISCOVERY_STATE_CONNECTING_HOST);
  return ASCIICHAT_OK;
}

◆ discovery_session_check_host_alive()

asciichat_error_t discovery_session_check_host_alive ( discovery_session_t * session )

Detect host disconnect (check connection status).

Parameters

session Session context

Returns: ASCIICHAT_OK if host alive, error if disconnected

Detect host disconnect (check connection status).

Returns: ASCIICHAT_OK for a live host, or a network error after loss is detected.

Definition at line 2210 of file src/discovery/session.c.

                                                                                   {
  if (!session || session->is_host) {
    // We are the host, so "host" is always alive
    return ASCIICHAT_OK;
  }
 
  // For WebRTC sessions, check the WebRTC transport instead of participant_ctx
  if (session->session_type == SESSION_TYPE_WEBRTC) {
    // If we have a WebRTC transport and it's marked as ready, host is alive
    if (session->webrtc_transport_ready) {
      return ASCIICHAT_OK;
    }
    // WebRTC transport not ready yet - might still be connecting
    return ERROR_NETWORK;
  }
 
  // For TCP sessions, check participant context
  // If we don't have a participant context yet, we're not connected
  if (!session->participant_ctx) {
    return ERROR_NETWORK;
  }
 
  // Check migration state - if we're already migrating, host is definitely not alive
  if (session->state == DISCOVERY_STATE_MIGRATING) {
    return ERROR_NETWORK; // Already detected disconnect
  }
 
  uint64_t now_ms = session_get_current_time_ms();
 
  if (session->liveness.ping_in_flight &&
      atomic_load_u64(&session->liveness.last_pong_received_ms) >= session->liveness.last_ping_sent_ms) {
    session->liveness.ping_in_flight = false;
    session->liveness.consecutive_failures = 0;
  }
  // Check if we have a ping in flight that timed out
  if (session->liveness.ping_in_flight) {
    uint64_t ping_age_ms = now_ms - session->liveness.last_ping_sent_ms;
    if (ping_age_ms > session->liveness.timeout_ms) {
      // Ping timed out
      session->liveness.consecutive_failures++;
      session->liveness.ping_in_flight = false;
      log_warn("Host ping timeout (attempt %u/%u, age=%llu ms)", session->liveness.consecutive_failures,
               session->liveness.max_failures, (unsigned long long)ping_age_ms);
 
      // Check if we've exceeded failure threshold
      if (session->liveness.consecutive_failures >= session->liveness.max_failures) {
        log_error("Host declared dead after %u consecutive ping failures", session->liveness.consecutive_failures);
        return ERROR_NETWORK;
      }
    }
  }
 
  // Check if it's time to send a new ping
  uint64_t time_since_last_ping = now_ms - session->liveness.last_ping_sent_ms;
  if (!session->liveness.ping_in_flight && time_since_last_ping >= session->liveness.ping_interval_ms) {
    // Send ping to host via participant connection
    acip_transport_t *transport = session_participant_get_transport(session->participant_ctx);
    if (!transport || !acip_transport_is_connected(transport))
      return SET_ERRNO(ERROR_NETWORK, "Host transport disconnected");
    asciichat_error_t result = acip_send_ping(transport);
    if (result == ASCIICHAT_OK) {
      session->liveness.last_ping_sent_ms = now_ms;
      session->liveness.ping_in_flight = true;
      log_debug("Sent ping to host (attempt %u/%u)", session->liveness.consecutive_failures + 1,
                session->liveness.max_failures);
    } else {
      log_warn("Failed to send ping to host: %d", result);
      session->liveness.consecutive_failures++;
      if (session->liveness.consecutive_failures >= session->liveness.max_failures) {
        log_error("Host declared dead after %u consecutive send failures", session->liveness.consecutive_failures);
        return ERROR_NETWORK;
      }
    }
  }
 
  return ASCIICHAT_OK;
}

References acip_send_ping(), ASCIICHAT_OK, host_liveness_t::consecutive_failures, DISCOVERY_STATE_MIGRATING, ERROR_NETWORK, discovery_session_t::is_host, host_liveness_t::last_ping_sent_ms, host_liveness_t::last_pong_received_ms, discovery_session_t::liveness, log_debug, log_error, log_warn, host_liveness_t::max_failures, discovery_session_t::participant_ctx, host_liveness_t::ping_in_flight, host_liveness_t::ping_interval_ms, session_participant_get_transport(), discovery_session_t::session_type, SESSION_TYPE_WEBRTC, SET_ERRNO, discovery_session_t::state, host_liveness_t::timeout_ms, and discovery_session_t::webrtc_transport_ready.

◆ discovery_session_create()

discovery_session_t * discovery_session_create ( const discovery_config_t * config )

Configuration for discovery session.

Create a new discovery session

Parameters

config Session configuration

Returns: New session or NULL on error

Definition at line 72 of file src/discovery/session.c.

                                                                                {
  if (!config) {
    SET_ERRNO(ERROR_INVALID_PARAM, "config is NULL");
    return NULL;
  }
 
  discovery_session_t *session = SAFE_CALLOC(1, sizeof(discovery_session_t), discovery_session_t *);
  if (!session) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate discovery session");
    return NULL;
  }
 
  session->state = DISCOVERY_STATE_INIT;
  session->handoff_generation = 1; // Match consensus_handoff_init().
  session->acds_transport = NULL;
  session->peer_manager = NULL;
  session->webrtc_transport_ready = false;
  session->webrtc_connection_initiated = false;
  session->webrtc_retry_attempt = 0;
  session->webrtc_last_attempt_time_ms = 0;
  session->webrtc_disconnected_since_ms = 0;
  session->stun_servers = NULL;
  session->stun_count = 0;
  session->turn_servers = NULL;
  session->turn_count = 0;
 
  // Initialize host liveness detection
  session->liveness.last_ping_sent_ms = 0;
  atomic_store_u64(&session->liveness.last_pong_received_ms, 0);
  session->liveness.consecutive_failures = 0;
  session->liveness.max_failures = 3;
  session->liveness.ping_interval_ms = 3 * MS_PER_SEC_INT; // Ping every 3 seconds
  session->liveness.timeout_ms = 10 * MS_PER_SEC_INT;      // 10 second timeout
  session->liveness.ping_in_flight = false;
 
  log_info("After CALLOC - participant_ctx=%p, host_ctx=%p", session->participant_ctx, session->host_ctx);
 
  // Explicit identity credentials apply to signaling as well as media authentication.
  const options_t *opts = options_get();
  bool explicit_identity = opts && opts->encrypt_key[0];
  char identity_path[DISCOVERY_SESSION_IDENTITY_PATH_BUFFER_SIZE];
  asciichat_error_t id_result;
  if (explicit_identity) {
    SAFE_STRNCPY(identity_path, opts->encrypt_key, sizeof(identity_path));
    id_result = ASCIICHAT_OK;
  } else {
    id_result = acds_identity_default_path(identity_path, sizeof(identity_path));
  }
  if (id_result == ASCIICHAT_OK) {
    asciichat_errno_scope_t load_scope = {0};
    bool suppressed = false;
    if (!explicit_identity) {
      load_scope = errno_scope_begin();
      suppressed = errno_notifications_suppress(true);
    }
    if (!explicit_identity && platform_access(identity_path, PLATFORM_ACCESS_EXISTS) != 0)
      id_result = ERROR_CONFIG;
    else
      id_result = acds_identity_load(identity_path, session->identity_pubkey, session->identity_seckey);
    if (!explicit_identity) {
      errno_notifications_suppress(suppressed);
      errno_scope_end(load_scope, ASCIICHAT_ERRNO_HANDLED);
    }
    if (id_result != ASCIICHAT_OK && !explicit_identity) {
      // File doesn't exist or is corrupted - generate new key
      log_info("Identity key not found, generating new key");
      id_result = acds_identity_generate(session->identity_pubkey, session->identity_seckey);
      if (id_result == ASCIICHAT_OK) {
        // Save for future use
        acds_identity_save(identity_path, session->identity_pubkey, session->identity_seckey);
      }
    }
  }
 
  if (id_result != ASCIICHAT_OK && explicit_identity) {
    SAFE_FREE(session);
    return NULL;
  }
  if (id_result != ASCIICHAT_OK) {
    NOTICE(DANGER, "DISCOVERY IDENTITY UNAVAILABLE", "Failed to load/generate identity key, using zero key");
    memset(session->identity_pubkey, 0, sizeof(session->identity_pubkey));
    memset(session->identity_seckey, 0, sizeof(session->identity_seckey));
  } else {
    char fingerprint[HEX_STRING_SIZE_32];
    acds_identity_fingerprint(session->identity_pubkey, fingerprint);
    log_info("Using identity key with fingerprint: %.16s...", fingerprint);
  }
 
  // Load multiple identity keys from options (multi-key protocol support)
  if (opts && opts->num_identity_keys > 0) {
    // Load all identity keys from options
    for (size_t i = 0; i < opts->num_identity_keys && i < MAX_SESSION_KEYS; i++) {
      uint8_t pubkey[ED25519_PUBLIC_KEY_SIZE] = {0};
      uint8_t seckey[ED25519_PRIVATE_KEY_SIZE] = {0};
      asciichat_error_t key_result = acds_identity_load(opts->identity_keys[i], pubkey, seckey);
      if (key_result == ASCIICHAT_OK) {
        memcpy(session->identity_pubkeys[session->num_identity_keys], pubkey, sizeof(pubkey));
        memcpy(session->identity_seckeys[session->num_identity_keys++], seckey, sizeof(seckey));
        sodium_memzero(seckey, sizeof(seckey));
        char fingerprint[HEX_STRING_SIZE_32];
        acds_identity_fingerprint(pubkey, fingerprint);
        log_info("Loaded identity key #%zu with fingerprint: %.16s...", i + 1, fingerprint);
      } else {
        log_warn("Failed to load identity key #%zu from %s", i + 1, opts->identity_keys[i]);
      }
    }
    if (session->num_identity_keys != opts->num_identity_keys) {
      sodium_memzero(session->identity_seckey, sizeof(session->identity_seckey));
      sodium_memzero(session->identity_seckeys, sizeof(session->identity_seckeys));
      SAFE_FREE(session);
      SET_ERRNO(ERROR_CRYPTO, "Could not load the complete discovery identity key set");
      return NULL;
    }
    memcpy(session->identity_pubkey, session->identity_pubkeys[0], sizeof(session->identity_pubkey));
    memcpy(session->identity_seckey, session->identity_seckeys[0], sizeof(session->identity_seckey));
    log_info("Loaded %zu identity key(s) for multi-key protocol", session->num_identity_keys);
  } else {
    // Single-key mode: use only the primary identity key
    memcpy(session->identity_pubkeys[0], session->identity_pubkey, ED25519_PUBLIC_KEY_SIZE);
    memcpy(session->identity_seckeys[0], session->identity_seckey, sizeof(session->identity_seckey));
    session->num_identity_keys = 1;
  }
 
  // ACDS connection info
  if (config->acds_url && config->acds_url[0]) {
    SAFE_STRNCPY(session->acds_url, config->acds_url, sizeof(session->acds_url));
  }
  if (config->acds_address && config->acds_address[0]) {
    SAFE_STRNCPY(session->acds_address, config->acds_address, sizeof(session->acds_address));
  } else {
    SAFE_STRNCPY(session->acds_address, "127.0.0.1", sizeof(session->acds_address));
  }
  session->acds_port = config->acds_port > 0 ? config->acds_port : ACIP_DISCOVERY_DEFAULT_PORT;
 
  // Session string (if joining)
  if (config->session_string && config->session_string[0]) {
    SAFE_STRNCPY(session->session_string, config->session_string, sizeof(session->session_string));
    session->is_initiator = false;
  } else {
    session->is_initiator = true;
  }
  if (config->password && config->password[0]) {
    SAFE_STRNCPY(session->password, config->password, sizeof(session->password));
  }
 
  // Callbacks
  session->on_state_change = config->on_state_change;
  session->on_session_ready = config->on_session_ready;
  session->on_error = config->on_error;
  session->callback_user_data = config->callback_user_data;
  session->should_exit_callback = config->should_exit_callback;
  session->exit_callback_data = config->exit_callback_data;
 
  // Initialize mutex for NAT quality protection
  if (mutex_init(&session->nat_quality_mutex, "discovery_nat_quality") != 0) {
    log_warn("Failed to initialize NAT quality mutex");
  }
 
  log_debug("Discovery session created (initiator=%d, acds=%s:%u)", session->is_initiator, session->acds_address,
            session->acds_port);
 
  NAMED_REGISTER_ATOMIC(&session->liveness.last_pong_received_ms, "discovery.last_pong_received_ms", NULL);
  return session;
}

Referenced by discovery_main().

◆ discovery_session_destroy()

asciichat_error_t discovery_session_destroy ( discovery_session_t * session )

Destroy discovery session and free resources.

Parameters

session Session to destroy

Definition at line 278 of file src/discovery/session.c.

                                                                          {
  ASCII_OTEL_SCOPE(DISCOVERY_SHUTDOWN);
  if (!session) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "session is NULL");
  }
 
  asciichat_error_t result = release_participant_transport(session);
  if (result != ASCIICHAT_OK)
    return result;
  // The detector borrows the session and mutex; retain both on a timed join failure.
  if (session->nat_detection_thread_started) {
    asciichat_error_t join_result = thread_join_timeout(&session->nat_detection_thread, NULL, 500 * NS_PER_MS_INT);
    if (join_result != ASCIICHAT_OK)
      return SET_ERRNO(ERROR_THREAD, "NAT detection worker still owns discovery session");
    session->nat_detection_thread_started = false;
  }
  release_host_control_transport(session);
 
  // Close ACDS connection
  if (session->acds_transport) {
    network_connection_destroy(&session->acds_connection);
    session->acds_transport = NULL;
  }
 
  // Destroy host context if active
  if (session->host_ctx) {
    asciichat_error_t result = session_host_destroy(session->host_ctx);
    if (result != ASCIICHAT_OK)
      return result;
    session->host_ctx = NULL;
  }
 
  // Destroy participant context if active
  if (session->participant_ctx) {
    session_participant_destroy(session->participant_ctx);
    session->participant_ctx = NULL;
  }
 
  // Clean up WebRTC peer manager (NEW)
  if (session->peer_manager) {
    webrtc_peer_manager_destroy(session->peer_manager);
    session->peer_manager = NULL;
  }
 
  // Clean up STUN/TURN server arrays (NEW)
  if (session->stun_servers) {
    SAFE_FREE(session->stun_servers);
    session->stun_servers = NULL;
    session->stun_count = 0;
  }
 
  if (session->turn_servers) {
    SAFE_FREE(session->turn_servers);
    session->turn_servers = NULL;
    session->turn_count = 0;
  }
 
  // Destroy NAT quality mutex
  mutex_destroy(&session->nat_quality_mutex);
 
  NAMED_UNREGISTER(&session->liveness.last_pong_received_ms);
  sodium_memzero(session->password, sizeof(session->password));
  sodium_memzero(session->identity_seckey, sizeof(session->identity_seckey));
  sodium_memzero(session->identity_seckeys, sizeof(session->identity_seckeys));
  SAFE_FREE(session);
  return ASCIICHAT_OK;
}

Referenced by discovery_main().

◆ discovery_session_get_host()

session_host_t * discovery_session_get_host ( discovery_session_t * session )

Get host context (if we are host).

Parameters

session Session context

Returns: Host context or NULL

Definition at line 2184 of file src/discovery/session.c.

                                                                         {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session");
    return NULL;
  }
  return session->host_ctx;
}

References ERROR_INVALID_PARAM, discovery_session_t::host_ctx, and SET_ERRNO.

◆ discovery_session_get_participant()

session_participant_t * discovery_session_get_participant ( discovery_session_t * session )

Get participant context (if we are participant).

Parameters

session Session context

Returns: Participant context or NULL

Definition at line 2192 of file src/discovery/session.c.

                                                                                       {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session");
    return NULL;
  }
  return session->participant_ctx;
}

References ERROR_INVALID_PARAM, discovery_session_t::participant_ctx, and SET_ERRNO.

◆ discovery_session_get_state()

discovery_state_t discovery_session_get_state ( const discovery_session_t * session )

Get current session state.

Parameters

session Session context

Returns: Current state

Definition at line 2152 of file src/discovery/session.c.

                                                                                  {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session");
    return DISCOVERY_STATE_FAILED;
  }
  return session->state;
}

References DISCOVERY_STATE_FAILED, ERROR_INVALID_PARAM, SET_ERRNO, and discovery_session_t::state.

◆ discovery_session_get_string()

const char * discovery_session_get_string ( const discovery_session_t * session )

Get session string.

Parameters

session Session context

Returns: Session string or NULL if not yet assigned

Definition at line 2168 of file src/discovery/session.c.

                                                                             {
  if (!session || session->session_string[0] == '\0') {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session or session string is empty");
    return NULL;
  }
  return session->session_string;
}

References ERROR_INVALID_PARAM, discovery_session_t::session_string, and SET_ERRNO.

◆ discovery_session_handle_host_disconnect()

asciichat_error_t discovery_session_handle_host_disconnect	(	discovery_session_t *	session,
		uint32_t	disconnect_reason )

Report host disconnect and await the ACDS recovery decision.

Parameters

session	Session context
disconnect_reason	Reason code for disconnect

Returns: ASCIICHAT_OK if the host loss report was sent

Report host disconnect and await the ACDS recovery decision.

Returns: ASCIICHAT_OK if the report was sent; a send error also fails the session.

Definition at line 2294 of file src/discovery/session.c.

                                                                                                                     {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "session is NULL");
    return ERROR_INVALID_PARAM;
  }
 
  log_warn("Host disconnect detected: reason=%u", disconnect_reason);
 
  session->host_loss_detected_ms = session_get_current_time_ms();
 
  // Notify ACDS of host loss (lightweight notification, no NAT data exchanged!)
  acip_host_lost_t host_lost = {0};
  memcpy(host_lost.session_id, session->session_id, SESSION_ID_SIZE);
  memcpy(host_lost.participant_id, session->participant_id, SESSION_ID_SIZE);
  memcpy(host_lost.last_host_id, session->host_id, SESSION_ID_SIZE);
  host_lost.disconnect_reason = disconnect_reason;
  host_lost.disconnect_time_ms = session->host_loss_detected_ms;
 
  asciichat_error_t result =
      packet_send_via_transport(session->acds_transport, PACKET_TYPE_ACIP_HOST_LOST, &host_lost, sizeof(host_lost), 0);
  if (result != ASCIICHAT_OK) {
    set_error(session, result, "Could not report host loss to ACDS");
    return result;
  }
 
  // A PLAN is advisory. Only ACDS COMMIT authorizes a role change after fresh
  // measurement and preparation. Continue dispatching while awaiting that decision.
  set_state(session, DISCOVERY_STATE_MIGRATING);
 
  return ASCIICHAT_OK;
}

References discovery_session_t::acds_transport, acip_host_lost_t, ASCIICHAT_OK, DISCOVERY_STATE_MIGRATING, ERROR_INVALID_PARAM, discovery_session_t::host_id, discovery_session_t::host_loss_detected_ms, log_warn, packet_send_via_transport(), PACKET_TYPE_ACIP_HOST_LOST, discovery_session_t::participant_id, discovery_session_t::session_id, SESSION_ID_SIZE, and SET_ERRNO.

◆ discovery_session_host_pong()

void discovery_session_host_pong ( discovery_session_t * session )

Record a host reply using the same clock as liveness deadlines.

Definition at line 2200 of file src/discovery/session.c.

                                                               {
  if (session)
    atomic_store_u64(&session->liveness.last_pong_received_ms, session_get_current_time_ms());
}

References host_liveness_t::last_pong_received_ms, and discovery_session_t::liveness.

◆ discovery_session_is_active()

bool discovery_session_is_active ( const discovery_session_t * session )

Check if session is active (call in progress).

Parameters

session Session context

Returns: True if active

Definition at line 2160 of file src/discovery/session.c.

                                                                     {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session");
    return false;
  }
  return session->state == DISCOVERY_STATE_ACTIVE;
}

References DISCOVERY_STATE_ACTIVE, ERROR_INVALID_PARAM, SET_ERRNO, and discovery_session_t::state.

◆ discovery_session_is_host()

bool discovery_session_is_host ( const discovery_session_t * session )

Check if we are the host.

Parameters

session Session context

Returns: True if we are hosting

Definition at line 2176 of file src/discovery/session.c.

                                                                   {
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null session");
    return false;
  }
  return session->is_host;
}

References ERROR_INVALID_PARAM, discovery_session_t::is_host, and SET_ERRNO.

◆ discovery_session_process()

asciichat_error_t discovery_session_process	(	discovery_session_t *	session,
		int64_t	timeout_ns )

Process session events (call in main loop).

Handles incoming ACDS messages, negotiation, and state transitions.

Parameters

session	Session context
timeout_ns	Max time to wait for events in nanoseconds (0 = non-blocking)

Returns: ASCIICHAT_OK on success, error on failure

Definition at line 2065 of file src/discovery/session.c.

                                                                                              {
  if (!session) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "session is NULL");
  }
 
  // Transport callbacks publish readiness; ownership changes and worker joins
  // execute here on the session's controlling thread.
  asciichat_error_t result = webrtc_peer_manager_dispatch_ready(session->peer_manager);
  if (result != ASCIICHAT_OK)
    return result;
 
  result = discovery_session_send_keepalive(session);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  if (session->state == DISCOVERY_STATE_ACTIVE || session->state == DISCOVERY_STATE_CONNECTING_HOST ||
      session->state == DISCOVERY_STATE_MIGRATING) {
    result = discovery_handoff_sample(session);
    if (result != ASCIICHAT_OK)
      return result;
  }
 
  // State handlers preserve deferred failures: recording a failed state does not
  // necessarily return an error until the next iteration processes that state.
  switch (session->state) {
  case DISCOVERY_STATE_WAITING_PEER:
    return discovery_session_wait_for_peer(session, timeout_ns);
  case DISCOVERY_STATE_NEGOTIATING:
    return discovery_session_negotiate(session);
  case DISCOVERY_STATE_STARTING_HOST:
    return discovery_session_start_host(session);
  case DISCOVERY_STATE_CONNECTING_HOST:
    return session->session_type == SESSION_TYPE_WEBRTC ? discovery_session_connect_webrtc(session)
                                                        : discovery_session_connect_tcp(session);
  case DISCOVERY_STATE_ACTIVE:
    return discovery_session_process_active(session, timeout_ns);
  case DISCOVERY_STATE_MIGRATING:
    return discovery_session_process_migration(session, timeout_ns);
  case DISCOVERY_STATE_FAILED:
    // Session has failed - return error on further processing
    return session->error != ASCIICHAT_OK ? session->error : ERROR_NETWORK;
 
  case DISCOVERY_STATE_ENDED:
    // Session has ended gracefully - return OK
    return ASCIICHAT_OK;
 
  case DISCOVERY_STATE_INIT:
  case DISCOVERY_STATE_CONNECTING_ACDS:
  case DISCOVERY_STATE_CREATING_SESSION:
  case DISCOVERY_STATE_JOINING_SESSION:
    // These states are handled during discovery_session_start(), not in the process loop
    // If we reach here, something went wrong - sleep and wait
    log_debug("State %d should be handled by discovery_session_start", session->state);
    platform_sleep_us(timeout_ns / 1000);
    break;
 
  default:
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid session state: %d", session->state);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, DISCOVERY_STATE_ACTIVE, DISCOVERY_STATE_CONNECTING_ACDS, DISCOVERY_STATE_CONNECTING_HOST, DISCOVERY_STATE_CREATING_SESSION, DISCOVERY_STATE_ENDED, DISCOVERY_STATE_FAILED, DISCOVERY_STATE_INIT, DISCOVERY_STATE_JOINING_SESSION, DISCOVERY_STATE_MIGRATING, DISCOVERY_STATE_NEGOTIATING, DISCOVERY_STATE_STARTING_HOST, DISCOVERY_STATE_WAITING_PEER, discovery_session_t::error, ERROR_INVALID_PARAM, ERROR_INVALID_STATE, ERROR_NETWORK, log_debug, discovery_session_t::peer_manager, discovery_session_t::session_type, SESSION_TYPE_WEBRTC, SET_ERRNO, discovery_session_t::state, and webrtc_peer_manager_dispatch_ready().

◆ discovery_session_start()

asciichat_error_t discovery_session_start ( discovery_session_t * session )

Start the discovery session.

Connects to ACDS and either creates or joins a session.

Parameters

session Session context

Returns: ASCIICHAT_OK on success

Definition at line 1489 of file src/discovery/session.c.

                                                                        {
  log_info("session=%p", session);
 
  if (!session) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "session is NULL");
  }
 
  log_info("is_initiator=%d, session_string='%s'", session->is_initiator, session->session_string);
 
  // Check if we should exit before starting blocking operations
  if (session->should_exit_callback && session->should_exit_callback(session->exit_callback_data)) {
    log_info("Exiting early due to should_exit_callback (before ACDS connect)");
    return ASCIICHAT_OK; // Return success to allow clean shutdown
  }
 
  log_info("Calling connect_to_acds...");
  // Connect to ACDS
  asciichat_error_t result = connect_to_acds(session);
  if (result != ASCIICHAT_OK) {
    log_error("connect_to_acds FAILED %s", asciichat_error_format(NULL, result));
    set_state(session, DISCOVERY_STATE_FAILED);
    return result;
  }
  log_info("connect_to_acds succeeded");
 
  // Check again after connection
  if (session->should_exit_callback && session->should_exit_callback(session->exit_callback_data)) {
    log_info("Exiting early due to should_exit_callback (after ACDS connect)");
    return ASCIICHAT_OK; // Return success to allow clean shutdown
  }
 
  session->acds_transport->receive_timeout_ns = 10 * NS_PER_SEC_INT;
 
  // Perform crypto handshake with ACDS (same as client-server handshake)
  log_info("Performing crypto handshake with ACDS...");
  crypto_handshake_context_t *handshake_ctx = network_connection_handshake(session->acds_connection);
 
  result = crypto_handshake_init("discovery_client", handshake_ctx, false);
  if (result != ASCIICHAT_OK) {
    log_error("Handshake init failed - %s", asciichat_error_format(NULL, result));
    set_error(session, result, "Crypto handshake init failed");
    return result;
  }
 
  bool has_identity = memcmp(session->identity_pubkey, (uint8_t[32]){0}, ED25519_PUBLIC_KEY_SIZE) != 0;
  // Store identity key in handshake context
  handshake_ctx->client_public_key.type = has_identity ? KEY_TYPE_ED25519 : KEY_TYPE_UNKNOWN;
  handshake_ctx->client_private_key.type = handshake_ctx->client_public_key.type;
  memcpy(handshake_ctx->client_public_key.key, session->identity_pubkey, ED25519_PUBLIC_KEY_SIZE);
  memcpy(handshake_ctx->client_private_key.key.ed25519, session->identity_seckey, ED25519_PRIVATE_KEY_SIZE);
  memcpy(handshake_ctx->client_private_key.public_key, session->identity_pubkey, sizeof(session->identity_pubkey));
 
  crypto_policy_t signaling_policy = {
      .transport_secure = strncmp(session->acds_url, "wss://", 6) == 0,
      .has_identity = has_identity,
  };
  uint8_t mode;
  result = crypto_policy_resolve(&signaling_policy, &mode);
  if (result == ASCIICHAT_OK)
    result = network_client_negotiate(session->acds_transport, handshake_ctx, mode, NETWORK_PROTOCOL_DISCOVERY);
  if (result != ASCIICHAT_OK) {
    set_error(session, result, "Discovery handshake failed");
    return result;
  }
 
  // Check again after handshake
  if (session->should_exit_callback && session->should_exit_callback(session->exit_callback_data)) {
    log_info("Exiting early due to should_exit_callback (after handshake)");
    return ASCIICHAT_OK; // Return success to allow clean shutdown
  }
 
  // Create or join session
  if (session->is_initiator) {
    log_info("Calling create_session - participant_ctx before=%p", session->participant_ctx);
    result = create_session(session);
    log_info("create_session returned - participant_ctx after=%p, result=%d", session->participant_ctx, result);
 
    if (result == ASCIICHAT_OK) {
      // Initiator also needs to register itself as a participant so it can receive PARTICIPANT_JOINED notifications
      // when other peers join. This makes the initiator discoverable to other participants.
      log_info("Initiator: now registering self as participant in created session");
      result = join_session(session);
      log_info("Initiator: join_session result=%d", result);
    }
    return result;
  } else {
    log_info("Calling join_session - participant_ctx before=%p", session->participant_ctx);
    asciichat_error_t result = join_session(session);
    log_info("join_session returned - participant_ctx after=%p, state=%d, result=%d", session->participant_ctx,
             session->state, result);
    return result;
  }
}

◆ discovery_session_stop()

void discovery_session_stop ( discovery_session_t * session )

Stop the discovery session.

Parameters

session Session context

Definition at line 2129 of file src/discovery/session.c.

                                                          {
  ASCII_OTEL_SCOPE(DISCOVERY_SHUTDOWN);
  if (!session) {
    SET_ERRNO(ERROR_INVALID_PARAM, "session is NULL");
    return;
  }
 
  log_info("Stopping discovery session...");
 
  // Send SESSION_LEAVE if connected
  if (session->acds_transport && session->session_id[0] != 0) {
    acip_session_leave_t leave_msg;
    memset(&leave_msg, 0, sizeof(leave_msg));
    memcpy(leave_msg.session_id, session->session_id, SESSION_ID_SIZE);
    memcpy(leave_msg.participant_id, session->participant_id, SESSION_ID_SIZE);
 
    packet_send_via_transport(session->acds_transport, PACKET_TYPE_ACIP_SESSION_LEAVE, &leave_msg, sizeof(leave_msg),
                              0);
  }
 
  set_state(session, DISCOVERY_STATE_ENDED);
}

References discovery_session_t::acds_transport, acip_session_leave_t, ASCII_OTEL_SCOPE, DISCOVERY_STATE_ENDED, ERROR_INVALID_PARAM, log_info, packet_send_via_transport(), PACKET_TYPE_ACIP_SESSION_LEAVE, discovery_session_t::participant_id, discovery_session_t::session_id, SESSION_ID_SIZE, and SET_ERRNO.

Referenced by discovery_main().

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ DISCOVERY_SESSION_ACDS_ADDRESS_BUFFER_SIZE

◆ DISCOVERY_SESSION_ACDS_URL_BUFFER_SIZE

Typedef Documentation

◆ discovery_should_exit_fn

Enumeration Type Documentation

◆ discovery_state_t

Function Documentation

◆ discovery_session_apply_handoff()

◆ discovery_session_check_host_alive()

◆ discovery_session_create()

◆ discovery_session_destroy()

◆ discovery_session_get_host()

◆ discovery_session_get_participant()

◆ discovery_session_get_state()

◆ discovery_session_get_string()

◆ discovery_session_handle_host_disconnect()

◆ discovery_session_host_pong()

◆ discovery_session_is_active()

◆ discovery_session_is_host()

◆ discovery_session_process()

◆ discovery_session_start()

◆ discovery_session_stop()