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.

7.2 KB
Raw Blame
/**
 * Cloudflare Realtime TURN credentials, minted once and served from memory.
 *
 * READ THIS BEFORE MAKING ANY OF IT ASYNC. The snapshot getter is synchronous on purpose, because the
 * only consumer — `terminalP2pPolicy()` — is called from three places that each reject an await for a
 * different reason:
 *   - `webWs.ts` `ack()`: awaiting IS safe there (frames are serialised through `frameChain`), but it
 *     would put a Cloudflare round trip in the middle of every `machine_select` and would need a fresh
 *     `selectGen` staleness re-check afterwards. Latency for no benefit.
 *   - `webWs.ts` per-frame signaling gate: an await there sits IN FRONT of the rate limiter and the
 *     size check, so a flood of `p2p_ice_candidate` frames would each hold the chain open uncounted.
 *   - `adapterWs.ts` gate: `onMessage` is a synchronous `void` arrow, adapterWs has no frame
 *     serialisation at all, and it replays a buffered queue in order at attach. Cannot await, period.
 *
 * So: a background refresh keeps a snapshot warm and every read is a property lookup. The credential
 * is account-wide rather than per-user (Cloudflare does not scope it to our users), so one snapshot
 * shared by every worker is correct — unlike bus.ts, which needs Redis because ITS values are
 * per-machine and the worker that wrote one is rarely the worker that reads it. Four cluster workers
 * minting four credentials every couple of hours is far cheaper than putting Redis in the path of
 * something that must degrade quietly.
 *
 * Every failure degrades to `null`, which the policy renders as STUN-only — the exact behaviour we
 * shipped before TURN existed. Nothing here ever throws.
 */
import { env } from '../config/env.js'
import { logger } from '../utils/logger.js'

export interface TurnCredentials {
  urls: string[]
  username: string
  credential: string
}

interface Snapshot {
  credentials: TurnCredentials
  /** Epoch ms after which the credential must not be handed out any more. */
  expiresAt: number
}

export interface TurnCredentialDeps {
  now?: () => number
  fetchImpl?: typeof fetch
}

/** Refresh once the credential is more than three quarters through its lifetime. */
const REFRESH_AT_REMAINING = 0.25
/** After a failure, do not hammer Cloudflare on every tick. */
const RETRY_AFTER_MS = 60_000
const CLOUDFLARE_TURN_API = 'https://rtc.live.cloudflare.com/v1/turn/keys'

let snapshot: Snapshot | null = null
let inflight: Promise<Snapshot | null> | null = null
let nextAttemptAt = 0
let timer: ReturnType<typeof setInterval> | null = null

function configured(): boolean {
  return !!env.TERMINAL_P2P_TURN_KEY_ID && !!env.TERMINAL_P2P_TURN_API_TOKEN
}

function parseIceServers(body: unknown): TurnCredentials | null {
  if (!body || typeof body !== 'object') return null
  const servers = (body as { iceServers?: unknown }).iceServers
  if (!Array.isArray(servers)) return null
  for (const entry of servers) {
    if (!entry || typeof entry !== 'object') continue
    const { urls, username, credential } = entry as Record<string, unknown>
    if (typeof username !== 'string' || !username) continue
    if (typeof credential !== 'string' || !credential) continue
    const list = (Array.isArray(urls) ? urls : [urls])
      .filter((url): url is string => typeof url === 'string' && /^turns?:/i.test(url))
    if (list.length > 0) return { urls: list, username, credential }
  }
  return null
}

async function mint(deps: Required<TurnCredentialDeps>): Promise<Snapshot | null> {
  const ttl = env.TERMINAL_P2P_TURN_TTL_SECONDS
  let response: Response
  try {
    response = await deps.fetchImpl(
      `${CLOUDFLARE_TURN_API}/${env.TERMINAL_P2P_TURN_KEY_ID}/credentials/generate-ice-servers`,
      {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${env.TERMINAL_P2P_TURN_API_TOKEN}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ ttl }),
        signal: AbortSignal.timeout(env.TERMINAL_P2P_TURN_TIMEOUT_MS),
      },
    )
  } catch (err) {
    logger.warn('turn credential request failed', { error: String(err) })
    return null
  }
  if (!response.ok) {
    const detail = await response.text().catch(() => '')
    logger.warn('turn credential rejected', { status: response.status, detail: detail.slice(0, 200) })
    return null
  }
  let body: unknown
  try {
    body = await response.json()
  } catch {
    logger.warn('turn credential response was not json')
    return null
  }
  const credentials = parseIceServers(body)
  if (!credentials) {
    logger.warn('turn credential response carried no usable turn entry')
    return null
  }
  return { credentials, expiresAt: deps.now() + ttl * 1000 }
}

async function refresh(deps: Required<TurnCredentialDeps>): Promise<Snapshot | null> {
  if (inflight) return inflight
  const run = mint(deps)
    .then((next) => {
      if (next) {
        snapshot = next
        nextAttemptAt = 0
        return next
      }
      // Keep whatever is still valid; a Cloudflare blip must not disable TURN mid-flight.
      nextAttemptAt = deps.now() + RETRY_AFTER_MS
      return snapshot
    })
    .catch(() => snapshot) // mint() already swallows everything; this is belt and braces
    .finally(() => { inflight = null })
  inflight = run
  return run
}

function resolveDeps(deps: TurnCredentialDeps = {}): Required<TurnCredentialDeps> {
  return {
    now: deps.now ?? ((): number => Date.now()),
    fetchImpl: deps.fetchImpl ?? fetch,
  }
}

/** Synchronous snapshot. `null` means "ship a STUN-only policy" — never an error. */
export function turnCredentials(deps: TurnCredentialDeps = {}): TurnCredentials | null {
  if (!configured()) return null
  const { now } = resolveDeps(deps)
  const current = snapshot
  if (!current) {
    // First read before the boot fetch landed (or after a total failure): kick one off and answer
    // STUN-only for now. The next machine_select gets the credential.
    if (now() >= nextAttemptAt) void refresh(resolveDeps(deps))
    return null
  }
  const ttlMs = env.TERMINAL_P2P_TURN_TTL_SECONDS * 1000
  const remaining = current.expiresAt - now()
  if (remaining <= 0) {
    if (now() >= nextAttemptAt) void refresh(resolveDeps(deps))
    return null
  }
  if (remaining < ttlMs * REFRESH_AT_REMAINING && now() >= nextAttemptAt) {
    void refresh(resolveDeps(deps)) // still serving the current one below; this is a background top-up
  }
  return current.credentials
}

/** Boot hook: mint immediately so the first machine_select already has TURN, then top up on a timer. */
export function startTurnCredentialRefresh(deps: TurnCredentialDeps = {}): void {
  if (!configured()) {
    logger.info('terminal p2p TURN disabled (no TERMINAL_P2P_TURN_KEY_ID)')
    return
  }
  const resolved = resolveDeps(deps)
  void refresh(resolved)
  if (timer) clearInterval(timer)
  // A quarter of the ttl: guarantees at least one attempt inside the refresh window even if one fails.
  const period = Math.max(60_000, (env.TERMINAL_P2P_TURN_TTL_SECONDS * 1000) / 4)
  timer = setInterval(() => { void turnCredentials(deps) }, period)
  timer.unref?.()
}

/** Test seam: forget the snapshot, the in-flight mint and the retry backoff. */
export function resetTurnCredentialsForTest(): void {
  snapshot = null
  inflight = null
  nextAttemptAt = 0
  if (timer) clearInterval(timer)
  timer = null
}