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.

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.ts
index 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.ts
index 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.ts
index 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 = {}): StunSelector
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<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 inflight
const 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.ts
index 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) => void
const 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.ts
index 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 = 1
export 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: boolean
protocolVersion: number
stunUrls: string[]
openWaitMs: number
+ turn?: TerminalP2pTurn
}
export interface TerminalP2pSignal {
@@ -41,6 +49,12 @@ export interface TerminalP2pSignal {
candidate?: RTCIceCandidateInit | null
reason?: string
stunUrls?: 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 = null
try {
- 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 = pc
this.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.ts
new file mode 100644
index 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)
+})