From e2d18b81259009be6ffe3a5bf4e3b802b071fda7 Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 15:05:33 +0800 Subject: [PATCH] Import packages/webrtc/src/adaptive-transport.ts --- packages/webrtc/src/adaptive-transport.ts | 897 ++++++++++++++++++++++ 1 file changed, 897 insertions(+) create mode 100644 packages/webrtc/src/adaptive-transport.ts diff --git a/packages/webrtc/src/adaptive-transport.ts b/packages/webrtc/src/adaptive-transport.ts new file mode 100644 index 0000000..abed194 --- /dev/null +++ b/packages/webrtc/src/adaptive-transport.ts @@ -0,0 +1,897 @@ +import { ControlLease } from './control-lease.js' +import { waitForRelayCapacity } from './websocket-backpressure.js' +import { + PROTOCOL_VERSION, + errorCodeSchema, + type ErrorCode, + WEBRTC_RESUME_CAPABILITY, + RELAY_RESUME_CAPABILITY, + type ConnectionLeaseAck, + acceptNegotiatedCapabilities, + createControlFrame, + createRelayDataFrame, + decodeControlFrame, + decodeRelayDataFrame, + encodeControlFrame, + encodeRelayDataFrame, + type ControlFrameByteLimits, + type ConnectAcceptedPayload, + type HelloAckPayload, + type RelayPayload, + type SecureHandshakePayload, + type SelectedTransport, + type TransportSelectedPayload, + type TransportStats, + isHeartbeatTimeoutClose, + isServerShutdownClose, +} from '@dsh-remote/protocol' +import { browserRtcFactory, type RtcIceServer, type RtcPeerConnectionFactory } from './rtc-adapter.js' +import { + RtcConnectError, + RtcDataChannelTransport, + type RtcConnectionDiagnostics, + type RtcConnectionDetails, + type RtcDiagnosticEvent, + type RtcSelectedTransport, + type RtcSignal, +} from './rtc-data-channel.js' +import { BaseTransport } from './transport.js' +import { fromBase64Url, toBase64Url } from './util.js' + +type RelayAssignment = Pick + +export interface AdaptiveTransportOptions { + role: 'client' + deviceId: string + accessToken: string + refreshAccessToken?: () => Promise + targetDeviceId: string + capabilities?: string[] + preferredTransports?: Array<'lan' | 'p2p' | 'turn' | 'relay'> + forceRelay?: boolean + /** Control authorization only, ending at connect.accepted. */ + handshakeTimeoutMs?: number + negotiateTimeoutMs?: number + iceServersTimeoutMs?: number + signal?: AbortSignal + rtcFactory?: RtcPeerConnectionFactory + fetchIceServers?: (connectionId: string, signal?: AbortSignal) => Promise + onWebRtcFallback?: (error: Error, diagnostics?: RtcConnectionDiagnostics) => void + onWebRtcDiagnostic?: (event: RtcDiagnosticEvent) => void + /** Payload-free diagnostics for an established carrier closing. */ + onDisconnect?: (event: AdaptiveDisconnectDiagnostic) => void +} + +export interface AdaptiveDisconnectDiagnostic { + reason: 'control-closed' | 'control-error' | 'invalid-control-frame' | 'webrtc-closed' + closeCode?: number + errorCode?: ErrorCode + closeReason?: string + /** Selected data-plane transport of an established WebRTC path that closed. */ + transport?: 'lan' | 'p2p' | 'turn' +} + +export interface AdaptiveConnectionDetails { + connectionId?: string + connectedAt?: number + heartbeatIntervalMs?: number + lastControlReceivedAt?: number + lastControlSentAt?: number + recoveryExpiresAt?: number + controlChannelUrl: string + controlChannelState: 'connecting' | 'open' | 'closing' | 'closed' + preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'> + negotiatedCapabilities: string[] + webRtcEnabled: boolean + webRtc?: RtcConnectionDetails +} + +const DEFAULT_CAPABILITIES = [WEBRTC_RESUME_CAPABILITY, RELAY_RESUME_CAPABILITY, 'transport.lan', 'transport.p2p', 'transport.turn', 'transport.relay', 'transport.relay.attach', 'harness.api.v1'] +const DEFAULT_PREFERRED_TRANSPORTS = ['lan', 'p2p', 'turn', 'relay'] as const + +/** + * Client-side adaptive transport: `p2p -> turn -> relay` (webrtc plan §4/§6.4). + * + * Owns the Server control WebSocket and negotiates the data plane after + * `connect.accepted`. WebRTC (initiator) is attempted first unless + * `forceRelay` is set or no RTC backend is available; every failure path + * closes the RTC state and falls back to the WebSocket Relay data plane. + * Noise IK always runs over `secure.handshake` control frames; only the Noise + * ciphertext moves to the DataChannel once WebRTC is established. + */ +export class AdaptiveTransport extends BaseTransport { + private readonly handshakeHandlers = new Set<(step: number, data: Uint8Array) => void>() + private socket?: WebSocket + private dataSocket?: WebSocket + private connectionId?: string + private relayCounter = 0 + private bytesSent = 0 + private bytesReceived = 0 + private dataMode: 'relay' | 'webrtc' = 'relay' + private selected?: SelectedTransport + private rtc?: RtcDataChannelTransport + private readyResolve?: () => void + private readyReject?: (error: Error) => void + private handshakeTimer?: ReturnType + private lifetime?: AbortController + private removeAbort?: () => void + private webrtcEnabled = true + private serverNegotiateTimeoutMs?: number + private negotiatedCapabilities: string[] = ['transport.relay'] + private controlFrameLimits: ControlFrameByteLimits = {} + private connectedAt?: number + private heartbeatIntervalMs?: number + private lastControlReceivedAt?: number + private lastControlSentAt?: number + private lastRtcDiagnostics?: RtcConnectionDiagnostics + private relayAssignment?: RelayAssignment + private dataReady = false + private recoveryTicket?: string + private relayRecoveryTicket?: string + private lease?: ControlLease + private recoveryTimer?: ReturnType + private recoveryOpeningTimer?: ReturnType + private recoveryAttempt = 0 + private controlReady = false + + constructor( + private readonly url: string, + private readonly options: AdaptiveTransportOptions, + ) { + super() + } + + async connect(): Promise { + if (this.socket !== undefined || this.connectedAt !== undefined) return + throwIfAborted(this.options.signal) + const lifetime = new AbortController() + this.lifetime = lifetime + this.webrtcEnabled = true + this.serverNegotiateTimeoutMs = undefined + this.dataMode = 'relay' + this.selected = undefined + this.connectedAt = undefined + this.relayCounter = 0 + this.socket = new WebSocket(this.url) + this.controlFrameLimits = {} + this.socket.binaryType = 'arraybuffer' + await new Promise((resolve, reject) => { + this.readyResolve = resolve + this.readyReject = reject + const onAbort = () => this.failConnection(new Error('Adaptive connection was aborted')) + this.options.signal?.addEventListener('abort', onAbort, { once: true }) + this.removeAbort = () => this.options.signal?.removeEventListener('abort', onAbort) + this.handshakeTimer = setTimeout( + () => this.failConnection(new Error('Adaptive control handshake timed out')), + this.options.handshakeTimeoutMs ?? 15_000, + ) + const socket = this.socket! + socket.onmessage = event => { if (this.socket === socket) void this.handleSocketMessage(event.data, lifetime) } + socket.onopen = () => { + if (this.lifetime !== lifetime) return + this.sendControl('hello', { + role: this.options.role, + deviceId: this.options.deviceId, + accessToken: this.options.accessToken, + protocols: [PROTOCOL_VERSION], + capabilities: this.options.capabilities ?? DEFAULT_CAPABILITIES, + }) + } + socket.onerror = () => { + if (this.lifetime === lifetime && this.socket === socket) this.controlLost(new Error('Control socket failed'), { reason: 'control-error' }) + } + socket.onclose = event => { + if (this.lifetime === lifetime && this.socket === socket) this.controlLost(adaptiveControlCloseError(event), { reason: 'control-closed', closeCode: event.code, closeReason: event.reason }) + } + }) + } + + async send(data: Uint8Array): Promise { + if (this.lease && !this.lease.valid()) throw new Error('Control lease expired') + if (this.connectionId === undefined) throw new Error('adaptive transport has not been authorized') + if (this.dataMode === 'webrtc') { + const rtc = this.rtc + if (rtc === undefined) throw new Error('webrtc data channel is not available') + this.bytesSent += data.byteLength + await rtc.send(data) + return + } + const socket = this.dataSocket ?? this.socket + if (socket?.readyState !== WebSocket.OPEN) throw new Error('adaptive transport is not connected') + await waitForRelayCapacity(socket) + const payload = { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + counter: this.relayCounter, + ciphertext: toBase64Url(data), + } satisfies RelayPayload + if (this.dataSocket !== undefined) { + this.dataSocket.send(encodeRelayDataFrame(createRelayDataFrame('relay', payload), this.controlFrameLimits)) + } + else this.sendControl('relay', payload) + this.bytesSent += data.byteLength + this.relayCounter += 1 + } + + connectionInfo(): { connectionId: string; localDeviceId: string; remoteDeviceId: string } { + if (this.connectionId === undefined) throw new Error('adaptive transport has not been authorized') + return { + connectionId: this.connectionId, + localDeviceId: this.options.deviceId, + remoteDeviceId: this.options.targetDeviceId, + } + } + + async connectionDetails(): Promise { + const remainingMs = this.lease?.remainingMs() + return { + ...(this.connectionId === undefined ? {} : { connectionId: this.connectionId }), + ...(this.connectedAt === undefined ? {} : { connectedAt: this.connectedAt }), + ...(this.heartbeatIntervalMs === undefined ? {} : { heartbeatIntervalMs: this.heartbeatIntervalMs }), + ...(this.lastControlReceivedAt === undefined ? {} : { lastControlReceivedAt: this.lastControlReceivedAt }), + ...(this.lastControlSentAt === undefined ? {} : { lastControlSentAt: this.lastControlSentAt }), + recoveryExpiresAt: remainingMs === undefined ? undefined : Date.now() + remainingMs, + controlChannelUrl: this.url, + controlChannelState: socketState(this.socket?.readyState), + preferredTransports: this.options.forceRelay === true + ? ['relay'] + : [...(this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS)], + negotiatedCapabilities: [...this.negotiatedCapabilities], + webRtcEnabled: this.webrtcEnabled, + ...(this.rtc === undefined ? {} : { webRtc: await this.rtc.connectionDetails() }), + } + } + + async sendHandshake(step: number, data: Uint8Array): Promise { + if (this.socket?.readyState !== WebSocket.OPEN || this.connectionId === undefined) { + throw new Error('adaptive transport has not been authorized') + } + this.sendControl('secure.handshake', { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + step, + data: toBase64Url(data), + } satisfies SecureHandshakePayload) + } + + onHandshake(cb: (step: number, data: Uint8Array) => void): () => void { + this.handshakeHandlers.add(cb) + return () => this.handshakeHandlers.delete(cb) + } + + async close(): Promise { + this.failConnection(new Error('Adaptive transport closed')) + } + + getStats(): TransportStats { + const webrtcConnected = this.dataMode === 'webrtc' && this.rtc?.getStats().connected === true + const relayConnected = this.dataMode === 'relay' + && (this.dataSocket?.readyState === WebSocket.OPEN && this.dataReady || this.socket?.readyState === WebSocket.OPEN) + && this.connectionId !== undefined + const connected = webrtcConnected || relayConnected + let mode: TransportStats['mode'] = 'Disconnected' + if (this.selected === 'relay') mode = relayConnected ? 'Relay' : 'Disconnected' + else if (this.selected === 'lan' || this.selected === 'turn' || this.selected === 'p2p') { + mode = webrtcConnected ? this.rtc!.getStats().mode : 'Disconnected' + } + return { mode, connected, bytesSent: this.bytesSent, bytesReceived: this.bytesReceived } + } + + private async handleSocketMessage(raw: string | ArrayBuffer | Blob, lifetime: AbortController): Promise { + if (this.lifetime !== lifetime) return + try { + if (typeof raw !== 'string') throw new Error('Adaptive control frames must be text JSON') + const frame = decodeControlFrame(raw, this.controlFrameLimits) + this.lastControlReceivedAt = Date.now() + if (frame.type === 'hello.ack') { + this.controlReady = true + const payload = frame.payload as Partial + if (payload.protocol !== PROTOCOL_VERSION) throw new Error('Server selected an unsupported protocol version') + this.heartbeatIntervalMs = payload.heartbeatIntervalMs + const offered = this.options.capabilities ?? DEFAULT_CAPABILITIES + this.negotiatedCapabilities = acceptNegotiatedCapabilities(offered, payload.capabilities) + this.controlFrameLimits = { + maxControlFrameBytes: payload.maxControlFrameBytes, + maxRelayFrameBytes: payload.maxRelayFrameBytes, + } + const preferredTransports = this.negotiatedTransports() + if (preferredTransports.length === 0) { + throw new Error('Server did not negotiate a supported transport capability') + } + if (payload.webrtcEnabled === false) this.webrtcEnabled = false + if (typeof payload.webrtcFallbackTimeoutMs === 'number' + && Number.isSafeInteger(payload.webrtcFallbackTimeoutMs) + && payload.webrtcFallbackTimeoutMs > 0) { + this.serverNegotiateTimeoutMs = payload.webrtcFallbackTimeoutMs + } + if (this.lease) { + if (!this.negotiatedCapabilities.includes(this.dataMode === 'webrtc' ? WEBRTC_RESUME_CAPABILITY : RELAY_RESUME_CAPABILITY)) throw new Error('Server no longer supports control recovery') + clearTimeout(this.recoveryOpeningTimer) + this.recoveryAttempt = 0 + this.lease.tick(true) + return + } + this.sendControl('connect.request', { + hostDeviceId: this.options.targetDeviceId, + preferredTransports, + }) + return + } + if (frame.type === 'connect.accepted') { + if (this.connectionId !== undefined) throw new Error('Duplicate connect.accepted') + const payload = frame.payload as Partial + if (typeof payload.connectionId !== 'string' || payload.connectionId.length === 0) { + throw new Error('connect.accepted did not include a connectionId') + } + this.connectionId = payload.connectionId + if (this.negotiatedCapabilities.includes(WEBRTC_RESUME_CAPABILITY)) this.recoveryTicket = payload.recoveryTicket + if (this.negotiatedCapabilities.includes(RELAY_RESUME_CAPABILITY)) this.relayRecoveryTicket = payload.relayRecoveryTicket + const assignment = payload as RelayAssignment + if (typeof assignment.relayEndpoint === 'string' && typeof assignment.relayTicket === 'string') { + this.relayAssignment = assignment + } + this.clearHandshake() + void this.negotiate(lifetime.signal).catch(error => { + if (this.lifetime === lifetime) this.failConnection(error instanceof Error ? error : new Error('Adaptive transport negotiation failed')) + }) + return + } + if (frame.type === 'connection.lease.ack') { + if (!this.lease) throw new Error('Unexpected connection lease') + this.lease.acknowledge(frame.payload as ConnectionLeaseAck) + return + } + if (frame.type === 'connect.rejected' || frame.type === 'error') { + const payload = frame.payload as { message?: unknown; code?: unknown; retryable?: unknown } + const message = typeof payload.message === 'string' ? payload.message : 'Server rejected the connection' + const failure = Object.assign(new Error(message), { code: payload.code, retryable: payload.retryable }) + const code = errorCodeSchema.safeParse(payload.code) + this.failConnection(failure, { + reason: payload.retryable === true ? 'control-error' : 'invalid-control-frame', + ...(code.success ? { errorCode: code.data } : {}), + }) + return + } + if (frame.type === 'relay') { + if (this.dataSocket !== undefined) return + if (this.dataMode !== 'relay') return + this.handleRelay(frame.payload as Partial) + return + } + if (frame.type === 'secure.handshake') { + const payload = frame.payload as Partial + if (payload.connectionId !== this.connectionId + || payload.targetDeviceId !== this.options.deviceId + || !Number.isSafeInteger(payload.step) + || typeof payload.data !== 'string') { + throw new Error('Received a secure handshake frame for an unknown connection') + } + const data = fromBase64Url(payload.data) + for (const handler of this.handshakeHandlers) handler(payload.step!, data) + return + } + if (frame.type === 'signal.answer') { + const payload = frame.payload as { connectionId?: unknown; targetDeviceId?: unknown; sdp?: unknown } + if (payload.connectionId === this.connectionId && typeof payload.sdp === 'string') { + this.rtc?.handleSignal({ type: 'answer', sdp: payload.sdp }) + } + return + } + if (frame.type === 'signal.ice') { + const payload = frame.payload as { connectionId?: unknown; candidate?: unknown } + if (payload.connectionId === this.connectionId && isObject(payload.candidate)) { + this.rtc?.handleSignal({ type: 'ice', candidate: payload.candidate }) + } + return + } + if (frame.type === 'signal.offer' || frame.type === 'transport.selected') return + if (frame.type === 'ping') this.sendControl('pong', frame.payload) + } catch (error) { + const failure = error instanceof Error ? error : new Error('Invalid adaptive control frame') + if (!('code' in failure)) Object.assign(failure, { code: 'INVALID_MESSAGE' }) + const code = errorCodeSchema.safeParse((failure as Error & { code?: unknown }).code) + this.failConnection(failure, { reason: 'invalid-control-frame', ...(code.success ? { errorCode: code.data } : {}) }) + } + } + + private handleRelay(payload: Partial): void { + if (payload.connectionId !== this.connectionId + || payload.targetDeviceId !== this.options.deviceId + || !Number.isSafeInteger(payload.counter) + || typeof payload.ciphertext !== 'string') { + throw new Error('Received a relay frame for an unknown connection') + } + const data = fromBase64Url(payload.ciphertext) + this.bytesReceived += data.byteLength + this.emit(data) + } + + private async negotiate(signal: AbortSignal): Promise { + if (this.connectionId === undefined) return + const preferred = this.negotiatedTransports() + const wantWebRtc = !this.options.forceRelay && this.webrtcEnabled + && (preferred.includes('lan') || preferred.includes('p2p') || preferred.includes('turn')) + let selected: SelectedTransport = 'relay' + this.lastRtcDiagnostics = undefined + if (wantWebRtc) { + try { + const rtcSelected = (await this.tryWebRtc(signal)).transport + throwIfAborted(signal) + const wireSelected = rtcSelected === 'lan' && !preferred.includes('lan') && preferred.includes('p2p') + ? 'p2p' + : rtcSelected + if (!preferred.includes(wireSelected)) { + await this.rtc?.close() + throwIfAborted(signal) + this.rtc = undefined + if (!preferred.includes('relay')) { + throw new Error(`WebRTC selected unnegotiated transport: ${rtcSelected}`) + } + this.dataMode = 'relay' + selected = 'relay' + } else { + this.dataMode = 'webrtc' + selected = wireSelected + } + } catch (error) { + throwIfAborted(signal) + const reason = error instanceof Error ? error : new Error('WebRTC negotiation failed.') + try { this.options.onWebRtcFallback?.(reason, this.lastRtcDiagnostics) } catch { /* diagnostics must not block fallback */ } + await this.rtc?.close() + throwIfAborted(signal) + this.rtc = undefined + if (!preferred.includes('relay')) throw reason + this.dataMode = 'relay' + selected = 'relay' + } + } else { + if (!preferred.includes('relay')) throw new Error('No negotiated transport is available') + this.dataMode = 'relay' + selected = 'relay' + } + this.selected = selected + if (selected === 'relay' && this.relayAssignment !== undefined) { + await this.openDataSocket(this.relayAssignment) + } + const turnNode = selected === 'turn' ? this.rtc?.selectedRelayUrl() : undefined + this.sendControl('transport.selected', { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + transport: selected, + ...(turnNode === undefined ? {} : { turnNode }), + } satisfies TransportSelectedPayload) + this.finishConnection() + } + + private negotiatedTransports(): Array<'lan' | 'p2p' | 'turn' | 'relay'> { + const preferred = this.options.forceRelay === true + ? ['relay'] as const + : this.options.preferredTransports ?? DEFAULT_PREFERRED_TRANSPORTS + return preferred.filter(transport => { + if (transport === 'lan') return this.negotiatedCapabilities.includes('transport.lan') + if (transport === 'p2p') return this.negotiatedCapabilities.includes('transport.p2p') + return this.negotiatedCapabilities.includes(`transport.${transport}`) + }) + } + + private async tryWebRtc(signal: AbortSignal): Promise<{ transport: RtcSelectedTransport, relayUrl?: string }> { + const connectionId = this.connectionId + if (connectionId === undefined) throw new RtcConnectError('RTC_UNAVAILABLE', 'No connection id for WebRTC negotiation.') + const factory = this.options.rtcFactory + ?? (typeof RTCPeerConnection === 'undefined' ? undefined : browserRtcFactory()) + if (factory === undefined) { + throw new RtcConnectError('RTC_UNAVAILABLE', 'No RTC backend is available in this environment.') + } + let iceServers: RtcIceServer[] = [] + try { + iceServers = await this.fetchIceServers(connectionId, signal) + } catch { + // TURN/STUN unavailable: still attempt direct P2P with host candidates. + iceServers = [] + } + throwIfAborted(signal) + const negotiatedMs = negotiateTimeout(this.serverNegotiateTimeoutMs, this.options.negotiateTimeoutMs) + // Without STUN/TURN servers only same-LAN host candidates can succeed; + // fail fast instead of waiting the full timeout on cross-network links. + const effectiveNegotiateTimeoutMs = iceServers.length === 0 + ? Math.min(negotiatedMs ?? DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS, DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS) + : negotiatedMs + const rtc = new RtcDataChannelTransport({ + role: 'initiator', + factory, + iceServers, + // A TURN-only attempt must constrain ICE itself. Otherwise a faster + // direct pair wins, then gets rejected as an unnegotiated transport. + iceTransportPolicy: this.negotiatedTransports().includes('turn') + && !this.negotiatedTransports().some(transport => transport === 'lan' || transport === 'p2p') + ? 'relay' + : 'all', + onSignal: signal => this.sendRtcSignal(signal), + negotiateTimeoutMs: effectiveNegotiateTimeoutMs, + label: `client->${this.options.targetDeviceId}`, + onDiagnostic: event => { + this.lastRtcDiagnostics = event.diagnostics + try { this.options.onWebRtcDiagnostic?.(event) } catch { /* diagnostics must not block negotiation */ } + }, + }) + this.rtc = rtc + rtc.onMessage(data => { + if (this.lease && !this.lease.valid()) return + this.bytesReceived += data.byteLength + this.emit(data) + }) + rtc.onClose(() => { + // A negotiation failure closes the provisional data channel before this + // transport switches to Relay. That is not a loss of the established + // Adaptive transport, so only surface closes from an active WebRTC path. + if (this.rtc === rtc && this.dataMode === 'webrtc') { + const transport = this.selected + this.failConnection(new Error('Active WebRTC channel closed'), { + reason: 'webrtc-closed', + ...(transport === 'lan' || transport === 'p2p' || transport === 'turn' ? { transport } : {}), + }) + } + }) + try { + await rtc.connect(signal) + } catch (error) { + throwIfAborted(signal) + this.lastRtcDiagnostics = rtc.diagnostics() + await rtc.close() + if (this.rtc === rtc) this.rtc = undefined + throwIfAborted(signal) + throw error + } + throwIfAborted(signal) + this.lastRtcDiagnostics = rtc.diagnostics() + return { transport: rtc.selectedTransport() ?? 'p2p', relayUrl: rtc.selectedRelayUrl() } + } + + markSecureReady(): void { + const ticket = this.dataMode === 'webrtc' ? this.recoveryTicket : this.dataReady && this.dataSocket?.readyState === WebSocket.OPEN ? this.relayRecoveryTicket : undefined + if (!ticket || !this.connectionId || this.lease) return + this.lease = new ControlLease(this.connectionId, ticket, payload => { + if (this.controlReady && this.lastControlReceivedAt !== undefined && Date.now() - this.lastControlReceivedAt >= 75_000) { + this.controlLost(new Error('Control heartbeat timed out'), { reason: 'control-error' }) + throw new Error('Control heartbeat timed out') + } + this.sendControl('connection.lease.request', payload) + }, () => this.failConnection(Object.assign(new Error('Control authorization lease expired'), { code: 'TRANSPORT_CLOSED', retryable: true }))) + this.lease.start() + } + + private controlLost(error: Error, diagnostic: AdaptiveDisconnectDiagnostic): void { + if ((error as Error & { retryable?: boolean }).retryable === false || !this.lease?.canDetach() + || !(this.dataMode === 'webrtc' ? this.rtc?.getStats().connected : this.dataReady && this.dataSocket?.readyState === WebSocket.OPEN)) { + this.failConnection(error, diagnostic) + return + } + const socket = this.socket + this.controlReady = false + this.socket = undefined + clearTimeout(this.recoveryOpeningTimer) + socket?.close() + if (this.recoveryTimer !== undefined) return + const delay = recoveryDelayMs(this.recoveryAttempt, diagnostic) + this.recoveryAttempt++ + this.recoveryTimer = setTimeout(() => { + this.recoveryTimer = undefined + void this.reopenControl() + }, delay) + } + + private async reopenControl(): Promise { + const lifetime = this.lifetime + if (!lifetime || !this.lease?.canDetach()) return + try { + const token = this.options.refreshAccessToken ? await this.options.refreshAccessToken() : this.options.accessToken + if (this.lifetime !== lifetime || !this.lease?.canDetach()) return + const socket = new WebSocket(this.url) + this.socket = socket + socket.binaryType = 'arraybuffer' + this.recoveryOpeningTimer = setTimeout(() => { + if (this.socket === socket) this.controlLost(new Error('Control recovery handshake timed out'), { reason: 'control-error' }) + }, 15_000) + socket.onopen = () => { + if (this.socket !== socket || this.lifetime !== lifetime) return + this.sendControl('hello', { role: this.options.role, deviceId: this.options.deviceId, + accessToken: token, protocols: [PROTOCOL_VERSION], capabilities: this.options.capabilities ?? DEFAULT_CAPABILITIES }) + } + socket.onmessage = event => { + if (this.socket === socket && this.lifetime === lifetime) void this.handleSocketMessage(event.data, lifetime) + } + socket.onerror = () => { + if (this.socket === socket) this.controlLost(new Error('Control recovery failed'), { reason: 'control-error' }) + } + socket.onclose = event => { + if (this.socket === socket) this.controlLost(adaptiveControlCloseError(event), { reason: 'control-closed', closeCode: event.code, closeReason: event.reason }) + } + } catch (error) { + if (this.lifetime !== lifetime) return + if (typeof error === 'object' && error && (('retryable' in error && error.retryable === false) + || ('code' in error && ['AUTH_INVALID', 'DEVICE_REVOKED', 'MEMBERSHIP_REQUIRED', 'PEER_IDENTITY_MISMATCH', 'DEVICE_NOT_FOUND', 'TOKEN_REUSED'].includes(String(error.code))))) { + this.failConnection(error instanceof Error ? error : new Error('Control recovery authorization failed')) + } else this.controlLost(new Error('Control recovery unavailable'), { reason: 'control-error' }) + } + } + + private async fetchIceServers(connectionId: string, signal: AbortSignal): Promise { + if (this.options.fetchIceServers === undefined) return [] + return new Promise((resolve, reject) => { + const request = new AbortController() + let settled = false + const finish = (error?: Error, servers: RtcIceServer[] = []) => { + if (settled) return + settled = true + clearTimeout(timer) + signal.removeEventListener('abort', onAbort) + if (error) reject(error) + else resolve(servers) + } + const onAbort = () => { + finish(new Error('ICE configuration request was aborted')) + request.abort() + } + const timer = setTimeout(() => { + finish(new Error('ICE configuration request timed out')) + request.abort() + }, this.options.iceServersTimeoutMs ?? 10_000) + signal.addEventListener('abort', onAbort, { once: true }) + if (signal.aborted) { onAbort(); return } + Promise.resolve().then(() => { + throwIfAborted(request.signal) + return this.options.fetchIceServers!(connectionId, request.signal) + }).then( + servers => finish(undefined, servers), + error => finish(error instanceof Error ? error : new Error('ICE configuration request failed')), + ) + }) + } + + private sendRtcSignal(signal: RtcSignal): void { + if (this.connectionId === undefined) return + if (signal.type === 'offer') { + this.sendControl('signal.offer', { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + sdp: signal.sdp, + }) + } else if (signal.type === 'answer') { + this.sendControl('signal.answer', { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + sdp: signal.sdp, + }) + } else { + this.sendControl('signal.ice', { + connectionId: this.connectionId, + targetDeviceId: this.options.targetDeviceId, + candidate: signal.candidate, + }) + } + } + + private async openDataSocket(assignment: RelayAssignment): Promise { + if (this.connectionId === undefined || this.dataSocket !== undefined) return + const socket = new WebSocket(assignment.relayEndpoint!) + socket.binaryType = 'arraybuffer' + this.dataSocket = socket + await new Promise((resolve, reject) => { + const timer = setTimeout(() => { + reject(new Error('Relay data attach timed out')) + socket.close() + }, this.options.handshakeTimeoutMs ?? 15_000) + socket.onopen = () => socket.send(encodeRelayDataFrame(createRelayDataFrame('relay.attach', { + connectionId: this.connectionId, + deviceId: this.options.deviceId, + peerDeviceId: this.options.targetDeviceId, + ticket: assignment.relayTicket, + }), this.controlFrameLimits)) + socket.onmessage = event => { + try { + if (typeof event.data !== 'string') throw new Error('Relay data frames must be text JSON') + const data = decodeRelayDataFrame(event.data, this.controlFrameLimits) + if (data.type === 'relay.ready') { + if (data.payload.connectionId !== this.connectionId + || (assignment.relayEpoch !== undefined && data.payload.epoch !== assignment.relayEpoch)) { + throw new Error('Relay data attach assignment mismatch') + } + clearTimeout(timer) + this.dataReady = true + resolve() + return + } + void this.handleDataSocketFrame(data.type, data.payload).catch(error => { + this.failConnection(error instanceof Error ? error : new Error('Invalid Relay data frame')) + }) + } catch (error) { + clearTimeout(timer) + reject(error instanceof Error ? error : new Error('Invalid Relay data frame')) + this.failConnection(error instanceof Error ? error : new Error('Invalid Relay data frame')) + } + } + socket.onerror = () => { + clearTimeout(timer) + reject(new Error('Relay data socket failed')) + } + socket.onclose = () => { + clearTimeout(timer) + if (!this.dataReady) reject(new Error('Relay data socket closed before attach')) + else this.failConnection(new Error('Relay data socket closed')) + } + }) + } + + private async handleDataSocketFrame(type: string, payload: Record): Promise { + if (type === 'relay.detach') { + this.failConnection(new Error('Relay peer detached')) + return + } + if (type === 'ping') { + if (this.dataSocket?.readyState === WebSocket.OPEN) { + this.dataSocket.send(encodeRelayDataFrame(createRelayDataFrame('pong', payload), this.controlFrameLimits)) + } + return + } + if (type === 'relay') { + if (payload.connectionId !== this.connectionId || payload.targetDeviceId !== this.options.deviceId + || !Number.isSafeInteger(payload.counter) || typeof payload.ciphertext !== 'string') { + throw new Error('Received a relay frame for an unknown connection') + } + const data = fromBase64Url(payload.ciphertext) + this.bytesReceived += data.byteLength + this.emit(data) + return + } + if (type === 'secure.handshake') { + if (payload.connectionId !== this.connectionId || payload.targetDeviceId !== this.options.deviceId + || !Number.isSafeInteger(payload.step) || typeof payload.data !== 'string') { + throw new Error('Received a secure handshake frame for an unknown connection') + } + const data = fromBase64Url(payload.data) + for (const handler of this.handshakeHandlers) handler(payload.step as number, data) + } + } + + private sendControl(type: Parameters[0], payload: unknown): void { + if (this.socket?.readyState !== WebSocket.OPEN) throw Object.assign(new Error('adaptive control socket is not open'), { code: 'TRANSPORT_CLOSED' }) + this.socket.send(encodeControlFrame(createControlFrame(type, payload), this.controlFrameLimits)) + this.lastControlSentAt = Date.now() + } + + private finishConnection(): void { + this.clearHandshake() + this.removeAbort?.() + this.removeAbort = undefined + this.connectedAt ??= Date.now() + this.readyResolve?.() + this.readyResolve = undefined + this.readyReject = undefined + } + + private failConnection(error: Error, diagnostic?: AdaptiveDisconnectDiagnostic): void { + if (this.lease && this.connectionId && this.socket?.readyState === WebSocket.OPEN) { + try { this.sendControl('connection.lease.close', { connectionId: this.connectionId }) } catch { /* local cleanup proceeds */ } + } + const established = this.connectedAt !== undefined + this.controlReady = false + // Start every new connection lifetime from a fresh backoff sequence; the + // counter is reset on a successful recovery hello too, but a terminal + // failure here must not inherit (or leak) a previous lifetime's attempt + // count when the transport is reused. + this.recoveryAttempt = 0 + this.lease?.stop() + this.lease = undefined + this.recoveryTicket = undefined + this.relayRecoveryTicket = undefined + clearTimeout(this.recoveryTimer) + clearTimeout(this.recoveryOpeningTimer) + this.recoveryTimer = undefined + this.clearHandshake() + const reject = this.readyReject + this.readyResolve = undefined + this.readyReject = undefined + this.removeAbort?.() + this.removeAbort = undefined + const lifetime = this.lifetime + this.lifetime = undefined + const rtc = this.rtc + const socket = this.socket + const dataSocket = this.dataSocket + this.rtc = undefined + this.socket = undefined + this.dataSocket = undefined + this.dataReady = false + this.relayAssignment = undefined + this.connectionId = undefined + this.connectedAt = undefined + lifetime?.abort() + reject?.(error) + void rtc?.close() + dataSocket?.close() + socket?.close() + if (established && diagnostic !== undefined) { + try { this.options.onDisconnect?.(diagnostic) } catch { /* diagnostics must not prevent close */ } + } + if (socket !== undefined || established) this.emitClose(error) + } + + private clearHandshake(): void { + if (this.handshakeTimer !== undefined) clearTimeout(this.handshakeTimer) + this.handshakeTimer = undefined + } +} + +function adaptiveControlCloseError(event: CloseEvent): Error { + // Close semantics live in @dsh-remote/protocol: the reason string is the + // semantic key because deployments disagree on the code (self-hosted Server + // sends 4009/'server shutdown', the hosted Server closes with + // 4001/'server shutdown' and reserves 4009 for heartbeat expiry). Only an + // expected Server outage, a peer heartbeat expiry or a documented transient + // code is retryable; authorization, replacement, protocol and unknown + // application codes stay terminal, exactly as before this change. + const serverShutdown = isServerShutdownClose(event.code, event.reason) + const heartbeatTimeout = isHeartbeatTimeoutClose(event.code, event.reason) + const reason = event.reason.trim().slice(0, 300) + const detail = reason.length > 0 + ? `${reason} (WebSocket ${event.code})` + : `WebSocket closed with code ${event.code}` + return Object.assign(new Error(`Adaptive control channel closed: ${detail}`), { + // Preserve the specific self-hosted authorization reasons so the Client + // runtime can surface a terminal reauthorization state instead of a generic + // transport loss (PR #285). Every other close keeps the shared semantics. + code: event.code === 4003 ? 'CONNECTION_REPLACED' + : event.code === 4001 && ['AUTH_INVALID', 'TOKEN_EXPIRED', 'DEVICE_REVOKED'].includes(reason) + ? reason : 'TRANSPORT_CLOSED', + retryable: serverShutdown || heartbeatTimeout + || [1000, 1001, 1006, 1011, 1012, 1013].includes(event.code), + }) +} + +/** Full-jitter window of every control-recovery attempt. */ +export const CONTROL_RECOVERY_MAX_DELAY_MS = 15_000 + +/** + * Delay before the next control-recovery attempt. + * + * `attempt` is the index of the attempt *about to be scheduled*: 0 is the + * first retry after losing the control channel. + * + * Every disconnect backs off into the widest window (`[0, 15s]`, full jitter) + * and stays there: a short outage still recovers quickly on average, while a + * tight retry loop against a failing control plane is impossible. The Server + * restart reason is classified separately for session retention but no longer + * changes the delay, because a restart is already the worst case of the same + * window. + */ +export function recoveryDelayMs(_attempt: number, _diagnostic: AdaptiveDisconnectDiagnostic): number { + return Math.random() * CONTROL_RECOVERY_MAX_DELAY_MS +} + +function isObject(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value) +} + +function socketState(readyState: number | undefined): AdaptiveConnectionDetails['controlChannelState'] { + if (readyState === 0) return 'connecting' + if (readyState === 1) return 'open' + if (readyState === 2) return 'closing' + return 'closed' +} + +function negotiateTimeout(serverMs: number | undefined, localMs: number | undefined): number | undefined { + // An explicit local setting wins; the server fallback hint must never be + // able to stretch a mobile client's WebRTC wait beyond its own budget. + if (localMs !== undefined) return localMs + if (serverMs === undefined) return undefined + return Math.min(SERVER_NEGOTIATE_TIMEOUT_MAX_MS, Math.max(SERVER_NEGOTIATE_TIMEOUT_MIN_MS, serverMs)) +} + +const DEFAULT_EMPTY_ICE_NEGOTIATE_TIMEOUT_MS = 4_000 +const SERVER_NEGOTIATE_TIMEOUT_MIN_MS = 6_000 +const SERVER_NEGOTIATE_TIMEOUT_MAX_MS = 12_000 + +// React Native AbortSignal implementations may omit throwIfAborted(). +function throwIfAborted(signal: AbortSignal | undefined): void { + if (signal?.aborted) throw new Error('Adaptive connection was aborted') +}