Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

15.5 KB
Raw Blame
/**
 * Picks ONE reachable STUN server out of the list the backend hands us, by racing them all at once
 * with a raw RFC 5389 Binding Request and putting the first one that answers at the front.
 *
 * This exists because werift does not do STUN failover and never did. `parseIceServers()`
 * (werift/lib/webrtc/src/utils.js:96) folds the whole `iceServers` array into a SINGLE `stunServer`
 * — `if (!options.stunServer && parsed.kind === "stun") options.stunServer = parsed.address` — so the
 * first `stun:` url wins and every url behind it is dropped without a word. Measured on werift 0.24.4
 * against a blackholed first entry (198.51.100.1) with two live servers behind it: ZERO srflx
 * candidates, and gathering stalled 5.0s on werift's gather timeout instead of finishing in ~60ms.
 * Both halves hurt. We do not trickle ICE (nothing subscribes to onIceCandidate; the candidates ride
 * in the SDP because `setLocalDescription` awaits `gatherCandidates()`), so that 5s is paid on the
 * initiator AND again on the responder, inside one 10s TERMINAL_P2P_NEGOTIATION_TIMEOUT_MS budget. A
 * single dead STUN server therefore does not merely lose srflx — it blows the whole negotiation.
 *
 * The peers do NOT have to agree on a server: a srflx candidate answers "what is my own public
 * address", so each side may ask whoever it likes. That is why nothing here touches the wire format —
 * `p2p_offer` keeps carrying the raw policy list and the responder races it independently.
 *
 * Two properties are load-bearing and must survive any edit:
 *   - `select()` NEVER rejects. It runs inside a long-lived daemon; an unhandled rejection here kills
 *     the process. Every failure path degrades to "return the list exactly as given", which is
 *     byte-for-byte today's behaviour — the cheapest possible proof this can never be worse.
 *   - A list of 0 or 1 urls is returned untouched with no probe at all. Production currently ships a
 *     single STUN url, so this module is provably a no-op there until the backend ships a longer one.
 */
import { randomBytes } from 'node:crypto'
import dgram from 'node:dgram'
import { lookup } from 'node:dns'
import { isIP } from 'node:net'

const STUN_MAGIC_COOKIE = 0x2112a442
const STUN_BINDING_REQUEST = 0x0001
const STUN_BINDING_SUCCESS = 0x0101
const STUN_ATTR_MAPPED_ADDRESS = 0x0001
const STUN_ATTR_XOR_MAPPED_ADDRESS = 0x0020
const STUN_HEADER_BYTES = 20

/** Measured RTT to cloudflare/google STUN is ~117ms, so this is ~3.4x headroom. It is only ever paid
 *  in full when EVERY server is dead — i.e. exactly when p2p was doomed anyway. */
const PROBE_TIMEOUT_MS = 400
/** One retransmit with the same transaction id absorbs a single lost datagram inside that budget. */
const PROBE_RETRANSMIT_MS = 150
const POSITIVE_TTL_MS = 5 * 60_000
/** Short, so a laptop coming off a captive portal heals on its own without any invalidation hook. */
const NEGATIVE_TTL_MS = 30_000

/** Resolves to the winner's IPv4 address, or null if this server did not answer. Never rejects. */
export type StunProbe = (url: string, timeoutMs: number, signal: AbortSignal) => Promise<string | null>

export interface StunSelection {
  /** The input list, winner first. Identical to the input (same order) when nothing answered. */
  urls: string[]
  /**
   * Did ANY configured STUN server answer over UDP?
   *
   * Tri-state on purpose. `null` means "not probed" — a list of 0 or 1 urls short-circuits without
   * sending a packet, so we know nothing either way. Collapsing that into `false` would tell
   * pickTurnUrl() that UDP is blocked on every single-STUN-url deployment and push all of them onto
   * TURN over TLS:443 for no reason.
   */
  udpReachable: boolean | null
}

export type StunSelector = (urls: string[]) => Promise<StunSelection>

export interface StunSelectorOptions {
  probe?: StunProbe
  now?: () => number
  ttlMs?: number
  negativeTtlMs?: number
  probeTimeoutMs?: number
}

interface StunTarget {
  scheme: 'stun' | 'stuns'
  host: string
  port: number
}

interface RaceResult {
  ordered: string[]
  /** false = every server failed, so `ordered` IS the input list and the result is cached briefly. */
  ok: boolean
}

interface CacheEntry {
  ordered: string[]
  ok: boolean
  at: number
}

/** Mirrors `parseIceServerUrl`/`parseAddress` in werift/lib/webrtc/src/utils.js:133-210 on purpose:
 *  disagreeing with werift about which host:port a url means would make the whole race meaningless. */
export function parseStunUrl(url: string): StunTarget | null {
  const matched = /^(stun|stuns):(.+)$/i.exec(url.trim())
  if (!matched) return null
  const scheme = matched[1]!.toLowerCase() as 'stun' | 'stuns'
  const fallbackPort = scheme === 'stuns' ? 5349 : 3478
  const [rest] = matched[2]!.split('?', 1)
  const authority = rest!.startsWith('//') ? rest!.slice(2) : rest!
  if (!authority) return null
  if (authority.startsWith('[')) {
    const closing = authority.indexOf(']')
    if (closing === -1) return null
    return { scheme, host: authority.slice(1, closing), port: parsePort(authority.slice(closing + 1), fallbackPort) }
  }
  const firstColon = authority.indexOf(':')
  const lastColon = authority.lastIndexOf(':')
  if (firstColon !== -1 && firstColon === lastColon) {
    return { scheme, host: authority.slice(0, firstColon), port: parsePort(authority.slice(firstColon + 1), fallbackPort) }
  }
  return { scheme, host: authority, port: fallbackPort }
}

function parsePort(value: string, fallbackPort: number): number {
  const port = Number.parseInt(value.startsWith(':') ? value.slice(1) : value, 10)
  return Number.isFinite(port) ? port : fallbackPort
}

/** Exported so the wire format can be unit-tested without a socket. */
export function buildBindingRequest(): { packet: Buffer; tid: Buffer } {
  const packet = Buffer.alloc(STUN_HEADER_BYTES)
  packet.writeUInt16BE(STUN_BINDING_REQUEST, 0)
  packet.writeUInt16BE(0, 2)
  packet.writeUInt32BE(STUN_MAGIC_COOKIE, 4)
  // Crypto-random, not counter-based: an off-path spoofer must not be able to guess the id and win
  // the race with a forged success response pointing us at a server that never answered.
  const tid = randomBytes(12)
  tid.copy(packet, 8)
  return { packet, tid }
}

/**
 * True only for a success response that carries a well-formed mapped address. That is deliberately
 * the same bar werift's own gathering applies: `serverReflexiveCandidate`
 * (werift/lib/ice/src/iceBase.js:271-288) reads XOR-MAPPED-ADDRESS unconditionally and throws without
 * it, so "answered" alone would be a weaker predicate than "werift will succeed here".
 *
 * The mapped value itself is discarded — our source port differs from werift's by construction; all
 * we are establishing is reachability. Malformed input returns false and never throws.
 */
export function parseBindingResponse(buf: Buffer, tid: Buffer): boolean {
  if (buf.length < STUN_HEADER_BYTES) return false
  if (buf.readUInt16BE(0) !== STUN_BINDING_SUCCESS) return false // also rejects 0x0111 error responses
  if (buf.readUInt32BE(4) !== STUN_MAGIC_COOKIE) return false
  if (!buf.subarray(8, STUN_HEADER_BYTES).equals(tid)) return false
  if (buf.readUInt16BE(2) !== buf.length - STUN_HEADER_BYTES) return false
  let off = STUN_HEADER_BYTES
  while (off + 4 <= buf.length) {
    const type = buf.readUInt16BE(off)
    const len = buf.readUInt16BE(off + 2)
    if (off + 4 + len > buf.length) return false
    if (type === STUN_ATTR_XOR_MAPPED_ADDRESS || type === STUN_ATTR_MAPPED_ADDRESS) {
      const family = buf.readUInt8(off + 5)
      if ((family === 0x01 && len === 8) || (family === 0x02 && len === 20)) return true
    }
    off += 4 + len + ((4 - (len % 4)) % 4)
  }
  return false
}

/** werift resolves STUN hosts as IPv4 (ice/src/stun/transaction.js:18-24) and only ever gathers srflx
 *  from IPv4 host candidates (ice/src/ice.js:861), so probing anything else would measure a path it
 *  cannot use. Note stun.cloudflare.com is dual-stack, so an unqualified lookup can hand back AAAA. */
function resolveIpv4(host: string, done: (address: string | null) => void): void {
  const literal = isIP(host)
  if (literal === 4) { done(host); return }
  if (literal === 6) { done(null); return }
  lookup(host, { family: 4 }, (err, address) => done(err ? null : address))
}

const probeStun: StunProbe = (url, timeoutMs, signal) => {
  const target = parseStunUrl(url)
  // stuns: is STUN-over-TLS/TCP. werift asks over UDP, so such an entry is unusable there anyway and
  // a UDP probe could not measure it honestly either.
  if (!target || target.scheme !== 'stun') return Promise.resolve(null)
  return new Promise<string | null>((resolve) => {
    if (signal.aborted) { resolve(null); return }
    let socket: dgram.Socket | null = null
    let deadline: ReturnType<typeof setTimeout> | null = null
    let retransmit: ReturnType<typeof setTimeout> | null = null
    let done = false
    const { packet, tid } = buildBindingRequest()

    const finish = (address: string | null): void => {
      if (done) return
      done = true
      if (deadline) clearTimeout(deadline)
      if (retransmit) clearTimeout(retransmit)
      signal.removeEventListener('abort', onAbort)
      try { socket?.close() } catch { /* never opened, or already closed */ }
      resolve(address)
    }
    function onAbort(): void { finish(null) }
    signal.addEventListener('abort', onAbort, { once: true })

    deadline = setTimeout(() => finish(null), timeoutMs)
    deadline.unref?.()

    resolveIpv4(target.host, (address) => {
      if (done) return
      if (!address) { finish(null); return }
      try {
        socket = dgram.createSocket('udp4')
      } catch { finish(null); return }
      // A probe must never be the reason the daemon stays alive.
      socket.unref()
      // Mandatory: a closed port answers with ICMP unreachable, which dgram raises as an 'error'
      // EVENT. Unhandled, that throws out of the event loop and takes the process with it.
      socket.on('error', () => finish(null))
      socket.on('message', (msg) => { if (parseBindingResponse(msg, tid)) finish(address) })
      socket.send(packet, target.port, address, (err) => { if (err) finish(null) })
      retransmit = setTimeout(() => {
        // Errors are ignored here: the first send already succeeded, so a failing retransmit should
        // let the deadline decide rather than cut short a response still in flight.
        if (!done) socket?.send(packet, target.port, address, () => { /* deadline decides */ })
      }, PROBE_RETRANSMIT_MS)
      retransmit.unref?.()
    })
  })
}

/** Only the winner, only for `stun:`, only when it was a name: we measured THAT address, and a host
 *  with several A records could resolve elsewhere inside werift's own lookup, quietly invalidating the
 *  race we just ran. Bounded by the positive TTL; a stale pin costs one slow gather, i.e. today. */
function pinWinner(url: string, address: string): string {
  const target = parseStunUrl(url)
  if (!target || target.scheme !== 'stun' || isIP(target.host)) return url
  return `stun:${address}:${target.port}`
}

export function createStunSelector(opts: StunSelectorOptions = {}): StunSelector {
  const probe = opts.probe ?? probeStun
  const now = opts.now ?? ((): number => Date.now())
  const ttlMs = opts.ttlMs ?? POSITIVE_TTL_MS
  const negativeTtlMs = opts.negativeTtlMs ?? NEGATIVE_TTL_MS
  const probeTimeoutMs = opts.probeTimeoutMs ?? PROBE_TIMEOUT_MS
  const cache = new Map<string, CacheEntry>()
  const pending = new Map<string, Promise<StunSelection>>()

  const race = (urls: string[]): Promise<RaceResult> => new Promise<RaceResult>((resolve) => {
    const controller = new AbortController()
    let settled = false
    let outstanding = urls.length
    const finish = (ordered: string[], ok: boolean): void => {
      if (settled) return
      settled = true
      controller.abort() // closes every losing socket and clears its timers at once
      resolve({ ordered, ok })
    }
    const lost = (): void => { if (--outstanding <= 0) finish(urls, false) }
    urls.forEach((url, index) => {
      let result: Promise<string | null>
      try {
        result = probe(url, probeTimeoutMs, controller.signal)
      } catch {
        lost() // a probe that throws synchronously is just a failed probe
        return
      }
      result.then(
        (address) => {
          if (!address) { lost(); return }
          finish([pinWinner(url, address), ...urls.filter((_, i) => i !== index)], true)
        },
        () => lost(),
      )
    })
  })

  return async (urls) => {
    // Zero or one url: nothing to choose between, so do not spend a single packet deciding. Reachability
    // stays UNKNOWN here rather than false — we never asked.
    if (urls.length <= 1) return { urls, udpReachable: null }
    const key = urls.map((url) => url.trim().toLowerCase()).join(' ')
    const hit = cache.get(key)
    if (hit && now() - hit.at < (hit.ok ? ttlMs : negativeTtlMs)) {
      return { urls: hit.ordered, udpReachable: hit.ok }
    }
    const inflight = pending.get(key)
    if (inflight) return inflight
    const run = race(urls)
      .then(({ ordered, ok }) => {
        cache.set(key, { ordered, ok, at: now() })
        return { urls: ordered, udpReachable: ok }
      })
      .catch(() => ({ urls, udpReachable: null })) // the contract is that this function never rejects
      .finally(() => { pending.delete(key) })
    pending.set(key, run)
    return run
  }
}

/**
 * Which of Cloudflare's five TURN urls to hand werift — it reads only the FIRST `turn:` entry
 * (webrtc/src/utils.js parseIceServers) and never falls over to the rest, exactly like the STUN bug
 * this module already works around. Its own udp→tcp retry stays on port 3478, which a network that
 * drops UDP usually blocks too, so the 443 choice has to be made here.
 *
 * The STUN race already answered the only question that matters — does UDP leave this host — so this
 * costs no extra packets. Both misreads are safe: guessing "blocked" merely picks the slower TLS path
 * (measured 404ms vs 115ms to allocate), and guessing "open" falls back to werift's own tcp retry.
 */
export function pickTurnUrl(turnUrls: string[], udpReachable: boolean | null): string | null {
  const usable = turnUrls.filter((url) => /^turns?:/i.test(url.trim()))
  if (usable.length === 0) return null
  if (udpReachable === false) {
    const tls = usable.find((url) => /^turns:/i.test(url.trim()) && parseStunUrlPort(url) === 443)
      ?? usable.find((url) => /^turns:/i.test(url.trim()))
    if (tls) return tls
  }
  if (udpReachable === true) {
    const udp = usable.find((url) => /[?&]transport=udp/i.test(url))
    if (udp) return udp
  }
  // Unknown, or the list carries no url of the preferred kind: behave exactly like werift does today.
  return usable[0] ?? null
}

function parseStunUrlPort(url: string): number | null {
  const match = /^turns?:(?:\/\/)?([^?]+)/i.exec(url.trim())
  if (!match) return null
  const authority = match[1]!
  const lastColon = authority.lastIndexOf(':')
  if (lastColon === -1 || authority.indexOf(':') !== lastColon) return null
  const port = Number.parseInt(authority.slice(lastColon + 1), 10)
  return Number.isFinite(port) ? port : null
}

/** Process-wide selector: one shared cache, so a warm-up on one relay pays for every later peer. */
export const selectStunUrls: StunSelector = createStunSelector()

/** Fire-and-forget: start the race the moment the url list is known, so its cost hides behind the
 *  round trip that follows. Callers join the same in-flight promise; nothing waits on this. */
export function warmStunUrls(urls: string[]): void {
  void selectStunUrls(urls).catch(() => { /* selectStunUrls never rejects; this is belt and braces */ })
}