upnp.h File Reference

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

Go to the source code of this file.

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

Typedefs
typedef struct nat_upnp_context	nat_upnp_context_t
	Handle to UPnP context.

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.
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.
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 direct TCP connectivity.

Enables automatic port forwarding on home routers using UPnP/NAT-PMP, making direct TCP connections work for ~70% of home users without WebRTC.

Quick Win Strategy:

• Try UPnP first (works on ~90% of home routers)
• Fall back to NAT-PMP (Apple/Time Capsule)
• If both fail, client connects via ACDS discovery + WebRTC

Author

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

Date

January 2026

Definition in file upnp.h.

Typedef Documentation

nat_upnp_context_t

typedef struct nat_upnp_context nat_upnp_context_t

Handle to UPnP context.

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 276 of file upnp.c.

                                              {
  if (!ctx || !(*ctx)) {
    return;
  }
 
  if ((*ctx)->is_mapped) {
    // Note: In a real implementation, we'd remove the port mapping from the gateway.
    // For MVP, we just log and let the lease expire naturally (typically 1 hour).
    log_debug("NAT: Port mapping will expire in ~1 hour (cleanup handled by router)");
  }
 
  SAFE_FREE(*ctx);
  *ctx = NULL;
}

References log_debug, and SAFE_FREE.

Referenced by 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 310 of file upnp.c.

                                                                                                   {
  if (!ctx || !addr || addr_len < 22) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: Invalid arguments for get_address");
  }
 
  if (!ctx->is_mapped || ctx->external_ip[0] == '\0') {
    return SET_ERRNO(ERROR_NETWORK, "NAT: No active mapping to advertise");
  }
 
  // Format as "IP:port" (e.g., "203.0.113.42:27224")
  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::is_mapped, nat_upnp_context::mapped_port, safe_snprintf(), and SET_ERRNO.

Referenced by nat_detect_quality(), and session_server_like_run().

nat_upnp_is_active()

bool nat_upnp_is_active

(

const nat_upnp_context_t *

ctx

)

Check if port mapping is still active.

Useful for long-running servers to verify the mapping hasn't expired.

Parameters

ctx	Context handle

Returns

true if port is still mapped on the gateway

Definition at line 291 of file upnp.c.

                                                       {
  if (!ctx) {
    return false;
  }
  return ctx->is_mapped && ctx->external_ip[0] != '\0';
}

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

Referenced by nat_detect_quality().

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 (not fatal, fallback to WebRTC)

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 236 of file upnp.c.

                                                                                                           {
  if (!ctx || !description) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "nat_upnp_open: Invalid arguments");
  }
 
  // Allocate context
  *ctx = SAFE_MALLOC(sizeof(nat_upnp_context_t), nat_upnp_context_t *);
  if (!(*ctx)) {
    return ERROR_MEMORY;
  }
 
  memset(*ctx, 0, sizeof(nat_upnp_context_t));
 
  // Try UPnP first (works on ~90% of home routers)
  log_info("NAT: Attempting UPnP port mapping for port %u...", internal_port);
  asciichat_error_t result = upnp_try_map_port(internal_port, description, *ctx);
 
  if (result == ASCIICHAT_OK) {
    log_info("NAT: ✓ UPnP port mapping successful!");
    return ASCIICHAT_OK;
  }
 
  log_info("NAT: UPnP failed, trying NAT-PMP fallback...");
  result = natpmp_try_map_port(internal_port, *ctx);
 
  if (result == ASCIICHAT_OK) {
    log_info("NAT: ✓ NAT-PMP port mapping successful!");
    return ASCIICHAT_OK;
  }
 
  // Both UPnP and NAT-PMP failed - this is OK, not fatal
  log_warn("NAT: Both UPnP and NAT-PMP failed. Direct TCP won't work, will use ACDS + WebRTC.");
  log_warn("NAT: This is normal for strict NATs. No action required.");
 
  SAFE_FREE(*ctx);
  *ctx = NULL;
 
  return SET_ERRNO(ERROR_NETWORK, "NAT: No automatic port mapping available (will use WebRTC)");
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, ERROR_MEMORY, ERROR_NETWORK, log_info, log_warn, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.

Referenced by nat_detect_quality(), and session_server_like_run().

nat_upnp_refresh()

asciichat_error_t nat_upnp_refresh

(

nat_upnp_context_t *

ctx

)

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

Some gateways may expire mappings. Call periodically (e.g., every hour) to ensure the mapping stays active.

Parameters

ctx	Context handle

Returns

ASCIICHAT_OK if refresh succeeded

Definition at line 298 of file upnp.c.

                                                            {
  if (!ctx || !ctx->is_mapped) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "NAT: Cannot refresh - no active mapping");
  }
 
  log_debug("NAT: Refreshing port mapping (would extend lease in full implementation)");
 
  // In a real implementation, we'd re-register the port mapping to extend the lease.
  // For now, we just return success since the lease is 1 hour anyway.
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, ERROR_INVALID_PARAM, nat_upnp_context::is_mapped, log_debug, and SET_ERRNO.