diff --git a/packages/client-core/src/transport-upgrader.ts b/packages/client-core/src/transport-upgrader.ts new file mode 100644 index 0000000..8f40b9e --- /dev/null +++ b/packages/client-core/src/transport-upgrader.ts @@ -0,0 +1,341 @@ +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) + } +}