discovery.h File Reference

Go to the source code of this file.

Data Structures
struct	discovery_result_t
	Result from session discovery. More...
struct	discovery_config_t
	Configuration for discovery session. More...

Macros
#define	NETWORK_MDNS_DISCOVERY_ERROR_MESSAGE_BUFFER_SIZE   256

Functions
void	discovery_config_init_defaults (discovery_config_t *config)
	Initialize discovery config with defaults.
asciichat_error_t	discover_session_parallel (const char *session_string, const discovery_config_t *config, discovery_result_t *result)
	Look up session in parallel on mDNS and ACDS.
ui_mdns_server_t *	discovery_mdns_query (int timeout_ms, int max_servers, bool quiet, int *out_count)
	Discover ascii-chat servers on local network via mDNS.
void	discovery_mdns_destroy (ui_mdns_server_t *servers)
	Free memory from mDNS discovery results.
void	pubkey_to_hex (const uint8_t pubkey[32], char hex_out[(32 *2+1)])
	Convert Ed25519 public key to hex string.
asciichat_error_t	hex_to_pubkey (const char *hex_str, uint8_t pubkey_out[32])
	Convert hex string to Ed25519 public key.

Macro Definition Documentation

NETWORK_MDNS_DISCOVERY_ERROR_MESSAGE_BUFFER_SIZE

#define NETWORK_MDNS_DISCOVERY_ERROR_MESSAGE_BUFFER_SIZE   256

Definition at line 67 of file discovery.h.

Function Documentation

discover_session_parallel()

asciichat_error_t discover_session_parallel	(	const char *	session_string,
		const discovery_config_t *	config,
		discovery_result_t *	result )

Look up session in parallel on mDNS and ACDS.

Spawns two concurrent threads to search both mDNS (local LAN) and ACDS (internet). Returns immediately when either finds the session, cancelling the other search.

Verification Logic:

If config->expected_pubkey is set:

• mDNS result: Verify TXT record contains matching host_pubkey
• ACDS result: Verify SESSION_LOOKUP response contains matching host_pubkey
• If both find result: Verify they have same pubkey (cross-check)
• On mismatch: Return ERROR_CRYPTO_VERIFY_FAILED

If config->expected_pubkey is NULL but config->insecure_mode is true:

• Skip all verification, accept first result found
• WARNING: Vulnerable to MITM attacks!

If config->expected_pubkey is NULL and config->insecure_mode is false:

• Search mDNS only (ACDS thread not started)
• Use TOFU (Trust On First Use): accept first mDNS result found

Thread Lifecycle:

• Both threads start immediately
• Whichever completes first signals success via condition variable
• Other thread is joined (cleaned up)
• Function returns with result

Parameters

session_string	Session string to find (e.g., "swift-river-mountain")
config	Discovery configuration
result	Discovery result (output)

Returns

ASCIICHAT_OK on success, error code on failure

Note

This function BLOCKS until one discovery method succeeds or both timeout

Not thread-safe for concurrent calls - use only one discovery at a time

Definition at line 541 of file discovery.c.

                                                                        {
  if (!session_string || !config || !result) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
    return ERROR_INVALID_PARAM;
  }
 
  // Validate session string format
  if (!is_session_string(session_string)) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid session string format");
    return ERROR_INVALID_PARAM;
  }
 
  memset(result, 0, sizeof(*result));
  log_info("Discovery: Looking up session '%s'", session_string);
 
  // Initialize thread state
  discovery_thread_state_t state;
  memset(&state, 0, sizeof(state));
  state.result = result;
  mutex_init(&state.lock, "mdns_resolve");
  cond_init(&state.signal, "mdns_signal");
 
  // Determine which discovery methods to use
  bool use_mdns = true;
  bool use_acds = config->expected_pubkey != NULL || config->insecure_mode;
  if (config->insecure_mode && !config->expected_pubkey)
    NOTICE(DANGER, "DISCOVERY HOST VERIFICATION DISABLED",
           "Insecure discovery is enabled without an expected host key.\n"
           "The discovered host identity cannot be verified; this is vulnerable to man-in-the-middle attacks.");
 
  if (!use_acds) {
    log_debug("Discovery: mDNS-only mode (no --server-key and no --acds-insecure)");
  }
 
  // Spawn mDNS thread
  platform_thread_t mdns_thread;
  thread_init(&mdns_thread);
 
  if (use_mdns) {
    mdns_thread_context_t *mdns_ctx = SAFE_MALLOC(sizeof(*mdns_ctx), mdns_thread_context_t *);
    if (!mdns_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate mDNS context");
      mutex_destroy(&state.lock);
      cond_destroy(&state.signal);
      return ERROR_MEMORY;
    }
 
    mdns_ctx->session_string = session_string;
    mdns_ctx->state = &state;
    mdns_ctx->expected_pubkey = config->expected_pubkey;
 
    int thread_err = platform_thread_create(&mdns_thread, "mdns", mdns_thread_fn, mdns_ctx);
    if (thread_err != 0) {
      log_warn("Discovery: Failed to spawn mDNS thread");
      SAFE_FREE(mdns_ctx);
      use_mdns = false;
    }
  }
 
  // Spawn ACDS thread
  platform_thread_t acds_thread;
  thread_init(&acds_thread);
 
  if (use_acds) {
    acds_thread_context_t *acds_ctx = SAFE_MALLOC(sizeof(*acds_ctx), acds_thread_context_t *);
    if (!acds_ctx) {
      SET_ERRNO(ERROR_MEMORY, "Failed to allocate ACDS context");
      if (use_mdns && thread_is_initialized(&mdns_thread)) {
        thread_join(&mdns_thread, NULL);
      }
      mutex_destroy(&state.lock);
      cond_destroy(&state.signal);
      return ERROR_MEMORY;
    }
 
    acds_ctx->session_string = session_string;
    acds_ctx->state = &state;
    acds_ctx->config = config;
 
    int thread_err = platform_thread_create(&acds_thread, "acds_client", acds_thread_fn, acds_ctx);
    if (thread_err != 0) {
      log_warn("Discovery: Failed to spawn ACDS thread");
      SAFE_FREE(acds_ctx);
      use_acds = false;
    }
  }
 
  // Wait for result (mDNS timeout 2s + ACDS timeout 5s max)
  uint32_t wait_timeout_ms = config->acds_timeout_ms + 1000;
  mutex_lock(&state.lock);
  {
    uint32_t elapsed_ms = 0;
    while (!state.found && elapsed_ms < wait_timeout_ms) {
      // Check if both threads are done
      if (state.mdns_done && state.acds_done) {
        break;
      }
 
      // Wait with timeout
      cond_timedwait(&state.signal, &state.lock, 500 * NS_PER_MS_INT);
      elapsed_ms += 500;
    }
  }
  mutex_unlock(&state.lock);
 
  // Join threads
  if (use_mdns && thread_is_initialized(&mdns_thread)) {
    thread_join(&mdns_thread, NULL);
  }
  if (use_acds && thread_is_initialized(&acds_thread)) {
    thread_join(&acds_thread, NULL);
  }
 
  // Cleanup
  mutex_destroy(&state.lock);
  cond_destroy(&state.signal);
 
  // Check result
  if (!result->success) {
    SET_ERRNO(ERROR_NOT_FOUND, "Session '%s' not found (mDNS/ACDS timeout)", session_string);
    return ERROR_NOT_FOUND;
  }
 
  log_info("Discovery: Session '%s' discovered via %s", session_string,
           result->source == DISCOVERY_SOURCE_MDNS ? "mDNS" : "ACDS");
 
  return ASCIICHAT_OK;
}

References discovery_config_t::acds_timeout_ms, ASCIICHAT_OK, acds_thread_context_t::config, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NOT_FOUND, discovery_config_t::expected_pubkey, mdns_thread_context_t::expected_pubkey, discovery_config_t::insecure_mode, is_session_string(), log_debug, log_info, log_warn, NOTICE, NS_PER_MS_INT, SAFE_FREE, SAFE_MALLOC, acds_thread_context_t::session_string, mdns_thread_context_t::session_string, SET_ERRNO, discovery_result_t::source, acds_thread_context_t::state, mdns_thread_context_t::state, and discovery_result_t::success.

discovery_config_init_defaults()

void discovery_config_init_defaults

(

discovery_config_t *

config

)

Initialize discovery config with defaults.

Sets sensible defaults:

• ACDS server: localhost:27225 (debug), discovery.ascii-chat.com (release)
• Timeouts: mdns=2000ms, acds=5000ms
• Verification: None (expected_pubkey=NULL)
• Insecure mode: false

Parameters

config

Configuration to initialize

Definition at line 519 of file discovery.c.

                                                                {
  if (!config)
    return;
 
  memset(config, 0, sizeof(*config));
 
  // Check if debug or release build
#ifdef NDEBUG
  // Release: use internet ACDS
  SAFE_STRNCPY(config->acds_server, "discovery.ascii-chat.com", sizeof(config->acds_server) - 1);
#else
  // Debug: use local ACDS
  SAFE_STRNCPY(config->acds_server, "127.0.0.1", sizeof(config->acds_server) - 1);
#endif
 
  config->acds_port = OPT_ACDS_PORT_INT_DEFAULT;
  config->mdns_timeout_ms = 2 * MS_PER_SEC_INT;
  config->acds_timeout_ms = 5 * MS_PER_SEC_INT;
  config->insecure_mode = false;
  config->expected_pubkey = NULL;
}

References discovery_config_t::acds_port, discovery_config_t::acds_server, discovery_config_t::acds_timeout_ms, discovery_config_t::expected_pubkey, discovery_config_t::insecure_mode, discovery_config_t::mdns_timeout_ms, MS_PER_SEC_INT, OPT_ACDS_PORT_INT_DEFAULT, and SAFE_STRNCPY.

discovery_mdns_destroy()

void discovery_mdns_destroy

(

ui_mdns_server_t *

servers

)

Free memory from mDNS discovery results.

Definition at line 288 of file discovery.c.

                                                       {
  SAFE_FREE(servers);
}

References SAFE_FREE.

Referenced by ui_mdns_free_results().

discovery_mdns_query()

ui_mdns_server_t * discovery_mdns_query	(	int	timeout_ms,
		int	max_servers,
		bool	quiet,
		int *	out_count )

Discover ascii-chat servers on local network via mDNS.

Queries for mDNS _ascii-chat._tcp services and returns discovered servers. This is the core discovery function used by both:

• Parallel discovery threads (discover_session_parallel)
• TUI wrapper (lan_discovery_query)

Parameters

timeout_ms	Query timeout in milliseconds (default: 2000)
max_servers	Maximum servers to discover (default: 20)
quiet	If true, suppresses progress messages
out_count	Output: number of servers discovered

Returns

Array of discovered servers, or NULL on error. Use discovery_mdns_destroy() to free.

Discover ascii-chat servers on local network via mDNS.

Parameters

timeout_ms	Query timeout in milliseconds
max_servers	Maximum servers to discover
quiet	If true, suppresses progress messages
out_count	Output: number of servers discovered

Returns

Array of discovered servers, or NULL on error. Use discovery_mdns_destroy() to free.

Definition at line 192 of file discovery.c.

                                                                                                    {
  if (!out_count) {
    SET_ERRNO(ERROR_INVALID_PARAM, "out_count pointer is NULL");
    return NULL;
  }
 
  *out_count = 0;
 
  // Apply defaults
  if (timeout_ms <= 0) {
    timeout_ms = 2 * MS_PER_SEC_INT;
  }
  if (max_servers <= 0) {
    max_servers = 20;
  }
 
  // Allocate state for collecting servers
  mdns_query_state_t state;
  memset(&state, 0, sizeof(state));
  state.capacity = max_servers;
  state.timeout_ms = timeout_ms;
  state.start_time_ms = (int64_t)time_ns_to_ms(time_get_ns());
 
  // Allocate server array
  state.servers = SAFE_MALLOC((size_t)state.capacity * sizeof(ui_mdns_server_t), ui_mdns_server_t *);
  if (!state.servers) {
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate mDNS discovery server array");
    return NULL;
  }
  memset(state.servers, 0, state.capacity * sizeof(ui_mdns_server_t));
 
  if (!quiet) {
    log_info("mDNS: Searching for ascii-chat servers on local network (timeout: %dms)", state.timeout_ms);
    printf("🔍 Searching for ascii-chat servers on LAN...\n");
  }
 
  // Discovery is retried in the live picker; failures remain in logs.
  asciichat_errno_scope_t query_scope = errno_scope_begin();
  bool previous_notifications = errno_notifications_suppress(true);
  // Initialize mDNS
  asciichat_mdns_t *mdns = asciichat_mdns_init();
  if (!mdns) {
    log_warn("mDNS: Failed to initialize mDNS - discovery unavailable");
    errno_notifications_suppress(previous_notifications);
    errno_scope_end(query_scope, ASCIICHAT_ERRNO_HANDLED);
    return state.servers;
  }
 
  // Start mDNS query for _ascii-chat._tcp services
  asciichat_error_t query_result =
      asciichat_mdns_query(mdns, "_ascii-chat._tcp.local", discovery_mdns_callback, &state);
 
  if (query_result != ASCIICHAT_OK) {
    log_info("mDNS: Query failed - no servers found via service discovery");
    asciichat_mdns_destroy(mdns);
    errno_notifications_suppress(previous_notifications);
    errno_scope_end(query_scope, ASCIICHAT_ERRNO_HANDLED);
    return state.servers;
  }
 
  // Poll for responses until timeout
  int64_t deadline = state.start_time_ms + state.timeout_ms;
  while (!state.query_complete && (int64_t)time_ns_to_ms(time_get_ns()) < deadline) {
    int poll_timeout = (int)(deadline - (int64_t)time_ns_to_ms(time_get_ns()));
    if (poll_timeout < 0) {
      poll_timeout = 0;
    }
    if (poll_timeout > 100) {
      poll_timeout = 100; // Check every 100ms
    }
    if (asciichat_mdns_update(mdns, poll_timeout) != ASCIICHAT_OK)
      break;
  }
 
  // Cleanup mDNS
  asciichat_mdns_destroy(mdns);
  errno_notifications_suppress(previous_notifications);
  errno_scope_end(query_scope, ASCIICHAT_ERRNO_HANDLED);
 
  if (!quiet) {
    if (state.count > 0) {
      printf("✅ Found %d ascii-chat server%s on LAN\n", state.count, state.count == 1 ? "" : "s");
      log_info("mDNS: Found %d server(s)", state.count);
    } else {
      printf("❌ No ascii-chat servers found on LAN\n");
      log_info("mDNS: No servers found");
    }
  }
 
  *out_count = state.count;
  return state.servers;
}

References ASCIICHAT_ERRNO_HANDLED, asciichat_mdns_destroy(), asciichat_mdns_init(), asciichat_mdns_query(), asciichat_mdns_update(), ASCIICHAT_OK, errno_notifications_suppress(), errno_scope_begin(), errno_scope_end(), ERROR_INVALID_PARAM, ERROR_MEMORY, log_info, log_warn, MS_PER_SEC_INT, SAFE_MALLOC, and SET_ERRNO.

Referenced by ui_mdns_query().

hex_to_pubkey()

asciichat_error_t hex_to_pubkey	(	const char *	hex_str,
		uint8_t	pubkey_out[32] )

Convert hex string to Ed25519 public key.

Converts 64-character hex string to 32-byte binary pubkey.

Parameters

hex_str	Hex string (64 characters)
pubkey_out	Output binary pubkey (32 bytes)

Returns

ASCIICHAT_OK on success, ERROR_INVALID_PARAM if invalid hex

Definition at line 67 of file discovery.c.

                                                                                                  {
  if (!hex_str || !pubkey_out) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid hex_str or pubkey_out pointer");
    return ERROR_INVALID_PARAM;
  }
 
  if (strlen(hex_str) != 64) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Hex string must be exactly 64 characters");
    return ERROR_INVALID_PARAM;
  }
 
  for (int i = 0; i < 32; i++) {
    char hex_byte[3];
    hex_byte[0] = hex_str[i * 2];
    hex_byte[1] = hex_str[i * 2 + 1];
    hex_byte[2] = '\0';
 
    if (!isxdigit(hex_byte[0]) || !isxdigit(hex_byte[1])) {
      SET_ERRNO(ERROR_INVALID_PARAM, "Invalid hex character in string");
      return ERROR_INVALID_PARAM;
    }
 
    pubkey_out[i] = (uint8_t)strtol(hex_byte, NULL, 16);
  }
 
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ED25519_PUBLIC_KEY_SIZE, ERROR_INVALID_PARAM, and SET_ERRNO.

pubkey_to_hex()

void pubkey_to_hex	(	const uint8_t	pubkey[32],
		char	hex_out[(32 *2+1)] )

Convert Ed25519 public key to hex string.

Converts 32-byte binary pubkey to lowercase hex (64 characters).

Parameters

pubkey	Binary public key (32 bytes)
hex_out	Output hex string buffer (must be at least 65 bytes)

Definition at line 58 of file discovery.c.

                                                                                                    {
  if (!pubkey || !hex_out)
    return;
  for (int i = 0; i < 32; i++) {
    safe_snprintf(hex_out + (i * 2), 3, "%02x", pubkey[i]);
  }
  hex_out[64] = '\0';
}

References ED25519_PUBLIC_KEY_SIZE, HEX_STRING_SIZE_32, and safe_snprintf().