NAT Traversal Patterns

// NAT mapping example:
// Home network: 192.168.1.0/24, public IP: 203.0.113.5
//
// Device A (192.168.1.10) opens connection to Google (142.250.80.36:443):
// → NAT creates mapping: 192.168.1.10:54321 ↔ 203.0.113.5:45001
// → Packet arrives at Google with src=203.0.113.5:45001
// ← Google replies to 203.0.113.5:45001 → NAT translates → 192.168.1.10:54321 ✓

// Peer-to-Peer problem:
// Peer A: 192.168.1.10 (behind NAT: 203.0.113.5)
// Peer B: 10.0.0.20  (behind NAT: 198.51.100.7)
//
// A tries to connect to B directly:
// A knows B's private IP (10.0.0.20) → not reachable from internet
// A knows B's public IP (198.51.100.7) → but which port? NAT table unknown
// B's NAT drops inbound packets from A — no matching outbound mapping exists
//
// Neither peer can initiate → connection impossible without traversal

// STUN request/response:
// Client (192.168.1.10:54321) → STUN server (stun.l.google.com:19302)
// STUN Binding Request (UDP)
//   "What is my public IP:port as you see it?"

// STUN Response:
// XOR-MAPPED-ADDRESS: 203.0.113.5:45001
//   ← This is what the internet sees when A sends from 192.168.1.10:54321

// After STUN:
// Peer A knows: public=203.0.113.5:45001, private=192.168.1.10:54321
// Peer B knows: public=198.51.100.7:62345, private=10.0.0.20:54321
// A and B exchange this info via signalling server (WebSocket/HTTP)

// UDP Hole Punching (works for full-cone and address-restricted NATs):
// Both A and B send UDP packets to each other's public IP:port simultaneously
// A → 198.51.100.7:62345  (creates NAT mapping on A's NAT)
// B → 203.0.113.5:45001   (creates NAT mapping on B's NAT)
// Second packet from each side passes through the now-open NAT mapping
// Direct UDP connection established!

// TURN — when hole punching fails (symmetric NAT):
// Both peers connect to TURN server, relay traffic through it:
//
// Peer A (behind symmetric NAT)
//   └──▶ TURN server (turn.aicancode.org:3478)
//              └──▶ Peer B (behind symmetric NAT)
//
// TURN allocate flow:
// 1. A sends Allocate Request to TURN server (with credentials)
// 2. TURN creates a relay address: 203.0.113.100:49152
// 3. A sends relay address to B via signalling
// 4. B connects to TURN relay address
// 5. All A↔B traffic relayed through TURN

// Cost: TURN relay uses bandwidth on your server — expensive at scale
// Mitigation: only use TURN when direct/STUN path fails (ICE selects best path)

// Self-hosted TURN server (coturn):
// turnserver --listening-port 3478 --realm aicancode.org
//   --user username:password --lt-cred-mech

// ICE candidate types (gathered by WebRTC):
// host candidate:       192.168.1.10:54321  ← direct (LAN only)
// srflx candidate:      203.0.113.5:45001   ← server-reflexive (STUN)
// relay candidate:      203.0.113.100:49152 ← TURN relay

// ICE connectivity checks — try all pairs simultaneously:
// (A host ↔ B host)   → fails (different NATs)
// (A srflx ↔ B srflx) → try UDP hole punch simultaneously
//   A → B public: creates A's NAT mapping
//   B → A public: creates B's NAT mapping → SUCCESS → direct path!
// (A relay ↔ B relay) → always works but slowest → used if above fail

// WebRTC ICE (JavaScript):
const pc = new RTCPeerConnection({
  iceServers: [
    { urls: 'stun:stun.l.google.com:19302' },               // STUN
    { urls: 'turn:turn.aicancode.org:3478',                 // TURN
      username: 'user', credential: 'pass' }
  ]
})
pc.onicecandidate = e => {
  if (e.candidate) signalingServer.send(e.candidate)  // exchange via signalling
}
// WebRTC handles hole punching, candidate pairing, and path selection automatically