Stun

Macros
#define	STUN_URL_BUFFER_SIZE   64
	STUN server configuration.

Functions
struct	__attribute__ ((packed))
int	stun_servers_parse (const char *csv_servers, const char *default_csv, stun_server_t *out_servers, int max_count)
	Parse comma-separated STUN server URLs into stun_server_t array.

Variables
	stun_server_t

STUN Protocol Constants
#define	STUN_DEFAULT_PORT   3478
	Standard STUN port (RFC 5389).
#define	STUN_TLS_DEFAULT_PORT   5349
	STUN over TLS port (RFC 5389).

Detailed Description

This module defines STUN server configuration structures for WebRTC connectivity. STUN servers help clients discover their public IP addresses and port mappings when behind NAT.

RFC 5389: Session Traversal Utilities for NAT (STUN) RFC 8489: Session Traversal Utilities for NAT (STUN) - updated

STUN SERVER ROLE:

• Helps clients discover their public-facing IP address and port
• Essential for WebRTC peer-to-peer connection establishment
• No relay (unlike TURN) - only provides connectivity information

USAGE IN ACDS:

• Discovery server provides STUN server list in SESSION_CREATED response
• Clients use STUN servers for ICE candidate gathering
• Multiple STUN servers can be provided for redundancy

Note

All structures are packed with attribute((packed)) for wire format

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

January 2026

Version

1.0

Macro Definition Documentation

STUN_DEFAULT_PORT

#define STUN_DEFAULT_PORT   3478

#include <include/ascii-chat/network/webrtc/stun.h>

Standard STUN port (RFC 5389).

Definition at line 87 of file stun.h.

STUN_TLS_DEFAULT_PORT

#define STUN_TLS_DEFAULT_PORT   5349

#include <include/ascii-chat/network/webrtc/stun.h>

STUN over TLS port (RFC 5389).

Definition at line 90 of file stun.h.

STUN_URL_BUFFER_SIZE

#define STUN_URL_BUFFER_SIZE   64

#include <include/ascii-chat/network/webrtc/stun.h>

STUN server configuration.

Used in ACDS SESSION_CREATED response to provide WebRTC connectivity information.

Protocol Format:

• host_len: 1 byte (length of host string)
• host: 64 bytes (null-terminated STUN URL)

URL Format Examples:

• Stun:discovery.ascii.chat:3478 (standard port)
• Stun:stun.l.google.com:19302 (Google public STUN)
• Stun:stun.example.com:5349 (custom port)

Wire Format (65 bytes total):

+----------+----------------------------------------+
| host_len |              host[64]                  |
+----------+----------------------------------------+
| 1 byte   |              64 bytes                  |
+----------+----------------------------------------+

STUN wire URL capacity in bytes, including NUL (63 URL bytes).

Definition at line 73 of file stun.h.

Referenced by stun_servers_parse().

Function Documentation

__attribute__()

struct __attribute__

(

(packed)

)

#include <include/ascii-chat/network/webrtc/stun.h>

< Length of host string (actual URL length)

< STUN server URL (e.g., "stun:discovery.ascii.chat:3478")

Definition at line 1 of file stun.h.

                                       {
  uint8_t host_len;                
  char host[STUN_URL_BUFFER_SIZE]; 
} stun_server_t;

stun_servers_parse()

int stun_servers_parse	(	const char *	csv_servers,
		const char *	default_csv,
		stun_server_t *	out_servers,
		int	max_count )

#include <include/ascii-chat/network/webrtc/stun.h>

Parse comma-separated STUN server URLs into stun_server_t array.

Parses a comma-separated string of STUN server URLs (e.g., "stun:server1:3478,stun:server2:3478") into an array of stun_server_t structs. If the input string is empty or NULL, uses the default endpoints from the options system.

Example Input Formats:

• Empty: "" (will use defaults from OPT_STUN_SERVERS_DEFAULT)
• Single: "stun:stun.example.com:3478"
• Multiple: "stun:server1:3478,stun:server2:19302,stun:server3:5349"

Parameters

csv_servers	Comma-separated STUN server URLs (can be empty)
default_csv	Default servers to use if csv_servers is empty
out_servers	Output array of stun_server_t structs (must be pre-allocated)
max_count	Maximum number of servers to parse

Returns

Number of servers parsed (0-max_count), or -1 on error

Note

Each server URL is limited to STUN_URL_BUFFER_SIZE - 1 bytes, excluding NUL

Function gracefully stops at max_count or if a server exceeds max length

Parses a comma-separated string of STUN server URLs into stun_server_t structs. If the input string is empty or NULL, uses the provided default string.

Parameters

csv_servers	Comma-separated STUN server URLs (can be empty)
default_csv	Default servers to use if csv_servers is empty
out_servers	Output array of stun_server_t structs (must be pre-allocated)
max_count	Maximum number of servers to parse

Returns

Number of servers parsed (0-max_count), or -1 on error

Definition at line 45 of file stun.c.

                                                                                                                    {
  if (!out_servers || max_count <= 0) {
    log_warn("Invalid output array or max_count");
    return -1;
  }
 
  // Use defaults if input is empty
  const char *servers_to_parse = csv_servers;
  if (!servers_to_parse || servers_to_parse[0] == '\0') {
    servers_to_parse = default_csv;
  }
 
  if (!servers_to_parse || servers_to_parse[0] == '\0') {
    log_warn("No servers to parse and no defaults provided");
    return 0;
  }
 
  // Get compiled regex (owned by the caller)
  pcre2_code *regex = stun_entry_regex_get();
 
  // If regex not available, fall back to manual parsing
  if (!regex) {
    log_warn("PCRE2 regex not available, falling back to manual parsing");
    // Fallback: manual character-by-character parsing (original implementation)
    int count = 0;
    const char *current = servers_to_parse;
    const char *end;
 
    while (count < max_count && *current != '\0') {
      while (isspace(*current)) {
        current++;
      }
      if (*current == '\0')
        break;
 
      end = strchr(current, ',');
      if (!end) {
        end = current + strlen(current);
      }
 
      while (end > current && isspace(*(end - 1))) {
        end--;
      }
 
      size_t len = end - current;
      if (len == 0) {
        current = *end ? end + 1 : end;
        continue;
      }
 
      if (len >= STUN_URL_BUFFER_SIZE) {
        log_warn("STUN server URL too long (max %d): %.*s", STUN_URL_BUFFER_SIZE - 1, (int)len, current);
        return -1;
      }
 
      out_servers[count].host_len = (uint8_t)len;
      memcpy(out_servers[count].host, current, len);
      out_servers[count].host[len] = '\0';
      count++;
 
      current = *end ? end + 1 : end;
    }
    return count;
  }
 
  // Parse using PCRE2 regex: match each trimmed entry
  int count = 0;
  pcre2_match_data *match_data = pcre2_match_data_create_from_pattern(regex, NULL);
  if (!match_data) {
    pcre2_code_free(regex);
    log_warn("Failed to allocate PCRE2 match data");
    return -1;
  }
 
  size_t offset = 0;
  int rc;
 
  while (count < max_count) {
    rc = asciichat_pcre2_match(regex, (PCRE2_SPTR8)servers_to_parse, strlen(servers_to_parse), offset, 0, match_data,
                               NULL);
 
    if (rc < 0) {
      // No more matches (PCRE2_ERROR_NOMATCH or other error)
      break;
    }
 
    // Extract the captured group (group 1)
    size_t len;
    const char *server_url = asciichat_pcre2_extract_group_ptr(match_data, 1, servers_to_parse, &len);
 
    if (!server_url) {
      break; // Group not matched
    }
 
    if (len >= STUN_URL_BUFFER_SIZE) {
      log_warn("STUN server URL too long (max %d): %.*s", STUN_URL_BUFFER_SIZE - 1, (int)len, server_url);
      pcre2_match_data_free(match_data);
      pcre2_code_free(regex);
      return -1;
    }
 
    // Copy trimmed entry to output
    out_servers[count].host_len = (uint8_t)len;
    memcpy(out_servers[count].host, server_url, len);
    out_servers[count].host[len] = '\0';
 
    count++;
 
    // Move offset to end of this match (need ovector for overall match end)
    PCRE2_SIZE *ovector = pcre2_get_ovector_pointer(match_data);
    offset = ovector[1];
 
    // Skip comma if present
    if (offset < strlen(servers_to_parse) && servers_to_parse[offset] == ',') {
      offset++;
    }
  }
 
  pcre2_match_data_free(match_data);
  pcre2_code_free(regex);
  return count;
}

References asciichat_pcre2_extract_group_ptr(), asciichat_pcre2_match(), log_warn, stun_server_t, and STUN_URL_BUFFER_SIZE.

Variable Documentation

stun_server_t

stun_server_t

#include <include/ascii-chat/network/webrtc/stun.h>

Definition at line 78 of file stun.h.

Referenced by stun_servers_parse().