nat.h File Reference

NAT quality detection for discovery mode host selection. More...

Go to the source code of this file.

Data Structures
struct	nat_quality_t
	NAT quality assessment result. More...

Functions
void	nat_quality_init (nat_quality_t *quality)
	Initialize NAT quality structure with defaults.
asciichat_error_t	nat_detect_quality (nat_quality_t *quality, const char *stun_server, uint16_t local_port)
	Detect NAT quality using all available methods.
asciichat_error_t	nat_measure_bandwidth (nat_quality_t *quality, socket_t acds_socket)
	Measure upload bandwidth to ACDS server.
int	nat_compare_quality (const nat_quality_t *ours, const nat_quality_t *theirs, bool we_are_initiator)
	Compare two NAT qualities and determine who should host.
void	nat_quality_to_acip (const nat_quality_t *quality, const uint8_t session_id[16], const uint8_t participant_id[16], acip_nat_quality_t *out)
	Convert nat_quality_t to acip_nat_quality_t for network transmission.
void	nat_quality_from_acip (const acip_nat_quality_t *acip, nat_quality_t *out)
	Convert acip_nat_quality_t to nat_quality_t.
const char *	nat_type_to_string (acip_nat_type_t type)
	Get human-readable description of NAT type.
int	nat_compute_tier (const nat_quality_t *quality)
	Compute NAT tier for host selection (0=best, 4=worst)

Detailed Description

NAT quality detection for discovery mode host selection.

Detects NAT characteristics to determine the best host candidate. Uses STUN, UPnP/NAT-PMP, and bandwidth measurements.

Definition in file nat.h.

Function Documentation

nat_compare_quality()

int nat_compare_quality	(	const nat_quality_t *	ours,
		const nat_quality_t *	theirs,
		bool	we_are_initiator
	)

Compare two NAT qualities and determine who should host.

Algorithm is deterministic - both sides get the same result. Uses NAT tier priority with bandwidth as tiebreaker.

Parameters

ours	Our NAT quality
theirs	Peer's NAT quality
we_are_initiator	True if we started the session

Returns

-1 = we host, 0 = equal (initiator wins), 1 = they host

Definition at line 54 of file nat.c.

                                                                                                       {
  if (!ours || !theirs) {
    return we_are_initiator ? -1 : 1;
  }
 
  int our_tier = nat_compute_tier(ours);
  int their_tier = nat_compute_tier(theirs);
 
  // Check for bandwidth override: massive bandwidth advantage can override NAT tier
  if (ours->upload_kbps > 0 && theirs->upload_kbps > 0) {
    if (ours->upload_kbps >= theirs->upload_kbps * BANDWIDTH_OVERRIDE_RATIO) {
      log_debug("NAT compare: we win by bandwidth override (%u vs %u kbps)", ours->upload_kbps, theirs->upload_kbps);
      return -1;
    }
    if (theirs->upload_kbps >= ours->upload_kbps * BANDWIDTH_OVERRIDE_RATIO) {
      log_debug("NAT compare: they win by bandwidth override (%u vs %u kbps)", theirs->upload_kbps, ours->upload_kbps);
      return 1;
    }
  }
 
  // Compare NAT tiers (lower = better)
  if (our_tier < their_tier) {
    log_debug("NAT compare: we win by tier (%d vs %d)", our_tier, their_tier);
    return -1;
  }
  if (our_tier > their_tier) {
    log_debug("NAT compare: they win by tier (%d vs %d)", our_tier, their_tier);
    return 1;
  }
 
  // Same tier - bandwidth is tiebreaker
  if (ours->upload_kbps > theirs->upload_kbps) {
    log_debug("NAT compare: we win by bandwidth (%u vs %u kbps)", ours->upload_kbps, theirs->upload_kbps);
    return -1;
  }
  if (ours->upload_kbps < theirs->upload_kbps) {
    log_debug("NAT compare: they win by bandwidth (%u vs %u kbps)", theirs->upload_kbps, ours->upload_kbps);
    return 1;
  }
 
  // Same bandwidth - latency is tiebreaker
  if (ours->rtt_to_acds_ns < theirs->rtt_to_acds_ns) {
    log_debug("NAT compare: we win by latency (%lu ns vs %lu ns)", ours->rtt_to_acds_ns, theirs->rtt_to_acds_ns);
    return -1;
  }
  if (ours->rtt_to_acds_ns > theirs->rtt_to_acds_ns) {
    log_debug("NAT compare: they win by latency (%lu ns vs %lu ns)", theirs->rtt_to_acds_ns, ours->rtt_to_acds_ns);
    return 1;
  }
 
  // Everything equal - initiator hosts
  log_debug("NAT compare: equal quality, initiator wins (we_are_initiator=%d)", we_are_initiator);
  return we_are_initiator ? -1 : 1;
}

References BANDWIDTH_OVERRIDE_RATIO, log_debug, nat_compute_tier(), nat_quality_t::rtt_to_acds_ns, and nat_quality_t::upload_kbps.

Referenced by negotiate_determine_result(), and negotiate_elect_future_host().

nat_compute_tier()

int nat_compute_tier

(

const nat_quality_t *

quality

)

Compute NAT tier for host selection (0=best, 4=worst)

Parameters

quality

NAT quality

Returns

Tier value

Definition at line 39 of file nat.c.

                                                   {
  if (!quality)
    return 4;
 
  if (quality->lan_reachable)
    return 0; // LAN - best
  if (quality->has_public_ip)
    return 1; // Public IP
  if (quality->upnp_available)
    return 2; // UPnP mapping
  if (quality->nat_type <= ACIP_NAT_TYPE_RESTRICTED)
    return 3; // STUN hole-punchable
  return 4;   // TURN relay required
}

References ACIP_NAT_TYPE_RESTRICTED, nat_quality_t::has_public_ip, nat_quality_t::lan_reachable, nat_quality_t::nat_type, and nat_quality_t::upnp_available.

Referenced by __attribute__(), discovery_session_process(), nat_compare_quality(), nat_detect_quality(), and negotiate_receive_peer_quality().

nat_detect_quality()

asciichat_error_t nat_detect_quality	(	nat_quality_t *	quality,
		const char *	stun_server,
		uint16_t	local_port
	)

Detect NAT quality using all available methods.

Runs STUN probe, UPnP check, and gathers ICE candidates in parallel. Results are stored in the provided nat_quality_t structure.

Parameters

quality	Output structure for results
stun_server	STUN server URL (e.g., "stun:stun.l.google.com:19302")
local_port	Local port to use for detection

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 293 of file nat.c.

                                                                                                           {
  if (!quality) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "quality is NULL");
  }
 
  nat_quality_init(quality);
  log_info("Starting NAT quality detection (local_port=%u)", local_port);
 
  // Try UPnP/NAT-PMP first
  nat_upnp_context_t *upnp = NULL;
  asciichat_error_t upnp_result = nat_upnp_open(local_port, "ascii-chat", &upnp);
  if (upnp_result == ASCIICHAT_OK && upnp && nat_upnp_is_active(upnp)) {
    quality->upnp_available = true;
    quality->upnp_mapped_port = upnp->mapped_port;
 
    char addr_buf[64];
    if (nat_upnp_get_address(upnp, addr_buf, sizeof(addr_buf)) == ASCIICHAT_OK) {
      // Parse IP:port
      char *colon = strchr(addr_buf, ':');
      if (colon) {
        size_t ip_len = (size_t)(colon - addr_buf);
        if (ip_len < sizeof(quality->public_address)) {
          memcpy(quality->public_address, addr_buf, ip_len);
          quality->public_address[ip_len] = '\0';
        }
      } else {
        SAFE_STRNCPY(quality->public_address, addr_buf, sizeof(quality->public_address));
      }
    }
 
    log_info("UPnP: mapped port %u, external IP %s", quality->upnp_mapped_port, quality->public_address);
    quality->nat_type = ACIP_NAT_TYPE_FULL_CONE; // UPnP implies at least full-cone equivalent
  } else {
    log_debug("UPnP: not available or mapping failed");
  }
 
  // Try STUN probe if provided and UPnP didn't succeed
  if (!quality->upnp_available && stun_server && stun_server[0]) {
    asciichat_error_t stun_result = nat_stun_probe(quality, stun_server, local_port);
    if (stun_result == ASCIICHAT_OK) {
      // Successfully got reflexive address via STUN
      quality->has_srflx_candidates = true;
 
      // If reflexive address is not private range, we have public IP
      // Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
      if (quality->public_address[0] && strncmp(quality->public_address, "10.", 3) != 0 &&
          strncmp(quality->public_address, "172.16.", 7) != 0 && strncmp(quality->public_address, "192.168.", 8) != 0) {
        quality->has_public_ip = true;
        quality->nat_type = ACIP_NAT_TYPE_OPEN;
      } else {
        // Reflexive address is still private - behind symmetric NAT
        quality->nat_type = ACIP_NAT_TYPE_SYMMETRIC;
      }
    } else {
      log_debug("STUN probe failed, falling back to symmetric NAT assumption");
    }
  }
 
  // Set ICE candidate flags based on what we found
  quality->has_host_candidates = true; // We always have local IP
  quality->has_srflx_candidates = quality->upnp_available || quality->has_public_ip || quality->has_srflx_candidates;
 
  // Check if TURN relay servers are available (configured via options or ACDS)
  const options_t *opts = options_get();
  const char *turn_servers = opts ? opts->turn_servers : NULL;
  quality->has_relay_candidates = (turn_servers && turn_servers[0] != '\0');
  if (quality->has_relay_candidates) {
    log_debug("TURN relay servers configured: %s", turn_servers);
  }
 
  quality->detection_complete = true;
  log_info("NAT detection complete: tier=%d, upnp=%d, has_public_ip=%d, nat_type=%s", nat_compute_tier(quality),
           quality->upnp_available, quality->has_public_ip, nat_type_to_string(quality->nat_type));
 
  if (upnp) {
    // Keep UPnP mapping active for the session
    // Don't close it here - caller is responsible for cleanup
  }
 
  return ASCIICHAT_OK;
}

References ACIP_NAT_TYPE_FULL_CONE, ACIP_NAT_TYPE_OPEN, ACIP_NAT_TYPE_SYMMETRIC, ASCIICHAT_OK, nat_quality_t::detection_complete, ERROR_INVALID_PARAM, nat_quality_t::has_host_candidates, nat_quality_t::has_public_ip, nat_quality_t::has_relay_candidates, nat_quality_t::has_srflx_candidates, log_debug, log_info, nat_upnp_context::mapped_port, nat_compute_tier(), nat_quality_init(), nat_quality_t::nat_type, nat_type_to_string(), nat_upnp_get_address(), nat_upnp_is_active(), nat_upnp_open(), options_get(), nat_quality_t::public_address, SAFE_STRNCPY, SET_ERRNO, options_state::turn_servers, nat_quality_t::upnp_available, and nat_quality_t::upnp_mapped_port.

Referenced by negotiate_start_detection().

nat_measure_bandwidth()

asciichat_error_t nat_measure_bandwidth	(	nat_quality_t *	quality,
		socket_t	acds_socket
	)

Measure upload bandwidth to ACDS server.

Uploads a test payload and measures throughput.

Parameters

quality	Structure to update with bandwidth results
acds_socket	Connected socket to ACDS

Returns

ASCIICHAT_OK on success, error code on failure

Definition at line 375 of file nat.c.

                                                                                      {
  if (!quality) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "quality is NULL");
  }
  if (acds_socket == INVALID_SOCKET_VALUE) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "invalid socket");
  }
 
  // Prepare bandwidth test packet
  acip_bandwidth_test_t test_msg = {0};
  memset(test_msg.session_id, 0, sizeof(test_msg.session_id)); // Anonymous test
  memset(test_msg.participant_id, 0, sizeof(test_msg.participant_id));
  test_msg.test_size_bytes = 65536; // 64KB test payload
  test_msg.client_send_time_ns = time_get_ns();
 
  // Send BANDWIDTH_TEST packet
  asciichat_error_t result = packet_send(acds_socket, PACKET_TYPE_ACIP_BANDWIDTH_TEST, &test_msg, sizeof(test_msg));
  if (result != ASCIICHAT_OK) {
    log_warn("Failed to send bandwidth test packet");
    return result;
  }
 
  // Send test payload (64KB of data)
  uint8_t *test_data = SAFE_MALLOC(test_msg.test_size_bytes, uint8_t *);
  if (!test_data) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate bandwidth test payload");
  }
  memset(test_data, 0xAA, test_msg.test_size_bytes); // Fill with pattern
 
  ssize_t sent = send(acds_socket, (const char *)test_data, test_msg.test_size_bytes, 0);
  SAFE_FREE(test_data);
 
  if (sent != (ssize_t)test_msg.test_size_bytes) {
    log_warn("Failed to send bandwidth test payload: sent=%zd, expected=%u", sent, test_msg.test_size_bytes);
    return SET_ERRNO(ERROR_NETWORK, "Bandwidth test payload send failed");
  }
 
  log_debug("Sent bandwidth test with %u bytes", test_msg.test_size_bytes);
 
  // Set socket timeout for response (5 seconds)
  if (socket_set_timeout(acds_socket, 5 * NS_PER_SEC_INT) != 0) {
    log_warn("Failed to set socket timeout for bandwidth test");
    return SET_ERRNO(ERROR_NETWORK, "Failed to set socket timeout");
  }
 
  // Wait for BANDWIDTH_RESULT response
  packet_type_t response_type;
  void *response_data = NULL;
  size_t response_len = 0;
 
  result = packet_receive(acds_socket, &response_type, &response_data, &response_len);
 
  if (result != ASCIICHAT_OK) {
    log_warn("Bandwidth test timeout or receive failed");
    return SET_ERRNO(ERROR_NETWORK_TIMEOUT, "No bandwidth test response from ACDS");
  }
 
  if (response_type != PACKET_TYPE_ACIP_BANDWIDTH_RESULT) {
    POOL_FREE(response_data, response_len);
    log_warn("Unexpected packet type %d (expected BANDWIDTH_RESULT)", response_type);
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Wrong packet type in bandwidth test response");
  }
 
  if (response_len != sizeof(acip_bandwidth_result_t)) {
    POOL_FREE(response_data, response_len);
    return SET_ERRNO(ERROR_NETWORK_PROTOCOL, "Invalid bandwidth result size");
  }
 
  // Parse results
  acip_bandwidth_result_t *results = (acip_bandwidth_result_t *)response_data;
  quality->upload_kbps = results->measured_upload_kbps;
  quality->download_kbps = results->measured_download_kbps;
  quality->rtt_to_acds_ns = results->rtt_ns;
  quality->jitter_ns = results->jitter_ns;
  quality->packet_loss_pct = results->packet_loss_pct;
 
  POOL_FREE(response_data, response_len);
 
  log_debug("Bandwidth measurement: upload=%u kbps, download=%u kbps, rtt=%lu ns", quality->upload_kbps,
            quality->download_kbps, quality->rtt_to_acds_ns);
 
  return ASCIICHAT_OK;
}

References acip_bandwidth_result_t, acip_bandwidth_test_t, ASCIICHAT_OK, nat_quality_t::download_kbps, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, ERROR_NETWORK_PROTOCOL, ERROR_NETWORK_TIMEOUT, INVALID_SOCKET_VALUE, nat_quality_t::jitter_ns, log_debug, log_warn, NS_PER_SEC_INT, nat_quality_t::packet_loss_pct, packet_receive(), packet_send(), PACKET_TYPE_ACIP_BANDWIDTH_RESULT, PACKET_TYPE_ACIP_BANDWIDTH_TEST, POOL_FREE, nat_quality_t::rtt_to_acds_ns, SAFE_FREE, SAFE_MALLOC, SET_ERRNO, socket_set_timeout(), time_get_ns(), and nat_quality_t::upload_kbps.

nat_quality_from_acip()

void nat_quality_from_acip	(	const acip_nat_quality_t *	acip,
		nat_quality_t *	out
	)

Convert acip_nat_quality_t to nat_quality_t.

Parameters

acip	ACIP message structure
out	Output local NAT quality structure

Definition at line 497 of file nat.c.

                                                                               {
  if (!acip || !out)
    return;
 
  nat_quality_init(out);
 
  out->has_public_ip = acip->has_public_ip != 0;
  out->upnp_available = acip->upnp_available != 0;
  out->upnp_mapped_port = ((uint16_t)acip->upnp_mapped_port[0] << 8) | acip->upnp_mapped_port[1];
  out->nat_type = (acip_nat_type_t)acip->stun_nat_type;
  out->lan_reachable = acip->lan_reachable != 0;
  out->stun_latency_ns = acip->stun_latency_ns;
 
  out->upload_kbps = acip->upload_kbps;
  out->download_kbps = acip->download_kbps;
  out->rtt_to_acds_ns = acip->rtt_to_acds_ns;
  out->jitter_ns = acip->jitter_ns;
  out->packet_loss_pct = acip->packet_loss_pct;
 
  SAFE_STRNCPY(out->public_address, acip->public_address, sizeof(out->public_address));
  out->public_port = acip->public_port;
 
  out->has_host_candidates = (acip->ice_candidate_types & 1) != 0;
  out->has_srflx_candidates = (acip->ice_candidate_types & 2) != 0;
  out->has_relay_candidates = (acip->ice_candidate_types & 4) != 0;
 
  out->detection_complete = true;
}

References nat_quality_t::detection_complete, nat_quality_t::download_kbps, nat_quality_t::has_host_candidates, nat_quality_t::has_public_ip, nat_quality_t::has_relay_candidates, nat_quality_t::has_srflx_candidates, nat_quality_t::jitter_ns, nat_quality_t::lan_reachable, nat_quality_init(), nat_quality_t::nat_type, nat_quality_t::packet_loss_pct, nat_quality_t::public_address, nat_quality_t::public_port, nat_quality_t::rtt_to_acds_ns, SAFE_STRNCPY, nat_quality_t::stun_latency_ns, nat_quality_t::upload_kbps, nat_quality_t::upnp_available, and nat_quality_t::upnp_mapped_port.

Referenced by __attribute__(), negotiate_elect_future_host(), and negotiate_receive_peer_quality().

nat_quality_init()

void nat_quality_init

(

nat_quality_t *

quality

)

Initialize NAT quality structure with defaults.

Parameters

quality

Structure to initialize

Definition at line 32 of file nat.c.

                                              {
  if (!quality)
    return;
  memset(quality, 0, sizeof(nat_quality_t));
  quality->nat_type = ACIP_NAT_TYPE_SYMMETRIC; // Assume worst case
}

References ACIP_NAT_TYPE_SYMMETRIC, and nat_quality_t::nat_type.

Referenced by nat_detect_quality(), nat_quality_from_acip(), and negotiate_init().

nat_quality_to_acip()

void nat_quality_to_acip	(	const nat_quality_t *	quality,
		const uint8_t	session_id[16],
		const uint8_t	participant_id[16],
		acip_nat_quality_t *	out
	)

Convert nat_quality_t to acip_nat_quality_t for network transmission.

Parameters

quality	Local NAT quality
session_id	Session UUID
participant_id	Participant UUID
out	Output ACIP message structure

Definition at line 459 of file nat.c.

                                                  {
  if (!quality || !out)
    return;
 
  memset(out, 0, sizeof(acip_nat_quality_t));
 
  if (session_id)
    memcpy(out->session_id, session_id, 16);
  if (participant_id)
    memcpy(out->participant_id, participant_id, 16);
 
  out->has_public_ip = quality->has_public_ip ? 1 : 0;
  out->upnp_available = quality->upnp_available ? 1 : 0;
  out->upnp_mapped_port[0] = (uint8_t)(quality->upnp_mapped_port >> 8);
  out->upnp_mapped_port[1] = (uint8_t)(quality->upnp_mapped_port & 0xFF);
  out->stun_nat_type = (uint8_t)quality->nat_type;
  out->lan_reachable = quality->lan_reachable ? 1 : 0;
  out->stun_latency_ns = quality->stun_latency_ns;
 
  out->upload_kbps = quality->upload_kbps;
  out->download_kbps = quality->download_kbps;
  out->rtt_to_acds_ns = quality->rtt_to_acds_ns;
  out->jitter_ns = quality->jitter_ns;
  out->packet_loss_pct = quality->packet_loss_pct;
 
  SAFE_STRNCPY(out->public_address, quality->public_address, sizeof(out->public_address));
  out->public_port = quality->public_port;
 
  out->ice_candidate_types = 0;
  if (quality->has_host_candidates)
    out->ice_candidate_types |= 1;
  if (quality->has_srflx_candidates)
    out->ice_candidate_types |= 2;
  if (quality->has_relay_candidates)
    out->ice_candidate_types |= 4;
}

References acip_nat_quality_t, nat_quality_t::download_kbps, nat_quality_t::has_host_candidates, nat_quality_t::has_public_ip, nat_quality_t::has_relay_candidates, nat_quality_t::has_srflx_candidates, nat_quality_t::jitter_ns, nat_quality_t::lan_reachable, nat_quality_t::nat_type, nat_quality_t::packet_loss_pct, participant_id, nat_quality_t::public_address, nat_quality_t::public_port, nat_quality_t::rtt_to_acds_ns, SAFE_STRNCPY, session_id, nat_quality_t::stun_latency_ns, nat_quality_t::upload_kbps, nat_quality_t::upnp_available, and nat_quality_t::upnp_mapped_port.

nat_type_to_string()

const char * nat_type_to_string

(

acip_nat_type_t

type

)

Get human-readable description of NAT type.

Parameters

type

NAT type

Returns

String description

Definition at line 526 of file nat.c.

                                                     {
  switch (type) {
  case ACIP_NAT_TYPE_OPEN:
    return "Open (Public IP)";
  case ACIP_NAT_TYPE_FULL_CONE:
    return "Full Cone";
  case ACIP_NAT_TYPE_RESTRICTED:
    return "Restricted Cone";
  case ACIP_NAT_TYPE_PORT_RESTRICTED:
    return "Port Restricted";
  case ACIP_NAT_TYPE_SYMMETRIC:
    return "Symmetric";
  default:
    return "Unknown";
  }
}

References ACIP_NAT_TYPE_FULL_CONE, ACIP_NAT_TYPE_OPEN, ACIP_NAT_TYPE_PORT_RESTRICTED, ACIP_NAT_TYPE_RESTRICTED, and ACIP_NAT_TYPE_SYMMETRIC.

Referenced by nat_detect_quality().