discovery.c File Reference

Parallel mDNS and ACDS session discovery implementation. More...

Go to the source code of this file.

Data Structures
struct	discovery_thread_state_t
struct	mdns_query_state_t
	Internal state for collecting discovered services. More...
struct	mdns_thread_context_t
struct	acds_thread_context_t

Functions
void	pubkey_to_hex (const uint8_t pubkey[32], char hex_out[65])
	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.
bool	is_session_string (const char *str)
	Check if a string matches session string pattern.
discovery_tui_server_t *	discovery_mdns_query (int timeout_ms, int max_servers, bool quiet, int *out_count)
	Public mDNS query function used by both parallel discovery and TUI wrapper.
void	discovery_mdns_free (discovery_tui_server_t *servers)
	Free memory from mDNS discovery results.
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.

Detailed Description

Parallel mDNS and ACDS session discovery implementation.

This module provides automated discovery of ascii-chat servers via parallel mDNS (local LAN) and ACDS (internet) lookups.

Architecture:

• mDNS discovery: discovery_mdns_query() - core implementation (this module)
• ACDS discovery: ACDS client implementation for centralized lookup
• Parallel coordination: Concurrent threads with "race to success" semantics
• TUI wrapper: discovery_tui.c calls discovery_mdns_query() for interactive selection

Definition in file discovery.c.

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 655 of file discovery.c.

                                                                        {
  if (!session_string || !config || !result) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters to discover_session_parallel");
    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);
  cond_init(&state.signal);
 
  // Determine which discovery methods to use
  bool use_mdns = true;
  bool use_acds = config->expected_pubkey != NULL || config->insecure_mode;
 
  if (!use_acds) {
    log_debug("Discovery: mDNS-only mode (no --server-key and no --acds-insecure)");
  }
 
  // Spawn mDNS thread
  asciichat_thread_t mdns_thread;
  asciichat_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 = asciichat_thread_create(&mdns_thread, 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
  asciichat_thread_t acds_thread;
  asciichat_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 && asciichat_thread_is_initialized(&mdns_thread)) {
        asciichat_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 = asciichat_thread_create(&acds_thread, 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);
      elapsed_ms += 500;
    }
  }
  mutex_unlock(&state.lock);
 
  // Join threads
  if (use_mdns && asciichat_thread_is_initialized(&mdns_thread)) {
    asciichat_thread_join(&mdns_thread, NULL);
  }
  if (use_acds && asciichat_thread_is_initialized(&acds_thread)) {
    asciichat_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_thread_state_t::acds_done, discovery_config_t::acds_timeout_ms, ASCIICHAT_OK, asciichat_thread_create(), asciichat_thread_init(), asciichat_thread_is_initialized(), asciichat_thread_join(), cond_destroy(), cond_init(), cond_timedwait(), acds_thread_context_t::config, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NOT_FOUND, mdns_thread_context_t::expected_pubkey, discovery_config_t::expected_pubkey, discovery_thread_state_t::found, discovery_config_t::insecure_mode, is_session_string(), discovery_thread_state_t::lock, log_debug, log_info, log_warn, discovery_thread_state_t::mdns_done, mutex_destroy(), mutex_init(), mutex_lock, mutex_unlock, discovery_thread_state_t::result, SAFE_FREE, SAFE_MALLOC, mdns_thread_context_t::session_string, acds_thread_context_t::session_string, SET_ERRNO, discovery_thread_state_t::signal, discovery_result_t::source, mdns_thread_context_t::state, acds_thread_context_t::state, and discovery_result_t::success.

Referenced by client_main().

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), acds.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 633 of file discovery.c.

                                                                {
  if (!config)
    return;
 
  memset(config, 0, sizeof(*config));
 
  // Check if debug or release build
#ifdef NDEBUG
  // Release: use internet ACDS
  strncpy(config->acds_server, "discovery.ascii-chat.com", sizeof(config->acds_server) - 1);
#else
  // Debug: use local ACDS
  strncpy(config->acds_server, "127.0.0.1", sizeof(config->acds_server) - 1);
#endif
 
  config->acds_port = 27225;
  config->mdns_timeout_ms = 2000;
  config->acds_timeout_ms = 5000;
  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, and discovery_config_t::mdns_timeout_ms.

Referenced by client_main().

discovery_mdns_free()

void discovery_mdns_free

(

discovery_tui_server_t *

servers

)

Free memory from mDNS discovery results.

Definition at line 408 of file discovery.c.

                                                          {
  SAFE_FREE(servers);
}

References SAFE_FREE.

Referenced by discovery_tui_free_results().

discovery_mdns_query()

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

Public mDNS query function used by both parallel discovery and TUI wrapper.

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_free() to free.

Definition at line 320 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 = 2000;
  }
  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 = discovery_get_time_ms();
 
  // Allocate server array
  state.servers = SAFE_MALLOC((size_t)state.capacity * sizeof(discovery_tui_server_t), discovery_tui_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(discovery_tui_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");
  }
 
  // Initialize mDNS
  asciichat_mdns_t *mdns = asciichat_mdns_init();
  if (!mdns) {
    log_warn("mDNS: Failed to initialize mDNS - discovery unavailable");
    SAFE_FREE(state.servers);
    return NULL;
  }
 
  // 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_shutdown(mdns);
    SAFE_FREE(state.servers);
    return NULL;
  }
 
  // Poll for responses until timeout
  int64_t deadline = state.start_time_ms + state.timeout_ms;
  while (!state.query_complete && discovery_get_time_ms() < deadline) {
    int poll_timeout = (int)(deadline - discovery_get_time_ms());
    if (poll_timeout < 0) {
      poll_timeout = 0;
    }
    if (poll_timeout > 100) {
      poll_timeout = 100; // Check every 100ms
    }
    asciichat_mdns_update(mdns, poll_timeout);
  }
 
  // Cleanup mDNS
  asciichat_mdns_shutdown(mdns);
 
  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_mdns_init(), asciichat_mdns_query(), asciichat_mdns_shutdown(), asciichat_mdns_update(), ASCIICHAT_OK, mdns_query_state_t::capacity, mdns_query_state_t::count, ERROR_INVALID_PARAM, ERROR_MEMORY, log_info, log_warn, mdns_query_state_t::query_complete, SAFE_FREE, SAFE_MALLOC, mdns_query_state_t::servers, SET_ERRNO, mdns_query_state_t::start_time_ms, and mdns_query_state_t::timeout_ms.

Referenced by discovery_tui_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 55 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, ERROR_INVALID_PARAM, and SET_ERRNO.

Referenced by client_main().

is_session_string()

bool is_session_string

(

const char *

str

)

Check if a string matches session string pattern.

Validates that input matches three-word pattern: word-word-word Each word is 3-64 characters of alphanumerics and hyphens (RFC 952).

Examples:

• ✅ swift-river-mountain - valid
• ✅ cat-dog-bird - valid
• ❌ swift - invalid (only one word)
• ❌ swift-river- - invalid (trailing hyphen)
• ❌ swift_river_mountain - invalid (underscores not allowed)

Parameters

str	String to validate

Returns

true if matches session string pattern, false otherwise

Note

Used by src/main.c to detect binary-level session string argument

Definition at line 83 of file discovery.c.

                                        {
  if (!str || strlen(str) == 0)
    return false;
 
  // Parse as word-word-word where each word is 3-64 alphanumerics
  // Hyphens are separators between words
  // No leading/trailing hyphens, no consecutive hyphens
  size_t len = strlen(str);
 
  // Check length bounds (minimum: "a-a-a" = 5, maximum: 64 chars per word * 3 + 2 hyphens = 194)
  if (len < 5 || len > 194) {
    return false;
  }
 
  // Must not start or end with hyphen
  if (str[0] == '-' || str[len - 1] == '-') {
    return false;
  }
 
  // Count words separated by hyphens
  int word_count = 1; // Start with 1 (not 0) to account for first word
  int current_word_len = 0;
  bool last_was_hyphen = false;
 
  for (size_t i = 0; i < len; i++) {
    char c = str[i];
 
    if (isalnum(c)) {
      current_word_len++;
 
      // Individual word must be 3-64 characters
      if (current_word_len > 64) {
        return false;
      }
      last_was_hyphen = false;
    } else if (c == '-') {
      // Hyphen marks end of current word
      if (last_was_hyphen) {
        // Consecutive hyphens
        return false;
      }
 
      // Current word must have been at least 3 chars
      if (current_word_len < 3) {
        return false;
      }
 
      word_count++;
      current_word_len = 0;
      last_was_hyphen = true;
    } else {
      // Invalid character
      return false;
    }
  }
 
  // Final word must be 3-64 characters
  if (current_word_len < 3 || current_word_len > 64) {
    return false;
  }
 
  // Must have exactly 3 words
  return word_count == 3;
}

Referenced by discover_session_parallel(), and parse_client_address().

pubkey_to_hex()

void pubkey_to_hex	(	const uint8_t	pubkey[32],
		char	hex_out[65]
	)

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 46 of file discovery.c.

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