import { transportTierRank, transportUpgradeIceSchema, wireFromTransportTier, type TransportStats, type TransportTier, } from '@dsh-remote/protocol' import { RtcDataChannelTransport, UpgradedRtcDataChannelTransport, type RtcConnectionDetails, type RtcIceCandidateInit, type RtcIceServer, type RtcPathMode, type RtcDiagnosticEvent, type RtcPeerConnectionFactory, type SequencedOutboundTransport, } from '@dsh-remote/webrtc' import type { RemoteClientCore } from './index.js' export interface UpgradeableSecureChannel { readonly outboundCounter: number attachIncomingLeg(leg: SequencedOutboundTransport): void markPreviousLegEndCounter?(previousLegEndCounter: number): void switchOutboundLeg(leg: SequencedOutboundTransport, options?: { closePrevious?: boolean; drainMs?: number }): Promise detachLeg(leg: SequencedOutboundTransport): Promise relayTrafficBytes?(): { sent: number; received: number } } export interface LiveTransportUpgradeTelemetry { attemptId: string from: TransportTier to?: RtcPathMode outcome: 'activated' | 'skipped-not-higher' | 'rejected' | 'failed' | 'aborted' durationMs: number relayBytesAtOutcome?: { sent: number; received: number } reason?: string } export interface ClientLiveTransportUpgraderOptions { connectionId: string rpc: RemoteClientCore channel: UpgradeableSecureChannel rtcFactory: RtcPeerConnectionFactory fetchIceServers?: (connectionId: string) => Promise iceServersTimeoutMs?: number negotiateTimeoutMs?: number onUpgraded?: (mode: RtcPathMode, transport: UpgradedRtcDataChannelTransport) => void onDiagnostic?: (event: RtcDiagnosticEvent) => void onTelemetry?: (telemetry: LiveTransportUpgradeTelemetry) => void } interface UpgradeOfferResponse { attemptId?: unknown sdp?: unknown } interface UpgradeActivateResponse { activated?: unknown mode?: unknown previousLegEndCounter?: unknown } let nextUpgradeSeq = 1 function createAttemptId(): string { return `upg_${Date.now().toString(36)}_${(nextUpgradeSeq++).toString(36)}` } /** * Client-side live WebRTC transport upgrader (`remote.transport.upgrade.v1`). * * Negotiates WebRTC DataChannels over an already-authenticated Noise RPC session * and climbs monotonically `Relay -> TURN -> P2P -> LAN` without rotating Noise * keys or interrupting open streams. */ export class ClientLiveTransportUpgrader { private currentLeg?: UpgradedRtcDataChannelTransport private activeAttemptId?: string private activeRtc?: RtcDataChannelTransport private readonly pendingRemoteIce: RtcIceCandidateInit[] = [] private remoteDescReady = false private promoting?: Promise private closed = false private unsubscribeEvents?: () => void constructor(private readonly options: ClientLiveTransportUpgraderOptions) { this.unsubscribeEvents = options.rpc.onEvent(event => { if (this.closed || event.event !== 'remote.transport.upgrade.ice') return const parsed = transportUpgradeIceSchema.safeParse(event.data) if (!parsed.success || parsed.data.attemptId !== this.activeAttemptId) return if (!this.remoteDescReady || this.activeRtc === undefined) { if (this.pendingRemoteIce.length < 64) this.pendingRemoteIce.push(parsed.data.candidate) return } this.activeRtc.handleSignal({ type: 'ice', candidate: parsed.data.candidate }) }) } get currentMode(): TransportTier { return this.currentLeg?.mode ?? 'Relay' } get activeTransport(): UpgradedRtcDataChannelTransport | undefined { return this.currentLeg } getStats(): TransportStats | undefined { return this.currentLeg?.getStats() } connectionDetails(): Promise | undefined { return this.currentLeg?.connectionDetails() } promote(options: { preferLan?: boolean } = {}): Promise { if (this.closed) return Promise.resolve(false) if (this.currentMode === 'LAN') return Promise.resolve(false) if (this.promoting !== undefined) return this.promoting const run = this.runAttempt(options.preferLan === true).finally(() => { if (this.promoting === run) this.promoting = undefined }) this.promoting = run return run } /** Wait up to `windowMs` for an in-flight upgrade so initial reads prefer direct when fast. */ async waitForInitialWindow(windowMs: number): Promise { if (this.currentMode !== 'Relay') return true const inFlight = this.promoting ?? this.promote() if (windowMs <= 0) return false let timer: ReturnType | undefined try { return await Promise.race([ inFlight, new Promise(resolve => { timer = setTimeout(() => resolve(false), windowMs) ;(timer as { unref?: () => void }).unref?.() }), ]) } finally { if (timer !== undefined) clearTimeout(timer) } } private async runAttempt(preferLan: boolean): Promise { const startedAt = Date.now() const fromMode = this.currentMode const attemptId = createAttemptId() this.activeAttemptId = attemptId this.pendingRemoteIce.length = 0 this.remoteDescReady = false const emitTelemetry = (outcome: LiveTransportUpgradeTelemetry['outcome'], extra: Partial = {}) => { this.options.onTelemetry?.({ attemptId, from: fromMode, outcome, durationMs: Math.max(0, Date.now() - startedAt), relayBytesAtOutcome: this.options.channel.relayTrafficBytes?.(), ...extra, }) } let iceServers: RtcIceServer[] = [] if (!preferLan && this.options.fetchIceServers !== undefined) { try { iceServers = await withTimeout( this.options.fetchIceServers(this.options.connectionId), this.options.iceServersTimeoutMs ?? 4_000, ) } catch { iceServers = [] } } if (this.closed) { emitTelemetry('aborted') return false } const localIceQueue: RtcIceCandidateInit[] = [] let offerSent = false let offerResolve: ((sdp: string) => void) | undefined const offerCreated = new Promise(resolve => { offerResolve = resolve }) const rtc = new RtcDataChannelTransport({ role: 'initiator', factory: this.options.rtcFactory, iceServers, negotiateTimeoutMs: this.options.negotiateTimeoutMs ?? 6_000, onDiagnostic: this.options.onDiagnostic, onSignal: signal => { if (this.closed || this.activeAttemptId !== attemptId) return if (signal.type === 'offer') { offerResolve?.(signal.sdp) return } if (signal.type === 'ice') { if (!offerSent) { if (localIceQueue.length < 64) localIceQueue.push(signal.candidate) } else { void this.options.rpc.rpc('remote.transport.upgrade.ice', { attemptId, candidate: signal.candidate }, undefined, 5_000).catch(() => undefined) } } }, }) this.activeRtc = rtc try { const openPromise = rtc.connect() // Prevent unhandled rejection if offer RPC fails before awaiting openPromise. openPromise.catch(() => undefined) const offerSdp = await withTimeout(offerCreated, 5_000) if (this.closed) throw new Error('Upgrader closed.') const answer = await this.options.rpc.rpc( 'remote.transport.upgrade.offer', { attemptId, sdp: offerSdp }, undefined, 8_000, ) offerSent = true for (const candidate of localIceQueue.splice(0)) { void this.options.rpc.rpc('remote.transport.upgrade.ice', { attemptId, candidate }, undefined, 5_000).catch(() => undefined) } if (typeof answer?.sdp !== 'string' || answer.sdp.length === 0) { throw new Error('Invalid upgrade answer.') } rtc.handleSignal({ type: 'answer', sdp: answer.sdp }) this.remoteDescReady = true for (const candidate of this.pendingRemoteIce.splice(0)) { rtc.handleSignal({ type: 'ice', candidate }) } await openPromise if (this.closed) throw new Error('Upgrader closed.') let detectedMode: RtcPathMode | undefined for (let i = 0; i < 6; i += 1) { const details = await rtc.connectionDetails().catch(() => undefined) detectedMode = details?.mode if (detectedMode === 'LAN') break if (!preferLan && detectedMode !== undefined) break if (i < 5) await new Promise(resolve => setTimeout(resolve, 40)) } if (detectedMode !== undefined && transportTierRank(detectedMode) <= transportTierRank(this.currentMode)) { void this.options.rpc.rpc('remote.transport.upgrade.abort', { attemptId }, undefined, 3_000).catch(() => undefined) await rtc.close().catch(() => undefined) emitTelemetry('skipped-not-higher', { to: detectedMode }) return false } const candidateWire = detectedMode !== undefined ? wireFromTransportTier(detectedMode) : undefined const provisionalMode: RtcPathMode = detectedMode ?? 'P2P' const upgraded = new UpgradedRtcDataChannelTransport(rtc, provisionalMode, wireFromTransportTier(provisionalMode)) // Attach inbound leg BEFORE telling the Host to switch its outbound leg. this.options.channel.attachIncomingLeg(upgraded) const activation = await this.options.rpc.rpc( 'remote.transport.upgrade.activate', { attemptId, ...(candidateWire !== undefined ? { transport: candidateWire } : {}), }, undefined, 6_000, ) if (activation?.activated !== true) { await this.options.channel.detachLeg(upgraded) emitTelemetry('rejected') return false } const authoritativeMode: RtcPathMode = activation.mode === 'LAN' || activation.mode === 'P2P' || activation.mode === 'TURN' ? activation.mode : provisionalMode if (authoritativeMode !== upgraded.mode) { upgraded.updateMode(authoritativeMode, wireFromTransportTier(authoritativeMode)) } // Atomically retire the previous outbound leg FIRST so no further frames // can be written to it and its close callback cannot fail the channel. const finalOldLegCounter = await this.options.channel.switchOutboundLeg(upgraded, { closePrevious: true }) if (typeof activation.previousLegEndCounter === 'number') { this.options.channel.markPreviousLegEndCounter?.(activation.previousLegEndCounter) } this.currentLeg = upgraded // Now notify the Host of the true final frame count sent on the retired leg // over the newly active DataChannel so the Host can drain and close it safely. void this.options.rpc.rpc( 'remote.transport.upgrade.drain', { attemptId, previousLegEndCounter: finalOldLegCounter }, undefined, 5_000, ).catch(() => undefined) this.options.onUpgraded?.(authoritativeMode, upgraded) emitTelemetry('activated', { to: authoritativeMode }) return true } catch (error) { void this.options.rpc.rpc('remote.transport.upgrade.abort', { attemptId }, undefined, 3_000).catch(() => undefined) await rtc.close().catch(() => undefined) emitTelemetry(this.closed ? 'aborted' : 'failed', { reason: error instanceof Error ? error.name : 'Error' }) return false } finally { if (this.activeAttemptId === attemptId) { this.activeAttemptId = undefined this.activeRtc = undefined this.pendingRemoteIce.length = 0 } } } async close(): Promise { if (this.closed) return this.closed = true this.unsubscribeEvents?.() this.unsubscribeEvents = undefined const active = this.activeRtc this.activeRtc = undefined if (active !== undefined) await active.close().catch(() => undefined) const leg = this.currentLeg this.currentLeg = undefined if (leg !== undefined) await leg.close().catch(() => undefined) } } async function withTimeout(promise: Promise, timeoutMs: number): Promise { let timer: ReturnType | undefined try { return await Promise.race([ promise, new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('Operation timed out.')), timeoutMs) ;(timer as { unref?: () => void }).unref?.() }), ]) } finally { if (timer !== undefined) clearTimeout(timer) } }