negotiate.h File Reference

Host negotiation logic for discovery mode. More...

Go to the source code of this file.

Data Structures
struct	negotiate_ctx_t
	Host negotiation context. More...

Enumerations
enum	negotiate_state_t {   NEGOTIATE_STATE_INIT , NEGOTIATE_STATE_DETECTING_NAT , NEGOTIATE_STATE_WAITING_PEER , NEGOTIATE_STATE_COMPARING ,   NEGOTIATE_STATE_WE_HOST , NEGOTIATE_STATE_THEY_HOST , NEGOTIATE_STATE_FAILED , NEGOTIATE_STATE_COMPLETE }
	Negotiation state. More...

Functions
void	negotiate_init (negotiate_ctx_t *ctx, const uint8_t session_id[16], const uint8_t participant_id[16], bool is_initiator)
	Initialize negotiation context.
asciichat_error_t	negotiate_start_detection (negotiate_ctx_t *ctx, const char *stun_server, uint16_t local_port)
	Start NAT detection phase.
asciichat_error_t	negotiate_receive_peer_quality (negotiate_ctx_t *ctx, const acip_nat_quality_t *peer_quality)
	Process received peer NAT quality.
asciichat_error_t	negotiate_determine_result (negotiate_ctx_t *ctx)
	Determine negotiation result.
negotiate_state_t	negotiate_get_state (const negotiate_ctx_t *ctx)
	Get current negotiation state.
bool	negotiate_is_complete (const negotiate_ctx_t *ctx)
	Check if negotiation is complete.
asciichat_error_t	negotiate_get_error (const negotiate_ctx_t *ctx)
	Get negotiation error (if failed)
asciichat_error_t	negotiate_elect_future_host (const acip_nat_quality_t collected_quality[], const uint8_t participant_ids[][16], size_t num_participants, uint8_t out_future_host_id[16])
	Elect future host from multiple participants (NEW P2P design)

Detailed Description

Host negotiation logic for discovery mode.

Implements the host negotiation protocol where participants exchange NAT quality information and determine who should become the host.

Definition in file negotiate.h.

Enumeration Type Documentation

negotiate_state_t

enum negotiate_state_t

Negotiation state.

Enumerator
NEGOTIATE_STATE_INIT	Initial state.
NEGOTIATE_STATE_DETECTING_NAT	Running NAT detection.
NEGOTIATE_STATE_WAITING_PEER	Waiting for peer's NAT quality.
NEGOTIATE_STATE_COMPARING	Comparing qualities.
NEGOTIATE_STATE_WE_HOST	We won, becoming host.
NEGOTIATE_STATE_THEY_HOST	They won, connecting as client.
NEGOTIATE_STATE_FAILED	Negotiation failed.
NEGOTIATE_STATE_COMPLETE	Negotiation complete.

Definition at line 26 of file negotiate.h.

             {
  NEGOTIATE_STATE_INIT,          
  NEGOTIATE_STATE_DETECTING_NAT, 
  NEGOTIATE_STATE_WAITING_PEER,  
  NEGOTIATE_STATE_COMPARING,     
  NEGOTIATE_STATE_WE_HOST,       
  NEGOTIATE_STATE_THEY_HOST,     
  NEGOTIATE_STATE_FAILED,        
  NEGOTIATE_STATE_COMPLETE       
} negotiate_state_t;

Function Documentation

negotiate_determine_result()

asciichat_error_t negotiate_determine_result

(

negotiate_ctx_t *

ctx

)

Determine negotiation result.

Called after both parties have exchanged NAT quality. Sets we_are_host and related fields.

Parameters

ctx	Negotiation context

Returns

ASCIICHAT_OK on success

Definition at line 111 of file negotiate.c.

                                                                   {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ctx is NULL");
  }
 
  if (!ctx->our_quality.detection_complete || !ctx->peer_quality_received) {
    return SET_ERRNO(ERROR_INVALID_STATE, "Cannot determine result: detection incomplete");
  }
 
  ctx->state = NEGOTIATE_STATE_COMPARING;
 
  // Compare NAT qualities
  int result = nat_compare_quality(&ctx->our_quality, &ctx->peer_quality, ctx->is_initiator);
 
  if (result <= 0) {
    // We should host
    ctx->we_are_host = true;
    ctx->state = NEGOTIATE_STATE_WE_HOST;
 
    // Set our address as host address
    if (ctx->our_quality.public_address[0]) {
      SAFE_STRNCPY(ctx->host_address, ctx->our_quality.public_address, sizeof(ctx->host_address));
    } else {
      // Fall back to localhost for testing
      SAFE_STRNCPY(ctx->host_address, "127.0.0.1", sizeof(ctx->host_address));
    }
 
    ctx->host_port = ctx->our_quality.upnp_available ? ctx->our_quality.upnp_mapped_port : ACIP_HOST_DEFAULT_PORT;
    ctx->connection_type = determine_connection_type(&ctx->our_quality);
 
    log_info("Negotiation result: WE ARE HOST (addr=%s:%u, type=%d)", ctx->host_address, ctx->host_port,
             ctx->connection_type);
  } else {
    // They should host
    ctx->we_are_host = false;
    ctx->state = NEGOTIATE_STATE_THEY_HOST;
 
    // Set peer address as host address
    if (ctx->peer_quality.public_address[0]) {
      SAFE_STRNCPY(ctx->host_address, ctx->peer_quality.public_address, sizeof(ctx->host_address));
    }
 
    ctx->host_port = ctx->peer_quality.upnp_available ? ctx->peer_quality.upnp_mapped_port : ACIP_HOST_DEFAULT_PORT;
    ctx->connection_type = determine_connection_type(&ctx->peer_quality);
 
    log_info("Negotiation result: THEY ARE HOST (addr=%s:%u, type=%d)", ctx->host_address, ctx->host_port,
             ctx->connection_type);
  }
 
  ctx->state = NEGOTIATE_STATE_COMPLETE;
  return ASCIICHAT_OK;
}

References negotiate_ctx_t::connection_type, nat_quality_t::detection_complete, negotiate_ctx_t::host_address, negotiate_ctx_t::host_port, negotiate_ctx_t::is_initiator, nat_compare_quality(), NEGOTIATE_STATE_COMPARING, NEGOTIATE_STATE_COMPLETE, NEGOTIATE_STATE_THEY_HOST, NEGOTIATE_STATE_WE_HOST, negotiate_ctx_t::our_quality, negotiate_ctx_t::peer_quality, negotiate_ctx_t::peer_quality_received, nat_quality_t::public_address, negotiate_ctx_t::state, nat_quality_t::upnp_available, nat_quality_t::upnp_mapped_port, and negotiate_ctx_t::we_are_host.

Referenced by discovery_session_process(), negotiate_receive_peer_quality(), and negotiate_start_detection().

negotiate_elect_future_host()

asciichat_error_t negotiate_elect_future_host	(	const acip_nat_quality_t	collected_quality[],
		const uint8_t	participant_ids[][16],
		size_t	num_participants,
		uint8_t	out_future_host_id[16]
	)

Elect future host from multiple participants (NEW P2P design)

Called by quorum leader after collecting NAT quality from all participants. Determines who should become host if current host dies. Uses deterministic algorithm so all participants independently reach same result.

Parameters

collected_quality	Array of NAT quality from all participants
participant_ids	Array of participant IDs (in same order as quality array)
num_participants	Number of participants
out_future_host_id	Output: Elected future host's participant ID

Returns

ASCIICHAT_OK on success

Note

All participants compute this independently on their own collected data and reach the same result (deterministic algorithm).

If only one participant remains, that one is elected.

If all have same quality, uses participant ID lexicographic order as tiebreaker.

Definition at line 182 of file negotiate.c.

                                                                              {
  if (!collected_quality || !participant_ids || !out_future_host_id) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
    return ERROR_INVALID_PARAM;
  }
 
  if (num_participants == 0 || num_participants > MAX_PARTICIPANTS) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid participant count");
    return ERROR_INVALID_PARAM;
  }
 
  // Special case: only one participant
  if (num_participants == 1) {
    memcpy(out_future_host_id, participant_ids[0], 16);
    log_info("Only one participant, electing as future host");
    return ASCIICHAT_OK;
  }
 
  // Convert all acip_nat_quality_t to nat_quality_t for comparison
  nat_quality_t qualities[MAX_PARTICIPANTS];
  for (size_t i = 0; i < num_participants; i++) {
    nat_quality_from_acip(&collected_quality[i], &qualities[i]);
  }
 
  // Find the best candidate by comparing all pairs
  // Winner is the one who "wins" most comparisons
  size_t best_idx = 0;
  int best_wins = 0;
 
  for (size_t i = 0; i < num_participants; i++) {
    int wins = 0;
 
    // Compare against all others
    for (size_t j = 0; j < num_participants; j++) {
      if (i == j)
        continue;
 
      // Compare: -1 means i wins, 1 means j wins, 0 means tie
      // Note: we_are_initiator parameter doesn't matter for multiparty comparison
      // We use false consistently for deterministic results
      int result = nat_compare_quality(&qualities[i], &qualities[j], false);
 
      if (result <= 0) {
        wins++; // i wins or tie
      }
    }
 
    // Select as winner if has more wins than current best
    // In case of tie, lexicographically smaller participant_id wins (as tiebreaker)
    if (wins > best_wins || (wins == best_wins && memcmp(participant_ids[i], participant_ids[best_idx], 16) < 0)) {
      best_wins = wins;
      best_idx = i;
    }
  }
 
  // Copy elected host ID
  memcpy(out_future_host_id, participant_ids[best_idx], 16);
 
  log_info("Future host elected (participant index %zu with %d wins)", best_idx, best_wins);
  return ASCIICHAT_OK;
}

References MAX_PARTICIPANTS, nat_compare_quality(), and nat_quality_from_acip().

negotiate_get_error()

asciichat_error_t negotiate_get_error

(

const negotiate_ctx_t *

ctx

)

Get negotiation error (if failed)

Parameters

ctx	Negotiation context

Returns

Error code or ASCIICHAT_OK if no error

Definition at line 176 of file negotiate.c.

                                                                  {
  if (!ctx)
    return ERROR_INVALID_PARAM;
  return ctx->error;
}

References negotiate_ctx_t::error.

negotiate_get_state()

negotiate_state_t negotiate_get_state

(

const negotiate_ctx_t *

ctx

)

Get current negotiation state.

Parameters

ctx	Negotiation context

Returns

Current state

Definition at line 164 of file negotiate.c.

                                                                  {
  if (!ctx)
    return NEGOTIATE_STATE_FAILED;
  return ctx->state;
}

References NEGOTIATE_STATE_FAILED, and negotiate_ctx_t::state.

negotiate_init()

void negotiate_init	(	negotiate_ctx_t *	ctx,
		const uint8_t	session_id[16],
		const uint8_t	participant_id[16],
		bool	is_initiator
	)

Initialize negotiation context.

Parameters

ctx	Context to initialize
session_id	Session UUID
participant_id	Our participant UUID
is_initiator	True if we created the session

Definition at line 17 of file negotiate.c.

                                       {
  if (!ctx)
    return;
 
  memset(ctx, 0, sizeof(negotiate_ctx_t));
 
  if (session_id)
    memcpy(ctx->session_id, session_id, 16);
  if (participant_id)
    memcpy(ctx->participant_id, participant_id, 16);
 
  ctx->is_initiator = is_initiator;
  ctx->state = NEGOTIATE_STATE_INIT;
  ctx->peer_quality_received = false;
  ctx->we_are_host = false;
 
  nat_quality_init(&ctx->our_quality);
  nat_quality_init(&ctx->peer_quality);
 
  log_debug("Negotiation initialized (initiator=%d)", is_initiator);
}

References negotiate_ctx_t::is_initiator, nat_quality_init(), NEGOTIATE_STATE_INIT, negotiate_ctx_t::our_quality, participant_id, negotiate_ctx_t::participant_id, negotiate_ctx_t::peer_quality, negotiate_ctx_t::peer_quality_received, session_id, negotiate_ctx_t::session_id, negotiate_ctx_t::state, and negotiate_ctx_t::we_are_host.

Referenced by discovery_session_process().

negotiate_is_complete()

bool negotiate_is_complete

(

const negotiate_ctx_t *

ctx

)

Check if negotiation is complete.

Parameters

ctx	Negotiation context

Returns

True if negotiation finished (success or failure)

Definition at line 170 of file negotiate.c.

                                                       {
  if (!ctx)
    return true;
  return ctx->state == NEGOTIATE_STATE_COMPLETE || ctx->state == NEGOTIATE_STATE_FAILED;
}

References NEGOTIATE_STATE_COMPLETE, NEGOTIATE_STATE_FAILED, and negotiate_ctx_t::state.

negotiate_receive_peer_quality()

asciichat_error_t negotiate_receive_peer_quality	(	negotiate_ctx_t *	ctx,
		const acip_nat_quality_t *	peer_quality
	)

Process received peer NAT quality.

Parameters

ctx	Negotiation context
peer_quality	Peer's NAT quality from network

Returns

ASCIICHAT_OK on success

Definition at line 67 of file negotiate.c.

                                                                                                               {
  if (!ctx || !peer_quality) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ctx or peer_quality is NULL");
  }
 
  nat_quality_from_acip(peer_quality, &ctx->peer_quality);
  ctx->peer_quality_received = true;
 
  log_info("Received peer NAT quality: tier=%d, upload=%u kbps", nat_compute_tier(&ctx->peer_quality),
           ctx->peer_quality.upload_kbps);
 
  // If our detection is complete, we can determine result
  if (ctx->our_quality.detection_complete) {
    ctx->state = NEGOTIATE_STATE_COMPARING;
    return negotiate_determine_result(ctx);
  }
 
  // Otherwise, keep waiting for our detection to complete
  return ASCIICHAT_OK;
}

References nat_quality_t::detection_complete, nat_compute_tier(), nat_quality_from_acip(), negotiate_determine_result(), NEGOTIATE_STATE_COMPARING, negotiate_ctx_t::our_quality, negotiate_ctx_t::peer_quality, negotiate_ctx_t::peer_quality_received, negotiate_ctx_t::state, and nat_quality_t::upload_kbps.

negotiate_start_detection()

asciichat_error_t negotiate_start_detection	(	negotiate_ctx_t *	ctx,
		const char *	stun_server,
		uint16_t	local_port
	)

Start NAT detection phase.

Parameters

ctx	Negotiation context
stun_server	STUN server URL
local_port	Local port for detection

Returns

ASCIICHAT_OK on success

Definition at line 40 of file negotiate.c.

                                                                                                                {
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "ctx is NULL");
  }
 
  ctx->state = NEGOTIATE_STATE_DETECTING_NAT;
  log_info("Starting NAT detection for host negotiation...");
 
  asciichat_error_t result = nat_detect_quality(&ctx->our_quality, stun_server, local_port);
  if (result != ASCIICHAT_OK) {
    ctx->state = NEGOTIATE_STATE_FAILED;
    ctx->error = result;
    log_error("NAT detection failed");
    return result;
  }
 
  // If we already have peer quality, we can determine result
  if (ctx->peer_quality_received) {
    ctx->state = NEGOTIATE_STATE_COMPARING;
    return negotiate_determine_result(ctx);
  }
 
  ctx->state = NEGOTIATE_STATE_WAITING_PEER;
  log_info("NAT detection complete, waiting for peer quality...");
  return ASCIICHAT_OK;
}

References negotiate_ctx_t::error, nat_detect_quality(), negotiate_determine_result(), NEGOTIATE_STATE_COMPARING, NEGOTIATE_STATE_DETECTING_NAT, NEGOTIATE_STATE_FAILED, NEGOTIATE_STATE_WAITING_PEER, negotiate_ctx_t::our_quality, negotiate_ctx_t::peer_quality_received, and negotiate_ctx_t::state.