cc0/net/stun.sg implements STUN RFC 5389 Binding Request/Response in cc0 — discovering a peer's external IP:port via XOR-MAPPED-ADDRESS. This unblocks Tier-2 hole-punch in the SRDX ICE stack: both SRDX peers exchange their external addresses, attempt a direct UDP connection, and only fall back to relay if the punch fails. 5 QEMU tests PASS.
Protocol and SRDX integration
STUN Binding Request/
Response (RFC 5389 subset)
Response (RFC 5389 subset)
STUN Binding Request/Response (RFC 5389 subset)
The implementation covers the RFC 5389 Binding subset only — the minimal footprint for NAT traversal: Binding Request (message type0x0001) and Binding Success Response (message type 0x0101). stun_query(conn, server_ip, server_port): sends a Binding Request to the STUN server at server_ip:server_port over Cap<NetConn> UDP. The STUN message header is 20 bytes: 2B message type, 2B length, 4B magic cookie (0x2112A442), 12B transaction ID. stun_recv_response(conn): receives the Binding Response; parses the XOR-MAPPED-ADDRESS attribute (attribute type 0x0020) — XOR-decodes the IP (XOR with magic cookie) and port (XOR with high 16 bits of magic cookie) to recover the external IP:port. Returns (ext_ip, ext_port). Loopback stub rings: separate send/recv ring buffers used in QEMU test mode to simulate the STUN server response without a real network.
SRDX ICE Tier-2
hole-punch integration
hole-punch integration
SRDX ICE Tier-2 hole-punch integration
The SRDX network stack has three connectivity tiers: Tier-1 = direct LAN (same subnet, no NAT), Tier-2 = UDP hole-punch (peers behind NAT, direct UDP possible if both punch simultaneously), Tier-3 = relay (SRDX relay broadcast,srdx_relay_bcast.sg). stun.sg unblocks Tier-2: each SRDX peer calls stun_query() to learn its external IP:port, exchanges that address with its counterpart (via the relay as a signalling channel), then both peers send UDP packets to each other's external address simultaneously — the NAT mappings open on both sides, allowing a direct connection. If the hole-punch fails (no response within a timeout), SRDX falls back to Tier-3 relay. This gives sigilOS SRDX direct peer-to-peer connectivity across NAT without requiring port forwarding.