upnp.h File Reference

UPnP/NAT-PMP port mapping for TCP and UDP connectivity. More...

Go to the source code of this file.

Data Structures
struct	nat_upnp_context
	Handle to UPnP context. More...

Macros
#define	NETWORK_NAT_UPNP_EXTERNAL_IP_BUFFER_SIZE   16
#define	NETWORK_NAT_UPNP_DEVICE_DESCRIPTION_BUFFER_SIZE   256
#define	NETWORK_NAT_UPNP_INTERNAL_IP_BUFFER_SIZE   16
#define	NETWORK_NAT_UPNP_SERVICE_TYPE_BUFFER_SIZE   128
#define	NETWORK_NAT_UPNP_DESCRIPTION_BUFFER_SIZE   128

Typedefs
typedef struct nat_upnp_context	nat_upnp_context_t
	Handle to UPnP context.

Enumerations
enum	nat_upnp_protocol_t { NAT_UPNP_TCP , NAT_UPNP_UDP }

Functions
asciichat_error_t	nat_upnp_open (uint16_t internal_port, const char *description, nat_upnp_context_t **ctx)
	Discover and open port via UPnP.
asciichat_error_t	nat_upnp_open_protocol (uint16_t internal_port, const char *description, nat_upnp_protocol_t protocol, nat_upnp_context_t **ctx)
	Open an owned TCP or UDP mapping; close with nat_upnp_close().
void	nat_upnp_close (nat_upnp_context_t **ctx)
	Close port mapping and clean up.
bool	nat_upnp_is_active (const nat_upnp_context_t *ctx)
	Check if port mapping is still active.
bool	nat_upnp_matches_bind_address (const nat_upnp_context_t *ctx, const char *bind_address)
	Whether the mapping targets a specific IPv4 bind address, or any wildcard listener.
asciichat_error_t	nat_upnp_get_endpoint (const nat_upnp_context_t *ctx, char *ip, size_t ip_len, uint16_t *port)
	Copy the unexpired mapped IP and external port for discovery advertisement.
asciichat_error_t	nat_upnp_refresh (nat_upnp_context_t *ctx)
	Refresh port mapping (e.g., for long-running servers).
asciichat_error_t	nat_upnp_get_address (const nat_upnp_context_t *ctx, char *addr, size_t addr_len)
	Get the public address (IP:port) for advertising to clients.

Detailed Description

UPnP/NAT-PMP port mapping for TCP and UDP connectivity.

Requests router mappings for TCP listeners and UDP transports. Mapping success does not prove Internet reachability (for example, behind another NAT). The owner must refresh the lease and close the mapping on shutdown.

Author

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

Date

January 2026

Definition in file upnp.h.

Macro Definition Documentation

NETWORK_NAT_UPNP_DESCRIPTION_BUFFER_SIZE

#define NETWORK_NAT_UPNP_DESCRIPTION_BUFFER_SIZE   128

Definition at line 21 of file upnp.h.

NETWORK_NAT_UPNP_DEVICE_DESCRIPTION_BUFFER_SIZE

#define NETWORK_NAT_UPNP_DEVICE_DESCRIPTION_BUFFER_SIZE   256

Definition at line 18 of file upnp.h.

NETWORK_NAT_UPNP_EXTERNAL_IP_BUFFER_SIZE

#define NETWORK_NAT_UPNP_EXTERNAL_IP_BUFFER_SIZE   16

Definition at line 17 of file upnp.h.

NETWORK_NAT_UPNP_INTERNAL_IP_BUFFER_SIZE

#define NETWORK_NAT_UPNP_INTERNAL_IP_BUFFER_SIZE   16

Definition at line 19 of file upnp.h.

NETWORK_NAT_UPNP_SERVICE_TYPE_BUFFER_SIZE

#define NETWORK_NAT_UPNP_SERVICE_TYPE_BUFFER_SIZE   128

Definition at line 20 of file upnp.h.

Typedef Documentation

nat_upnp_context_t

typedef struct nat_upnp_context nat_upnp_context_t

Handle to UPnP context.

Enumeration Type Documentation

nat_upnp_protocol_t

enum nat_upnp_protocol_t

Enumerator
NAT_UPNP_TCP
NAT_UPNP_UDP

Definition at line 27 of file upnp.h.

{ NAT_UPNP_TCP, NAT_UPNP_UDP } nat_upnp_protocol_t;

Function Documentation

nat_upnp_close()

void nat_upnp_close

(

nat_upnp_context_t **

ctx

)

Close port mapping and clean up.

Removes the port mapping from the gateway and frees resources. Safe to call with NULL.

Parameters

ctx	Context handle (will be set to NULL on return)

Definition at line 251 of file upnp.c.

                                              {
  ASCII_OTEL_SCOPE(NAT_CLOSE);
 
  if (!ctx || !*ctx) {
    return;
  }
  if ((*ctx)->is_mapped) {
    asciichat_error_t error = ERROR_NETWORK;
#if defined(__APPLE__) && defined(HAVE_MINIUPNPC)
    if ((*ctx)->is_natpmp) {
      error = natpmp_map(*ctx, 0, false);
    } else
#endif
    {
#ifdef HAVE_MINIUPNPC
      char port[PORT_STRING_BUFFER_SIZE];
      safe_snprintf(port, sizeof(port), "%u", (*ctx)->mapped_port);
      int result =
          UPNP_DeletePortMapping((*ctx)->control_url, (*ctx)->service_type, port, mapping_protocol(*ctx), NULL);
      // Fios gateways require an explicit wildcard when deleting an unrestricted mapping.
      if (result == 402) {
        result = UPNP_DeletePortMapping((*ctx)->control_url, (*ctx)->service_type, port, mapping_protocol(*ctx), "*");
      }
      if (result != UPNPCOMMAND_SUCCESS && result != 714) {
        log_debug("UPnP: deletion failed: %s (%d)", strupnperror(result), result);
      }
      // An already expired mapping needs no further cleanup.
      error = (result == UPNPCOMMAND_SUCCESS || result == 714) ? ASCIICHAT_OK : ERROR_NETWORK;
#endif
    }
    if (error != ASCIICHAT_OK) {
      log_warn("NAT: could not remove mapping for port %u; its lease will expire", (*ctx)->mapped_port);
    } else {
      log_info("NAT: removed mapping for port %u", (*ctx)->mapped_port);
    }
  }
  SAFE_FREE((*ctx)->control_url);
  SAFE_FREE(*ctx);
  *ctx = NULL;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ERROR_NETWORK, log_debug, log_info, log_warn, PORT_STRING_BUFFER_SIZE, SAFE_FREE, and safe_snprintf().

Referenced by mcp_http_run(), and session_server_like_run().

nat_upnp_get_address()

asciichat_error_t nat_upnp_get_address	(	const nat_upnp_context_t *	ctx,
		char *	addr,
		size_t	addr_len )

Get the public address (IP:port) for advertising to clients.

Useful for ACDS registration where we need to advertise the public endpoint for P2P connections.

Parameters

	ctx	Context handle
[out]	addr	Buffer to write "IP:port" format (must be at least 22 bytes)
	addr_len	Size of addr buffer

Returns

ASCIICHAT_OK if successfully written

ERROR_INVALID_PARAM if addr is too small

Definition at line 343 of file upnp.c.

                                                                                                   {
  if (!ctx || !addr || addr_len < 22) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: invalid arguments for get_address");
  }
  if (!nat_upnp_is_active(ctx)) {
    return SET_ERRNO(ERROR_NETWORK, "NAT: no unexpired mapping to advertise");
  }
  int written = safe_snprintf(addr, addr_len, "%s:%u", ctx->external_ip, ctx->mapped_port);
  if (written < 0 || (size_t)written >= addr_len) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: address buffer too small");
  }
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, nat_upnp_context::external_ip, nat_upnp_context::mapped_port, nat_upnp_is_active(), safe_snprintf(), and SET_ERRNO.

Referenced by session_server_like_run().

nat_upnp_get_endpoint()

asciichat_error_t nat_upnp_get_endpoint	(	const nat_upnp_context_t *	ctx,
		char *	ip,
		size_t	ip_len,
		uint16_t *	port )

Copy the unexpired mapped IP and external port for discovery advertisement.

Definition at line 304 of file upnp.c.

                                                                                                                {
  if (!ctx || !ip || !port || ip_len < sizeof(ctx->external_ip)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: invalid endpoint output");
  }
  if (!nat_upnp_is_active(ctx)) {
    return SET_ERRNO(ERROR_NETWORK, "NAT: no unexpired mapping to advertise");
  }
  SAFE_STRNCPY(ip, ctx->external_ip, ip_len);
  *port = ctx->mapped_port;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, nat_upnp_context::external_ip, nat_upnp_context::mapped_port, nat_upnp_is_active(), SAFE_STRNCPY, and SET_ERRNO.

nat_upnp_is_active()

bool nat_upnp_is_active

(

const nat_upnp_context_t *

ctx

)

Check if port mapping is still active.

Checks the locally tracked lease; does not probe Internet reachability.

Parameters

ctx	Context handle

Returns

true if the locally tracked mapping lease has not expired

Definition at line 292 of file upnp.c.

                                                       {
  return ctx && ctx->is_mapped && ctx->external_ip[0] && time_get_ns() < ctx->expires_at_ns;
}

References nat_upnp_context::expires_at_ns, nat_upnp_context::external_ip, and nat_upnp_context::is_mapped.

Referenced by nat_upnp_get_address(), nat_upnp_get_endpoint(), nat_upnp_refresh(), and session_server_like_run().

nat_upnp_matches_bind_address()

bool nat_upnp_matches_bind_address	(	const nat_upnp_context_t *	ctx,
		const char *	bind_address )

Whether the mapping targets a specific IPv4 bind address, or any wildcard listener.

Definition at line 296 of file upnp.c.

                                                                                            {
  if (!ctx) {
    return false;
  }
  return !bind_address || !bind_address[0] || strcmp(bind_address, "0.0.0.0") == 0 ||
         (ctx->internal_ip[0] && strcmp(bind_address, ctx->internal_ip) == 0);
}

References nat_upnp_context::internal_ip.

Referenced by session_server_like_run().

nat_upnp_open()

asciichat_error_t nat_upnp_open	(	uint16_t	internal_port,
		const char *	description,
		nat_upnp_context_t **	ctx )

Discover and open port via UPnP.

Attempts to find an UPnP-enabled gateway and request port mapping. On success, fills in external_ip and mapped_port.

Parameters

	internal_port	Local TCP port to map (e.g., 27224 for ACDS)
	description	Description for port mapping (e.g., "ascii-chat Server")
[out]	ctx	Context handle (must be freed with nat_upnp_close())

Returns

ASCIICHAT_OK if port was successfully mapped

ERROR_NETWORK_* if discovery or mapping failed (does not determine listener reachability)

Example:

nat_upnp_context_t *ctx = NULL;
asciichat_error_t result = nat_upnp_open(27224, "ascii-chat Server", &ctx);
if (result == ASCIICHAT_OK && ctx) {
    printf("Public IP: %s\n", ctx->external_ip);
    // Advertise ctx->external_ip:ctx->mapped_port to ACDS
}

Definition at line 203 of file upnp.c.

                                                                                                           {
  return nat_upnp_open_protocol(internal_port, description, NAT_UPNP_TCP, ctx);
}

References nat_upnp_open_protocol(), and NAT_UPNP_TCP.

Referenced by mcp_http_run(), and session_server_like_run().

nat_upnp_open_protocol()

asciichat_error_t nat_upnp_open_protocol	(	uint16_t	internal_port,
		const char *	description,
		nat_upnp_protocol_t	protocol,
		nat_upnp_context_t **	ctx )

Open an owned TCP or UDP mapping; close with nat_upnp_close().

Definition at line 207 of file upnp.c.

                                                                   {
  ASCII_OTEL_SCOPE(NAT_MAP);
  ASCII_OTEL_ATTR_STRING("network.transport", protocol == NAT_UPNP_UDP ? "udp" : "tcp");
  ASCII_OTEL_ATTR_INT("network.local.port", internal_port);
  if (!ctx) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: missing mapping output");
  }
  *ctx = NULL;
  if (!internal_port || !description || (protocol != NAT_UPNP_TCP && protocol != NAT_UPNP_UDP)) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: a listening port and description are required");
  }
  *ctx = SAFE_CALLOC(1, sizeof(nat_upnp_context_t), nat_upnp_context_t *);
  if (!*ctx) {
    return SET_ERRNO(ERROR_MEMORY, "NAT: could not allocate mapping context");
  }
  (*ctx)->protocol = protocol;
  (*ctx)->internal_port = internal_port;
  (*ctx)->mapped_port = internal_port;
  SAFE_STRNCPY((*ctx)->description, description, sizeof((*ctx)->description));
  log_info("UPnP: discovering a gateway for %s port %u", protocol == NAT_UPNP_UDP ? "UDP" : "TCP", internal_port);
  asciichat_errno_scope_t mapping_scope = errno_scope_begin();
  asciichat_error_t result = upnp_try_map_port(*ctx);
#if defined(__APPLE__) && defined(HAVE_MINIUPNPC)
  if (result != ASCIICHAT_OK) {
    log_debug("UPnP unavailable; trying NAT-PMP");
    result = natpmp_map(*ctx, MAPPING_LEASE_SECONDS, true);
  }
#endif
  if (result == ASCIICHAT_OK) {
    ascii_otel_metric(ASCII_OTEL_METRIC_NAT_MAP_SUCCESS, 1);
    errno_scope_end(mapping_scope, ASCIICHAT_ERRNO_HANDLED);
    log_info("NAT: mapping created for %s:%u (external reachability unverified)", (*ctx)->external_ip,
             (*ctx)->mapped_port);
    return ASCIICHAT_OK;
  }
  ascii_otel_metric(ASCII_OTEL_METRIC_NAT_MAP_FAILURE, 1);
  LOG_ERRNO_IF_SET("Automatic router mapping unavailable");
  SAFE_FREE((*ctx)->control_url);
  SAFE_FREE(*ctx);
  *ctx = NULL;
  return SET_ERRNO(ERROR_NETWORK, "NAT: automatic mapping unavailable; direct connectivity may still work");
}

References ASCII_OTEL_ATTR_INT, ASCII_OTEL_ATTR_STRING, ascii_otel_metric(), ASCII_OTEL_SCOPE, ASCIICHAT_ERRNO_HANDLED, ASCIICHAT_OK, errno_scope_begin(), errno_scope_end(), ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, log_debug, LOG_ERRNO_IF_SET, log_info, MAPPING_LEASE_SECONDS, NAT_UPNP_TCP, NAT_UPNP_UDP, SAFE_CALLOC, SAFE_FREE, SAFE_STRNCPY, and SET_ERRNO.

Referenced by nat_upnp_open().

nat_upnp_refresh()

asciichat_error_t nat_upnp_refresh

(

nat_upnp_context_t *

ctx

)

Refresh port mapping (e.g., for long-running servers).

Call from one owning thread when refresh_at_ns is reached. Renewal is scheduled halfway through the lease; failures schedule a bounded retry.

Parameters

ctx	Context handle

Returns

ASCIICHAT_OK if refresh succeeded

Definition at line 316 of file upnp.c.

                                                            {
  ASCII_OTEL_SCOPE(NAT_REFRESH);
 
  if (!ctx || !ctx->is_mapped) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: cannot refresh without a mapping");
  }
  asciichat_error_t result = ERROR_NETWORK;
#if defined(__APPLE__) && defined(HAVE_MINIUPNPC)
  if (ctx->is_natpmp) {
    result = natpmp_map(ctx, MAPPING_LEASE_SECONDS, false);
  } else
#endif
  {
#ifdef HAVE_MINIUPNPC
    result = upnp_map(ctx);
#endif
  }
  if (result != ASCIICHAT_OK) {
    ctx->refresh_at_ns = time_get_ns() + MAPPING_RETRY_NS;
    log_warn("NAT: mapping renewal failed; %s; retrying in 30 seconds",
             nat_upnp_is_active(ctx) ? "previous lease has not expired" : "mapping lease expired");
    return result;
  }
  log_info("NAT: mapping renewed for %s:%u", ctx->external_ip, ctx->mapped_port);
  return ASCIICHAT_OK;
}

References ASCII_OTEL_SCOPE, ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_NETWORK, nat_upnp_context::external_ip, nat_upnp_context::is_mapped, nat_upnp_context::is_natpmp, log_info, log_warn, nat_upnp_context::mapped_port, MAPPING_LEASE_SECONDS, MAPPING_RETRY_NS, nat_upnp_is_active(), nat_upnp_context::refresh_at_ns, and SET_ERRNO.

Referenced by mcp_http_run().