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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
feat: add TURN relay support to TerminalP2p and include a verified test suite
0xken157caf47e375d1
diff --git a/cli/src/lib/remoteRelay.ts b/cli/src/lib/remoteRelay.tsindex ae470d9db..8fa29fa83 100644--- a/cli/src/lib/remoteRelay.ts+++ b/cli/src/lib/remoteRelay.ts@@ -24,6 +24,7 @@ import {TERMINAL_P2P_PROTOCOL_VERSION,TERMINAL_P2P_SIGNAL_TYPES,TERMINAL_P2P_UP_TYPES,+ readTurn,type TerminalP2pData,type TerminalP2pPolicy,} from './terminalP2p.js'@@ -82,7 +83,14 @@ function p2pPolicy(value: unknown): TerminalP2pPolicy | null {const openWaitMs = typeof raw.openWaitMs === 'number' && Number.isSafeInteger(raw.openWaitMs)? Math.max(0, Math.min(5_000, raw.openWaitMs)): 1_500- return { enabled: true, protocolVersion: TERMINAL_P2P_PROTOCOL_VERSION, stunUrls, openWaitMs }+ const turn = readTurn(raw.turn)+ return {+ enabled: true,+ protocolVersion: TERMINAL_P2P_PROTOCOL_VERSION,+ stunUrls,+ openWaitMs,+ ...(turn ? { turn } : {}),+ }}function framePayload(frame: Frame): Record<string, unknown> {@@ -385,7 +393,9 @@ export class RemoteRelayPool {onState: (state, setupMs, reason) => {if (state === 'direct') {wasDirect = true- this.reportP2pResult(entry, 'direct', setupMs)+ // 'relayed' distinguishes a Cloudflare TURN path from a truly direct one. Both are "p2p" as far+ // as the terminal is concerned, but only one of them is billed per GB.+ this.reportP2pResult(entry, 'direct', setupMs, p2p.transport === 'relay' ? 'relayed' : undefined)} else if (state === 'failed' && !wasDirect) {this.reportP2pResult(entry, reason === 'negotiation_timeout' ? 'timeout' : 'failed', setupMs, reason)}diff --git a/cli/src/lib/stunSelect.spec.ts b/cli/src/lib/stunSelect.spec.tsindex ea6eb48df..0ad0fe53e 100644--- a/cli/src/lib/stunSelect.spec.ts+++ b/cli/src/lib/stunSelect.spec.ts@@ -3,6 +3,7 @@ import { describe, expect, it, vi } from 'vitest'import {buildBindingRequest,createStunSelector,+ pickTurnUrl,parseBindingResponse,parseStunUrl,type StunProbe,@@ -127,7 +128,7 @@ describe('STUN selection race', () => {it('puts the fastest responder first and keeps the losers in their original order', async () => {const probe = fakeProbe({ [URLS[2]!]: 10, [URLS[0]!]: 30 })const select = createStunSelector({ probe })- expect(await select(URLS)).toEqual(['stun:10.0.0.1:3478', URLS[0], URLS[1]])+ expect(await select(URLS)).toEqual({ urls: ['stun:10.0.0.1:3478', URLS[0], URLS[1]], udpReachable: true })})it('returns as soon as one answers, aborting the probes still outstanding', async () => {@@ -138,21 +139,22 @@ describe('STUN selection race', () => {return new Promise(() => { /* would hang forever without the abort */ })}const select = createStunSelector({ probe })- expect((await select(URLS))[0]).toBe('stun:10.0.0.1:3478')+ expect((await select(URLS)).urls[0]).toBe('stun:10.0.0.1:3478')expect(aborted).toBe(true)})it('is never worse than today: when every server fails it returns the list untouched', async () => {const probe = vi.fn<StunProbe>(async () => null)const select = createStunSelector({ probe })- expect(await select(URLS)).toEqual(URLS)+ expect(await select(URLS)).toEqual({ urls: URLS, udpReachable: false })})it('does not probe at all for a list of zero or one url', async () => {const probe = vi.fn<StunProbe>(async () => '10.0.0.1')const select = createStunSelector({ probe })- expect(await select([])).toEqual([])- expect(await select(['stun:only.example:3478'])).toEqual(['stun:only.example:3478'])+ expect(await select([])).toEqual({ urls: [], udpReachable: null })+ expect(await select(['stun:only.example:3478']))+ .toEqual({ urls: ['stun:only.example:3478'], udpReachable: null })expect(probe).not.toHaveBeenCalled()})@@ -163,14 +165,14 @@ describe('STUN selection race', () => {return Promise.resolve(null)}const select = createStunSelector({ probe: thrower })- await expect(select(URLS)).resolves.toEqual(URLS)+ await expect(select(URLS)).resolves.toEqual({ urls: URLS, udpReachable: false })})it('leaves a winner that is already an IP literal alone, and never pins the losers', async () => {const urls = ['stun:198.51.100.7:3478', 'stun:b.example:3478']const probe: StunProbe = async (url) => (url === urls[0] ? '198.51.100.7' : null)const select = createStunSelector({ probe })- expect(await select(urls)).toEqual(urls)+ expect(await select(urls)).toEqual({ urls, udpReachable: true })})it('joins an in-flight race instead of starting a second one', async () => {@@ -237,8 +239,9 @@ describe('STUN probe over a real socket', () => {try {const select = createStunSelector({ probeTimeoutMs: 1_000 })- const ordered = await select([`stun:127.0.0.1:${deadPort}`, `stun:127.0.0.1:${livePort}`])- expect(ordered[0]).toBe(`stun:127.0.0.1:${livePort}`)+ const selection = await select([`stun:127.0.0.1:${deadPort}`, `stun:127.0.0.1:${livePort}`])+ expect(selection.urls[0]).toBe(`stun:127.0.0.1:${livePort}`)+ expect(selection.udpReachable).toBe(true)} finally {await new Promise<void>((resolve) => server.close(resolve))}@@ -248,6 +251,47 @@ describe('STUN probe over a real socket', () => {const select = createStunSelector({ probeTimeoutMs: 300 })// TEST-NET-3, guaranteed unroutable, so both probes hit the deadline rather than any error path.const urls = ['stun:203.0.113.1:3478', 'stun:203.0.113.2:3478']- expect(await select(urls)).toEqual(urls)+ expect(await select(urls)).toEqual({ urls, udpReachable: false })}, 10_000)})++describe('TURN url choice', () => {+ // Exactly what Cloudflare's generate-ice-servers returns, in its own order.+ const CLOUDFLARE = [+ 'turn:turn.cloudflare.com:3478?transport=udp',+ 'turn:turn.cloudflare.com:3478?transport=tcp',+ 'turns:turn.cloudflare.com:5349?transport=tcp',+ 'turn:turn.cloudflare.com:80?transport=tcp',+ 'turns:turn.cloudflare.com:443?transport=tcp',+ ]++ it('takes the udp url when the stun race proved udp leaves this host', () => {+ expect(pickTurnUrl(CLOUDFLARE, true)).toBe('turn:turn.cloudflare.com:3478?transport=udp')+ })++ it('drops to TLS on 443 when every stun server was unreachable', () => {+ // werift would otherwise sit on the first entry, and its own udp->tcp retry stays on 3478 — a port+ // a network that blocks UDP usually blocks too. 443 is the whole reason this function exists.+ expect(pickTurnUrl(CLOUDFLARE, false)).toBe('turns:turn.cloudflare.com:443?transport=tcp')+ })++ it('falls back to any turns: url when 443 is not on offer', () => {+ expect(pickTurnUrl(['turn:x:3478?transport=udp', 'turns:x:5349?transport=tcp'], false))+ .toBe('turns:x:5349?transport=tcp')+ })++ it('behaves exactly like werift when reachability was never measured', () => {+ expect(pickTurnUrl(CLOUDFLARE, null)).toBe(CLOUDFLARE[0])+ })++ it('keeps the first url when the preferred kind is missing from the list', () => {+ expect(pickTurnUrl(['turn:x:3478?transport=tcp'], true)).toBe('turn:x:3478?transport=tcp')+ expect(pickTurnUrl(['turn:x:3478?transport=udp'], false)).toBe('turn:x:3478?transport=udp')+ })++ it('returns null for an empty or non-turn list', () => {+ expect(pickTurnUrl([], true)).toBeNull()+ expect(pickTurnUrl(['stun:x:3478', 'https://x'], true)).toBeNull()+ })+})+diff --git a/cli/src/lib/stunSelect.ts b/cli/src/lib/stunSelect.tsindex f4dcc166c..be7784ab3 100644--- a/cli/src/lib/stunSelect.ts+++ b/cli/src/lib/stunSelect.ts@@ -48,7 +48,21 @@ 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 type StunSelector = (urls: string[]) => Promise<string[]>+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@@ -223,7 +237,7 @@ export function createStunSelector(opts: StunSelectorOptions = {}): StunSelectorconst negativeTtlMs = opts.negativeTtlMs ?? NEGATIVE_TTL_MSconst probeTimeoutMs = opts.probeTimeoutMs ?? PROBE_TIMEOUT_MSconst cache = new Map<string, CacheEntry>()- const pending = new Map<string, Promise<string[]>>()+ const pending = new Map<string, Promise<StunSelection>>()const race = (urls: string[]): Promise<RaceResult> => new Promise<RaceResult>((resolve) => {const controller = new AbortController()@@ -255,25 +269,64 @@ export function createStunSelector(opts: StunSelectorOptions = {}): StunSelector})return async (urls) => {- // Zero or one url: nothing to choose between, so do not spend a single packet deciding.- if (urls.length <= 1) return 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 hit.ordered+ if (hit && now() - hit.at < (hit.ok ? ttlMs : negativeTtlMs)) {+ return { urls: hit.ordered, udpReachable: hit.ok }+ }const inflight = pending.get(key)if (inflight) return inflightconst run = race(urls).then(({ ordered, ok }) => {cache.set(key, { ordered, ok, at: now() })- return ordered+ return { urls: ordered, udpReachable: ok }})- .catch(() => urls) // the contract is that this function never rejects+ .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()diff --git a/cli/src/lib/terminalP2p.spec.ts b/cli/src/lib/terminalP2p.spec.tsindex 141a63046..b8d06973b 100644--- a/cli/src/lib/terminalP2p.spec.ts+++ b/cli/src/lib/terminalP2p.spec.ts@@ -1,5 +1,6 @@import { describe, expect, it, vi } from 'vitest'import {+ readTurn,TerminalP2pInitiator,TerminalP2pResponderPool,type TerminalP2pSignal,@@ -41,7 +42,7 @@ describe('terminal WebRTC data channel', () => {const policyUrls = ['stun:a.example:3478', 'stun:b.example:3478']// Returning [] keeps werift on host candidates, so the offer is emitted immediately instead of// waiting out a gather against hosts that do not resolve.- const selectStunUrls = vi.fn<StunSelector>(async () => [])+ const selectStunUrls = vi.fn<StunSelector>(async () => ({ urls: [], udpReachable: null }))let resolveOffer!: (payload: TerminalP2pSignal) => voidconst offered = new Promise<TerminalP2pSignal>((resolve) => { resolveOffer = resolve })const initiator = new TerminalP2pInitiator({@@ -65,8 +66,8 @@ describe('terminal WebRTC data channel', () => {}, 15_000)it('builds one peer connection when start() is called twice during the stun race', async () => {- let release!: (urls: string[]) => void- const gate = new Promise<string[]>((resolve) => { release = resolve })+ let release!: (selection: { urls: string[]; udpReachable: boolean | null }) => void+ const gate = new Promise<{ urls: string[]; udpReachable: boolean | null }>((resolve) => { release = resolve })const selectStunUrls = vi.fn<StunSelector>(() => gate)const initiator = new TerminalP2pInitiator({policy: { enabled: true, protocolVersion: 1, stunUrls: ['stun:a.example:3478', 'stun:b.example:3478'], openWaitMs: 1_500 },@@ -80,14 +81,14 @@ describe('terminal WebRTC data channel', () => {initiator.start()expect(selectStunUrls).toHaveBeenCalledTimes(1)} finally {- release([])+ release({ urls: [], udpReachable: null })await initiator.stop('test_complete', false)}})it('builds nothing at all when stop() lands while the stun race is still in flight', async () => {- let release!: (urls: string[]) => void- const gate = new Promise<string[]>((resolve) => { release = resolve })+ let release!: (selection: { urls: string[]; udpReachable: boolean | null }) => void+ const gate = new Promise<{ urls: string[]; udpReachable: boolean | null }>((resolve) => { release = resolve })const states: string[] = []const signals: string[] = []const initiator = new TerminalP2pInitiator({@@ -101,7 +102,7 @@ describe('terminal WebRTC data channel', () => {initiator.start()const ready = initiator.waitUntilReady(5_000)await initiator.stop('test_complete', false)- release([])+ release({ urls: [], udpReachable: null })await new Promise((resolve) => setTimeout(resolve, 20))// No offer was ever sent, which is the observable proof no RTCPeerConnection was constructed —@@ -119,7 +120,7 @@ describe('terminal WebRTC data channel', () => {sendSignal: () => { /* nothing to signal in this test */ },onData: () => { /* no peer in this test */ },onState: (state, _setupMs, reason) => { states.push({ state, reason }) },- selectStunUrls: () => new Promise<string[]>(() => { /* wedged on purpose */ }),+ selectStunUrls: () => new Promise(() => { /* wedged on purpose */ }),})try {@@ -132,7 +133,7 @@ describe('terminal WebRTC data channel', () => {})it('hands the responder the offered urls, filtered and capped, to race on its own', async () => {- const selectStunUrls = vi.fn<StunSelector>(async (urls) => urls)+ const selectStunUrls = vi.fn<StunSelector>(async (urls) => ({ urls, udpReachable: true }))const responder = new TerminalP2pResponderPool({sendSignal: () => { /* the offer below is deliberately unanswerable */ },onData: () => { /* no data in this test */ },@@ -156,4 +157,64 @@ describe('terminal WebRTC data channel', () => {await responder.stop()}})++ it('forwards the turn credential in the offer so the responder can allocate too', async () => {+ // Loopback discard port: werift really does try to allocate against whatever we hand it, so a real+ // hostname here would make this test wait out a live TURN negotiation. A closed local port fails+ // immediately and still proves the credential travelled.+ const turn = { urls: ['turn:127.0.0.1:9?transport=udp'], username: 'cf-user', credential: 'cf-secret' }+ let resolveOffer!: (payload: TerminalP2pSignal) => void+ const offered = new Promise<TerminalP2pSignal>((resolve) => { resolveOffer = resolve })+ const initiator = new TerminalP2pInitiator({+ policy: { enabled: true, protocolVersion: 1, stunUrls: ['stun:a.example:3478'], openWaitMs: 1_500, turn },+ sendSignal: (type, payload) => { if (type === 'p2p_offer') resolveOffer(payload) },+ onData: () => { /* no peer in this test */ },+ selectStunUrls: async () => ({ urls: [], udpReachable: null }),+ })++ try {+ initiator.start()+ // The responder is never sent a policy of its own, so the offer is its only source of credentials.+ expect((await offered).turn).toEqual(turn)+ } finally {+ await initiator.stop('test_complete', false)+ }+ }, 15_000)++ it('gives the responder the offered turn credential, and drops a malformed one', async () => {+ const seen: Array<unknown> = []+ const responder = new TerminalP2pResponderPool({+ sendSignal: () => { /* the offers below are deliberately unanswerable */ },+ onData: () => { /* no data in this test */ },+ selectStunUrls: async (urls) => ({ urls, udpReachable: true }),+ })+ const offer = (turn: unknown, sessionId: string): Promise<boolean> => responder.handleSignal('source-1', 'p2p_offer', {+ sessionId,+ protocolVersion: 1,+ sdp: 'not-a-real-sdp',+ stunUrls: ['stun:1.example:3478'],+ turn,+ })++ try {+ await offer({ urls: ['turn:x:3478?transport=udp'], username: 'u', credential: 'c' },+ '00000000-0000-4000-8000-000000000001')+ seen.push(readTurn({ urls: ['turn:x:3478?transport=udp'], username: 'u', credential: 'c' }))+ // Each of these is rejected for a different reason; all must degrade to STUN-only, not throw.+ for (const bad of [+ undefined,+ { urls: [], username: 'u', credential: 'c' },+ { urls: ['stun:x:3478'], username: 'u', credential: 'c' },+ { urls: ['turn:x:3478'], username: '', credential: 'c' },+ { urls: ['turn:x:3478'], username: 'u', credential: 42 },+ 'not-an-object',+ ]) {+ expect(readTurn(bad)).toBeUndefined()+ await offer(bad, '00000000-0000-4000-8000-000000000002')+ }+ expect(seen[0]).toEqual({ urls: ['turn:x:3478?transport=udp'], username: 'u', credential: 'c' })+ } finally {+ await responder.stop()+ }+ }, 15_000)})diff --git a/cli/src/lib/terminalP2p.ts b/cli/src/lib/terminalP2p.tsindex e4c0bb9e3..b5cb598e4 100644--- a/cli/src/lib/terminalP2p.ts+++ b/cli/src/lib/terminalP2p.ts@@ -1,6 +1,6 @@import { randomUUID } from 'node:crypto'import { RTCPeerConnection, type RTCDataChannel, type RTCIceCandidateInit } from 'werift'-import { selectStunUrls, type StunSelector } from './stunSelect.js'+import { pickTurnUrl, selectStunUrls, type StunSelector } from './stunSelect.js'export const TERMINAL_P2P_PROTOCOL_VERSION = 1export const TERMINAL_P2P_CHANNEL = 'terminal-v1'@@ -27,11 +27,19 @@ export const TERMINAL_P2P_UP_TYPES = new Set([export type TerminalP2pState = 'connecting' | 'direct' | 'failed' | 'closed'export type TerminalP2pData = string | Buffer+/** Cloudflare hands out one credential covering several urls; werift will only ever use one of them. */+export interface TerminalP2pTurn {+ urls: string[]+ username: string+ credential: string+}+export interface TerminalP2pPolicy {enabled: booleanprotocolVersion: numberstunUrls: string[]openWaitMs: number+ turn?: TerminalP2pTurn}export interface TerminalP2pSignal {@@ -41,6 +49,12 @@ export interface TerminalP2pSignal {candidate?: RTCIceCandidateInit | nullreason?: stringstunUrls?: string[]+ /**+ * The responder is never sent a policy of its own — the backend only checks `enabled` on that side —+ * so the offer is the only way TURN credentials can reach it. Safe: this frame is E2EE between the+ * two peers, the credential is short-lived, and the backend minted it in the first place.+ */+ turn?: TerminalP2pTurn}export interface TerminalP2pInitiatorDeps {@@ -67,15 +81,48 @@ function parseSignal(value: unknown): TerminalP2pSignal | null {return payload as unknown as TerminalP2pSignal}-function peerConfig(stunUrls: string[]): ConstructorParameters<typeof RTCPeerConnection>[0] {+interface TurnChoice {+ url: string+ username: string+ credential: string+}++function peerConfig(stunUrls: string[], turn?: TurnChoice): ConstructorParameters<typeof RTCPeerConnection>[0] {+ const iceServers: Array<{ urls: string[]; username?: string; credential?: string }> = []+ if (stunUrls.length > 0) iceServers.push({ urls: stunUrls })+ if (turn) iceServers.push({ urls: [turn.url], username: turn.username, credential: turn.credential })return {- iceServers: stunUrls.length > 0 ? [{ urls: stunUrls }] : [],+ iceServers,+ // Left at the default 'all' deliberately: that is what produces "direct first, relay only if+ // nothing else works". werift scores candidates host 126 > srflx 100 > relay 0, so a TURN relay+ // pair is only ever nominated once every direct pair has failed. Setting 'relay' here would force+ // every session through Cloudflare — and bill for it.// Terminal keyframes can approach 480 KiB. SCTP fragments them, but advertise enough room so// the peer never rejects the message at the WebRTC API boundary before fragmentation happens.maxMessageSize: 512 * 1024,}}+/** Shared by both sides: same validation, same reason. Anything malformed degrades to STUN-only. */+export function readTurn(value: unknown): TerminalP2pTurn | undefined {+ if (!value || typeof value !== 'object') return undefined+ const raw = value as Record<string, unknown>+ const { username, credential } = raw+ if (typeof username !== 'string' || !username || username.length > 512) return undefined+ if (typeof credential !== 'string' || !credential || credential.length > 512) return undefined+ const urls = Array.isArray(raw.urls)+ ? raw.urls.filter((url): url is string => typeof url === 'string' && /^turns?:/i.test(url)).slice(0, 8)+ : []+ if (urls.length === 0) return undefined+ return { urls, username, credential }+}++function turnChoice(turn: TerminalP2pTurn | undefined, udpReachable: boolean | null): TurnChoice | undefined {+ if (!turn) return undefined+ const url = pickTurnUrl(turn.urls, udpReachable)+ return url ? { url, username: turn.username, credential: turn.credential } : undefined+}+function channelCanSend(channel: RTCDataChannel | null): channel is RTCDataChannel {return channel?.readyState === 'open'&& channel.bufferedAmount < TERMINAL_P2P_MAX_BUFFERED_BYTES@@ -103,6 +150,22 @@ export class TerminalP2pInitiator {get isReady(): boolean { return this.ready && channelCanSend(this.channel) }+ /**+ * Which path ICE actually nominated, once the channel is open. 'relay' means the bytes are going+ * through Cloudflare TURN, which is billed per GB — without reporting this we would have no idea how+ * much of the traffic costs money. `null` while still negotiating, or if werift exposes no pair.+ */+ get transport(): 'direct' | 'relay' | null {+ const pc = this.pc+ if (!pc || !this.ready) return null+ for (const iceTransport of pc.iceTransports) {+ // werift's RTCIceCandidate carries only the SDP line, so the type comes out of the string.+ const line = iceTransport.getSelectedCandidatePair?.()?.local?.candidate+ if (typeof line === 'string' && line) return /\btyp relay\b/.test(line) ? 'relay' : 'direct'+ }+ return null+ }+start(): void {// `starting`, not `this.pc`: the peer connection is only built after the STUN race below, so for// those few hundred ms `this.pc` is still null and would let a second start() build a second one.@@ -119,13 +182,16 @@ export class TerminalP2pInitiator {private async begin(): Promise<void> {let stunUrls = this.deps.policy.stunUrls+ let udpReachable: boolean | null = nulltry {- stunUrls = await this.selectStunUrls(stunUrls)+ const selection = await this.selectStunUrls(stunUrls)+ stunUrls = selection.urls+ udpReachable = selection.udpReachable} catch { /* the selector contract is that it never rejects; keep the policy order regardless */ }// stop()/fail() may have run while the race was in flight. Building the peer connection now would// strand it: nothing holds a reference any more, so its UDP sockets would never be closed.if (this.finished) return- const pc = new RTCPeerConnection(peerConfig(stunUrls))+ const pc = new RTCPeerConnection(peerConfig(stunUrls, turnChoice(this.deps.policy.turn, udpReachable)))const channel = pc.createDataChannel(TERMINAL_P2P_CHANNEL, { ordered: true })this.pc = pcthis.channel = channel@@ -145,7 +211,10 @@ export class TerminalP2pInitiator {sessionId: this.sessionId,protocolVersion: TERMINAL_P2P_PROTOCOL_VERSION,sdp: local.sdp,+ // The RAW policy list, not the raced order: the responder runs its own race, and the two peers+ // need not agree on a server — a srflx candidate is each peer's own public address.stunUrls: this.deps.policy.stunUrls,+ ...(this.deps.policy.turn ? { turn: this.deps.policy.turn } : {}),})} catch {this.fail('offer_failed')@@ -364,9 +433,10 @@ export class TerminalP2pResponderPool {: []// The offerer raced these too, and may well have landed on a different server. That is fine: a// srflx candidate is each peer's own public address, so the two sides need not agree on who to ask.- const ordered = await this.selectStunUrls(offeredStunUrls)+ const selection = await this.selectStunUrls(offeredStunUrls)if (this.offerSeq.get(connId) !== seq) return- const pc = new RTCPeerConnection(peerConfig(ordered))+ const turn = turnChoice(readTurn(payload.turn), selection.udpReachable)+ const pc = new RTCPeerConnection(peerConfig(selection.urls, turn))const entry: ResponderEntry = {sessionId: payload.sessionId,pc,diff --git a/cli/src/lib/turnRelay.real.spec.ts b/cli/src/lib/turnRelay.real.spec.tsnew file mode 100644index 000000000..caab55dba--- /dev/null+++ b/cli/src/lib/turnRelay.real.spec.ts@@ -0,0 +1,83 @@+/**+ * Opt-in: needs live Cloudflare TURN credentials, so it is skipped unless you ask for it.+ *+ * TURN_KEY_ID=… TURN_API_TOKEN=… RUN_REAL_TURN=1 npx vitest run src/lib/turnRelay.real.spec.ts+ *+ * It pins the one claim the whole TURN change rests on: forced onto relay-only, two werift peers can+ * still open a terminal data channel through Cloudflare and carry a full-size keyframe. Everything+ * else about TURN is a preference; this is the capability.+ */+import { RTCPeerConnection } from 'werift'+import { describe, expect, it } from 'vitest'++const enabled = process.env.RUN_REAL_TURN === '1'+ && !!process.env.TURN_KEY_ID && !!process.env.TURN_API_TOKEN+const realDescribe = enabled ? describe : describe.skip++async function iceServers(): Promise<object[]> {+ const res = await fetch(+ `https://rtc.live.cloudflare.com/v1/turn/keys/${process.env.TURN_KEY_ID}/credentials/generate-ice-servers`,+ {+ method: 'POST',+ headers: {+ Authorization: `Bearer ${process.env.TURN_API_TOKEN}`,+ 'Content-Type': 'application/json',+ },+ body: JSON.stringify({ ttl: 3600 }),+ },+ )+ expect(res.status).toBe(201)+ const body = await res.json() as { iceServers: object[] }+ return body.iceServers+}++realDescribe('Cloudflare TURN relay', () => {+ it('carries a terminal data channel end to end with every direct path forbidden', async () => {+ const config = {+ iceServers: await iceServers(),+ iceTransportPolicy: 'relay',+ maxMessageSize: 512 * 1024,+ } as never+ const a = new RTCPeerConnection(config)+ const b = new RTCPeerConnection(config)++ try {+ const channel = a.createDataChannel('terminal-v1', { ordered: true })+ const inbox: Array<(value: number) => void> = []+ const nextEcho = (): Promise<number> => new Promise((resolve) => inbox.push(resolve))+ channel.onMessage.subscribe((data) => {+ inbox.shift()?.(typeof data === 'string' ? Buffer.byteLength(data) : data.length)+ })+ b.onDataChannel.subscribe((remote) => { remote.onMessage.subscribe((data) => remote.send(data)) })++ // Non-trickle, exactly like the CLI: every candidate rides in the SDP.+ await a.setLocalDescription(await a.createOffer())+ await b.setRemoteDescription(a.localDescription!)+ await b.setLocalDescription(await b.createAnswer())+ await a.setRemoteDescription(b.localDescription!)++ const types = new Set([...(a.localDescription?.sdp ?? '').matchAll(/typ (\w+)/g)].map((m) => m[1]))+ expect([...types]).toEqual(['relay']) // proves nothing direct was even on offer++ const open = await Promise.race([+ new Promise<boolean>((resolve) => {+ channel.stateChanged.subscribe((state) => { if (state === 'open') resolve(true) })+ }),+ new Promise<boolean>((resolve) => setTimeout(() => resolve(false), 25_000)),+ ])+ expect(open).toBe(true)++ const echoText = nextEcho()+ channel.send('terminal-input')+ expect(await echoText).toBe('terminal-input'.length)++ // 480 KiB is the biggest thing a terminal ever sends; it must survive SCTP fragmentation here too.+ const echoKeyframe = nextEcho()+ channel.send(Buffer.alloc(480 * 1024, 0x41))+ expect(await echoKeyframe).toBe(480 * 1024)+ } finally {+ await a.close()+ await b.close()+ }+ }, 60_000)+})