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') }