upnp.c File Reference

UPnP/NAT-PMP port mapping implementation. More...

Go to the source code of this file.

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 implementation.

Strategy for enabling direct TCP without WebRTC:

1. Try UPnP discovery (works on ~90% of consumer routers)
2. Fall back to NAT-PMP if UPnP fails (Apple/Time Capsule)
3. If both fail, client falls back to ACDS + WebRTC

This pragmatic approach provides direct connectivity for most home users while maintaining compatibility with stricter NATs via WebRTC fallback.

Definition in file upnp.c.

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 289 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 main().

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 323 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 = 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, and SET_ERRNO.

Referenced by main(), and server_main().

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 304 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.

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 249 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, description, *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 main(), and server_main().

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 311 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.