Module protocol_holepunch 

NAT Hole Punching Protocol (QUIC-only)

This protocol enables direct connections between peers behind NATs by using existing connected peers as signaling relays. It is restricted to QUIC because QUIC’s single-socket design allows the dialer and listener to share the same port, which is essential for NAT traversal. NAT hole punching protocol (QUIC-only)

1. Peer A wants to connect to peer C (both behind NATs)
2. A finds mutual peer B connected to both
3. A sends HolepunchRequest to B
4. B sends HolepunchConnect to both A and C with synchronized timing
5. A and C simultaneously connect to each other’s observed addresses

Structs

HolepunchConnect

Instruction to attempt a holepunch connection

HolepunchRequest

Request a peer to relay a holepunch

HolepunchResult

Result of a holepunch attempt

ProtocolHolepunch

UsedNonce 🔒

Constants

ALLOWED_SCHEME 🔒

CONNECT_VALIDITY_MS 🔒

Maximum time window in ms for a connection instruction to be valid.

COORDINATION_DELAY_MS 🔒

Delay before simultaneous connection attempt in ms

HOLEPUNCH_MAX_BYTES

HOLEPUNCH_METERING

MAX_CLOCK_SKEW_MS 🔒

Maximum clock skew allowed between peers in ms

MAX_PENDING_PER_PEER 🔒

Maximum pending holepunch requests per peer IP

NONCE_EXPIRY_SECS 🔒

Nonce expiry time for replay protection

PROTO_NAME 🔒

Statics

INITIATOR_NONCES 🔒

Tracks nonces for active initiate_punch() calls.