diff --git a/packages/webrtc/tests/relay-transport.test.ts b/packages/webrtc/tests/relay-transport.test.ts new file mode 100644 index 0000000..f7995f4 --- /dev/null +++ b/packages/webrtc/tests/relay-transport.test.ts @@ -0,0 +1,898 @@ +import { runScenarios, scenarioName } from '../../../scripts/test-scenarios.mjs' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { createControlFrame } from '@dsh-remote/protocol' +import { + AdaptiveTransport, + RelayTransport, + RtcDataChannelTransport, + type AdaptiveTransportOptions, + type RtcPeerConnectionFactory, +} from '../src/index.js' + +class FakeWebSocket { + static readonly OPEN = 1 + static latest?: FakeWebSocket + static instances: FakeWebSocket[] = [] + readyState = 0 + binaryType = '' + sent: string[] = [] + onopen: (() => void) | null = null + onmessage: ((event: { data: string | ArrayBuffer | Blob }) => void) | null = null + onerror: (() => void) | null = null + onclose: ((event: { code: number; reason: string }) => void) | null = null + + constructor(readonly url: string) { + FakeWebSocket.latest = this + FakeWebSocket.instances.push(this) + } + + open(): void { + this.readyState = FakeWebSocket.OPEN + this.onopen?.() + } + + receive(value: unknown): void { + this.receiveRaw(JSON.stringify(value)) + } + + receiveRaw(data: string | ArrayBuffer | Blob): void { + this.onmessage?.({ data }) + } + + send(value: string): void { + this.sent.push(value) + } + + close(): void { + this.readyState = 3 + } +} + +const cleanupScenario1 = () => { + vi.useRealTimers() + vi.restoreAllMocks() + vi.unstubAllGlobals() + FakeWebSocket.latest = undefined + FakeWebSocket.instances = [] +} +afterEach(cleanupScenario1) + +describe('RelayTransport control handshake', () => { + it('attaches an independent data socket when the Server assigns one', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new RelayTransport('wss://remote.example/ws/v1/connect', { + role: 'client', deviceId: 'client-1', accessToken: 'access-token', targetDeviceId: 'host-1', + }) + const connecting = transport.connect() + const control = FakeWebSocket.latest! + control.open() + control.receive(helloAck({ capabilities: ['transport.relay', 'transport.relay.attach'] })) + await Promise.resolve() + control.receive(createControlFrame('connect.accepted', { + connectionId: 'connection-1', + relayEndpoint: 'wss://relay.example/ws', + relayTicket: 'dshrt.payload.signature', + relayNodeId: 'relay-1', + relayEpoch: 4, + })) + await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2)) + const data = FakeWebSocket.instances[1]! + data.open() + expect(JSON.parse(data.sent[0]!)).toMatchObject({ + type: 'relay.attach', + payload: { connectionId: 'connection-1', deviceId: 'client-1', peerDeviceId: 'host-1', ticket: 'dshrt.payload.signature' }, + }) + data.receive({ v: 1, id: 'ready', type: 'relay.ready', timestamp: Date.now(), payload: { connectionId: 'connection-1', epoch: 4 } }) + await connecting + await transport.sendHandshake(1, new Uint8Array([1, 2, 3])) + await transport.send(new TextEncoder().encode('encrypted-frame')) + expect(control.sent.filter(frame => JSON.parse(frame).type === 'secure.handshake')).toHaveLength(1) + expect(JSON.parse(data.sent[1]!)).toMatchObject({ type: 'relay', payload: { connectionId: 'connection-1', targetDeviceId: 'host-1', counter: 0 } }) + expect(control.sent.filter(frame => JSON.parse(frame).type === 'relay')).toHaveLength(0) + }) + + it('waits for authorization and sends canonical relay frames', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new RelayTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + }) + let connected = false + const connecting = transport.connect().then(() => { connected = true }) + const socket = FakeWebSocket.latest! + socket.open() + + expect(JSON.parse(socket.sent[0]!)).toMatchObject({ + v: 1, + type: 'hello', + payload: { role: 'client', deviceId: 'client-1', accessToken: 'access-token', protocols: [1] }, + }) + expect(connected).toBe(false) + + socket.receive(createControlFrame('hello.ack', { + protocol: 1, + serverVersion: '0.1.0', + connectionSessionId: 'control-1', + heartbeatIntervalMs: 25_000, + maxControlFrameBytes: 65_536, + maxRelayFrameBytes: 1_048_576, + capabilities: ['transport.relay'], + })) + await Promise.resolve() + expect(JSON.parse(socket.sent[1]!)).toMatchObject({ + v: 1, + type: 'connect.request', + payload: { hostDeviceId: 'host-1', preferredTransports: ['relay'] }, + }) + expect(connected).toBe(false) + + socket.receive(createControlFrame('connect.accepted', { + connectionId: 'connection-1', + })) + await connecting + expect(transport.connectionInfo()).toEqual({ + connectionId: 'connection-1', + localDeviceId: 'client-1', + remoteDeviceId: 'host-1', + }) + await transport.sendHandshake(1, new Uint8Array([1, 2, 3])) + await transport.send(new TextEncoder().encode('encrypted-frame')) + + expect(JSON.parse(socket.sent[2]!)).toMatchObject({ + type: 'secure.handshake', + payload: { connectionId: 'connection-1', targetDeviceId: 'host-1', step: 1, data: 'AQID' }, + }) + const relay = JSON.parse(socket.sent[3]!) + expect(relay).toMatchObject({ + v: 1, + type: 'relay', + payload: { connectionId: 'connection-1', targetDeviceId: 'host-1', counter: 0 }, + }) + expect(relay.payload.ciphertext).not.toContain('encrypted-frame') + }) + + it('rejects a capability that the Client did not offer', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new RelayTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + }) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(createControlFrame('hello.ack', { + protocol: 1, + serverVersion: '0.1.0', + connectionSessionId: 'control-1', + heartbeatIntervalMs: 25_000, + maxControlFrameBytes: 65_536, + maxRelayFrameBytes: 1_048_576, + capabilities: ['transport.p2p'], + })) + await expect(connecting).rejects.toThrow('did not offer') + }) + + it('enforces the negotiated Relay limit before updating send statistics', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new RelayTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + }) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ + capabilities: ['transport.relay'], + maxRelayFrameBytes: 180, + })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await connecting + + await expect(transport.send(new Uint8Array(256))).rejects.toThrow('Relay frame exceeds') + expect(transport.getStats().bytesSent).toBe(0) + }) + + it('rejects binary Control frames before decoding them', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new RelayTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + }) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receiveRaw(new ArrayBuffer(2 * 1024 * 1024)) + + await expect(connecting).rejects.toThrow('must be text JSON') + }) +}) + +describe('AdaptiveTransport capability negotiation', () => { + it('moves Relay ciphertext to the assigned data socket while keeping handshake on control', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport({ forceRelay: true }) + const connecting = transport.connect() + const control = FakeWebSocket.latest! + control.open() + control.receive(helloAck({ capabilities: ['transport.relay', 'transport.relay.attach'] })) + await Promise.resolve() + control.receive(createControlFrame('connect.accepted', { + connectionId: 'connection-1', + relayEndpoint: 'wss://relay.example/ws', + relayTicket: 'dshrt.payload.signature', + relayNodeId: 'relay-1', + relayEpoch: 4, + })) + await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2)) + const data = FakeWebSocket.instances[1]! + data.open() + expect(JSON.parse(data.sent[0]!)).toMatchObject({ type: 'relay.attach', payload: { connectionId: 'connection-1' } }) + data.receive({ v: 1, id: 'ready', type: 'relay.ready', timestamp: Date.now(), payload: { connectionId: 'connection-1', epoch: 4 } }) + await connecting + await transport.sendHandshake(1, new Uint8Array([7])) + await transport.send(new Uint8Array([8, 9])) + expect(lastSentPayload(control, 'secure.handshake')).toMatchObject({ connectionId: 'connection-1' }) + expect(JSON.parse(data.sent[1]!)).toMatchObject({ type: 'relay', payload: { connectionId: 'connection-1', counter: 0 } }) + expect(lastSentPayload(control, 'transport.selected')).toMatchObject({ transport: 'relay' }) + }) + + it('retains a confirmed independent Relay socket across control loss without resetting the relay counter', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + // Every recovery is now delayed: the restart window is drawn from + // Math.random(), so drive it with fake timers instead of wall-clock waits. + const random = vi.spyOn(Math, 'random').mockReturnValue(0) + const transport = createAdaptiveTransport({ forceRelay: true, refreshAccessToken: async () => 'fresh-token' }) + const closed = vi.fn() + transport.onClose(closed) + try { + const connecting = transport.connect() + const control = FakeWebSocket.latest! + control.open() + control.receive(helloAck({ capabilities: ['transport.relay', 'transport.relay.attach', 'transport.relay.resume.v1'] })) + control.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1', relayEndpoint: 'wss://relay.example/ws', relayTicket: 'attach', relayEpoch: 4, relayRecoveryTicket: 'recovery' })) + await vi.waitFor(() => expect(FakeWebSocket.instances).toHaveLength(2)) + const data = FakeWebSocket.instances[1]! + data.open() + data.receive({ v: 1, id: 'ready', type: 'relay.ready', timestamp: Date.now(), payload: { connectionId: 'connection-1', epoch: 4 } }) + await connecting + transport.markSecureReady() + const lease = lastSentPayload(control, 'connection.lease.request') + control.receive(createControlFrame('connection.lease.ack', { ...lease, ticket: 'renewed', leaseMs: 300_000 })) + await transport.send(Uint8Array.of(1)) + control.readyState = 3 + control.onclose?.({ code: 1012, reason: 'restart' }) + await transport.send(Uint8Array.of(2)) + const relayFrames = data.sent.map(raw => JSON.parse(raw)).filter(frame => frame.type === 'relay') + expect(relayFrames.map(frame => frame.payload.counter)).toEqual([0, 1]) + expect(transport.getStats().connected).toBe(true) + expect(closed).not.toHaveBeenCalled() + // The recovery timer is scheduled on a microtask after controlLost(); + // with Math.random() = 0 the delay is 0ms, so a single macrotask turn + // fires it and the new control socket exists. + await new Promise(resolve => setTimeout(resolve, 10)) + expect(random).toHaveBeenCalled() + expect(FakeWebSocket.instances).toHaveLength(3) + const recovered = FakeWebSocket.latest! + recovered.open() + recovered.receive(helloAck({ capabilities: ['transport.relay', 'transport.relay.attach', 'transport.relay.resume.v1'] })) + expect(lastSentPayload(recovered, 'connection.lease.request')).toMatchObject({ connectionId: 'connection-1', ticket: 'renewed' }) + data.readyState = 3 + data.onclose?.({ code: 1006, reason: '' }) + await vi.waitFor(() => expect(closed).toHaveBeenCalledOnce()) + } finally { await transport.close() } + }) + + it('closes an established WebRTC data channel when the Control socket closes', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const disconnected = vi.fn() + const closed = vi.fn() + const transport = createAdaptiveTransport({ rtcFactory: rtc.factory, onDisconnect: disconnected }) + transport.onClose(closed) + + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.relay'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await vi.waitFor(() => expect(rtc.channel.onopen).toBeTypeOf('function')) + rtc.channel.readyState = 'open' + rtc.channel.onopen?.() + await connecting + expect(transport.getStats().connected).toBe(true) + + await transport.send(Uint8Array.of(1, 2, 3)) + expect(rtc.channel.send).toHaveBeenCalledOnce() + socket.readyState = 3 + socket.onclose?.({ code: 1012, reason: 'Server restart' }) + + await vi.waitFor(() => expect(rtc.channel.close).toHaveBeenCalledOnce()) + expect(rtc.pc.close).toHaveBeenCalledOnce() + expect(transport.getStats().connected).toBe(false) + expect(disconnected).toHaveBeenCalledWith({ reason: 'control-closed', closeCode: 1012, closeReason: 'Server restart' }) + expect(closed).toHaveBeenCalledOnce() + await expect(transport.send(Uint8Array.of(4))).rejects.toThrow('not been authorized') + }) + + it('retains confirmed WebRTC data while reauthenticating control without creating a new logical connection', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const refresh = vi.fn(async () => 'fresh-access-token') + const transport = createAdaptiveTransport({ rtcFactory: rtc.factory, refreshAccessToken: refresh }) + const closed = vi.fn() + transport.onClose(closed) + try { + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.webrtc.resume.v1'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1', recoveryTicket: 'initial' })) + await vi.waitFor(() => expect(rtc.channel.onopen).toBeTypeOf('function')) + rtc.channel.readyState = 'open' + rtc.channel.onopen?.() + await connecting + transport.markSecureReady() + const request = lastSentPayload(socket, 'connection.lease.request') + socket.receive(createControlFrame('connection.lease.ack', { ...request, ticket: 'renewed', leaseMs: 300_000 })) + // Every recovery is scheduled with a full-jitter delay now; Math.random() + // = 0 keeps it at 0ms so a single macrotask turn fires the retry. + vi.spyOn(Math, 'random').mockReturnValue(0) + socket.readyState = 3 + socket.onclose?.({ code: 1012, reason: 'restart' }) + await transport.connect() // Idempotent while only control is detached. + await transport.send(Uint8Array.of(1)) + expect(closed).not.toHaveBeenCalled() + expect(rtc.pc.close).not.toHaveBeenCalled() + await vi.waitFor(() => expect(FakeWebSocket.latest).not.toBe(socket)) + const recovered = FakeWebSocket.latest! + // The old control heartbeat is stale, but the new socket is still + // handshaking. A forced lease tick must not close it. + const internals = transport as unknown as { lastControlReceivedAt: number; lease: { tick(force: boolean): void } } + internals.lastControlReceivedAt = Date.now() - 80_000 + internals.lease.tick(true) + expect(FakeWebSocket.latest).toBe(recovered) + expect(recovered.readyState).toBe(0) + recovered.open() + expect(lastSentPayload(recovered, 'hello')).toMatchObject({ accessToken: 'fresh-access-token' }) + recovered.receive(helloAck({ capabilities: ['transport.p2p', 'transport.webrtc.resume.v1'] })) + const renewal = lastSentPayload(recovered, 'connection.lease.request') + expect(renewal).toMatchObject({ connectionId: 'connection-1', ticket: 'renewed' }) + expect(recovered.sent.map(raw => JSON.parse(raw).type)).not.toContain('connect.request') + recovered.receive(createControlFrame('connection.lease.ack', { ...renewal, ticket: 'recovered', leaseMs: 300_000 })) + // Old-socket callbacks must not close the retained session. + socket.onclose?.({ code: 4003, reason: 'stale replacement' }) + await transport.send(Uint8Array.of(2)) + expect(rtc.channel.send).toHaveBeenCalledTimes(2) + expect(closed).not.toHaveBeenCalled() + recovered.receive(createControlFrame('error', { code: 'DEVICE_REVOKED', message: 'revoked', retryable: false })) + await vi.waitFor(() => expect(closed).toHaveBeenCalledOnce()) + } finally { await transport.close() } + }) + + it('retains the session across both shutdown close codes and jitters only the first retry', async () => { + await runScenarios([ + { name: '4009/server shutdown', code: 4009, reason: 'server shutdown' }, + { name: '4001/server shutdown', code: 4001, reason: 'server shutdown' }, + ].map(row => ({ name: row.name, run: async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const random = vi.spyOn(Math, 'random').mockReturnValue(0.5) + const rtc = stalledRtc() + const transport = createAdaptiveTransport({ rtcFactory: rtc.factory }) + const closed = vi.fn() + transport.onClose(closed) + try { + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.webrtc.resume.v1'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1', recoveryTicket: 'initial' })) + await vi.waitFor(() => expect(rtc.channel.onopen).toBeTypeOf('function')) + rtc.channel.readyState = 'open' + rtc.channel.onopen?.() + await connecting + transport.markSecureReady() + const request = lastSentPayload(socket, 'connection.lease.request') + socket.receive(createControlFrame('connection.lease.ack', { ...request, ticket: 'renewed', leaseMs: 300_000 })) + const instancesBefore = FakeWebSocket.instances.length + + // Install fake timers just before the control close so every real + // event loop turn above stays untouched. + vi.useFakeTimers() + socket.readyState = 3 + socket.onclose?.({ code: row.code, reason: row.reason }) + // The lease keeps the authenticated WebRTC session alive, and a Server + // restart is spread over the full [0, 15s] window instead of stampeding. + expect(closed).not.toHaveBeenCalled() + expect(rtc.pc.close).not.toHaveBeenCalled() + await vi.advanceTimersByTimeAsync(5_000) + expect(FakeWebSocket.instances).toHaveLength(instancesBefore) + await vi.advanceTimersByTimeAsync(3_000) + expect(FakeWebSocket.instances).toHaveLength(instancesBefore + 1) + expect(closed).not.toHaveBeenCalled() + expect(random).toHaveBeenCalled() + } finally { + vi.useRealTimers() + await transport.close() + } + } })), cleanupScenario1) + }) + + it('retries the self-hosted heartbeat close without retrying authorization or unknown application closes', async () => { + await runScenarios([ + { code: 4001, reason: 'CONNECTION_FAILED', retryable: true }, + { code: 4001, reason: 'AUTH_INVALID', failure: 'AUTH_INVALID', retryable: false }, + { code: 4001, reason: 'TOKEN_EXPIRED', failure: 'TOKEN_EXPIRED', retryable: false }, + { code: 4001, reason: 'DEVICE_REVOKED', failure: 'DEVICE_REVOKED', retryable: false }, + { code: 4001, reason: '', retryable: false }, + { code: 4001, reason: 'CONNECTION_FAILED: unknown detail', retryable: false }, + { code: 4003, reason: 'CONNECTION_FAILED', retryable: false }, + { code: 1008, reason: 'CONNECTION_FAILED', retryable: false }, + // Close semantics are keyed on the reason: the hosted Server uses 4009 + // for heartbeat expiry and 4001 for hello/auth failures and shutdown. + { code: 4009, reason: 'heartbeat timeout', retryable: true }, + { code: 4009, reason: 'server shutdown', retryable: true }, + { code: 4001, reason: 'server shutdown', retryable: true }, + { code: 1013, reason: 'server shutdown', retryable: true }, + { code: 4009, reason: '', retryable: false }, + ].map(row => ({ name: `${row.code}/${row.reason}`, run: async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport({ forceRelay: true }) + const closed = vi.fn() + transport.onClose(closed) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.relay'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await connecting + socket.onclose?.(row) + expect(closed).toHaveBeenCalledOnce() + expect(closed).toHaveBeenCalledWith(expect.objectContaining({ + code: row.failure ?? (row.code === 4003 ? 'CONNECTION_REPLACED' : 'TRANSPORT_CLOSED'), retryable: row.retryable, + })) + await transport.close() + } })), cleanupScenario1) + }) + + it('reports established carrier failures without leaking control payloads or retrying old closes', async () => { + await runScenarios(['control-closed', 'control-error', 'retryable-control-error', 'invalid-control-frame', 'webrtc-closed', 'local-close'].map(reason => ({ + name: reason, run: async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const diagnostic = vi.fn() + const closed = vi.fn() + const rtc = reason === 'webrtc-closed' ? stalledRtc() : undefined + const transport = createAdaptiveTransport({ onDisconnect: diagnostic, ...(rtc === undefined ? {} : { rtcFactory: rtc.factory }) }) + transport.onClose(closed) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: rtc === undefined ? ['transport.relay'] : ['transport.p2p', 'transport.relay'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + if (rtc !== undefined) { + await vi.waitFor(() => expect(rtc.channel.onopen).toBeTypeOf('function')) + rtc.channel.readyState = 'open' + rtc.channel.onopen?.() + } + await connecting + if (reason === 'control-closed') socket.onclose?.({ code: 4003, reason: 'private upstream detail' }) + if (reason === 'control-error') socket.onerror?.() + if (reason === 'retryable-control-error') { + socket.receive(createControlFrame('error', { code: 'CONNECTION_FAILED', message: 'CONNECTION_FAILED', connectionId: 'connection-1', retryable: true })) + } + if (reason === 'invalid-control-frame') socket.receiveRaw('invalid private content') + if (rtc !== undefined) (rtc.channel as unknown as { onclose: () => void }).onclose() + if (reason === 'local-close') await transport.close() + expect(closed).toHaveBeenCalledOnce() + if (reason === 'control-closed') expect(closed).toHaveBeenCalledWith(expect.objectContaining({ code: 'CONNECTION_REPLACED', retryable: false })) + expect(transport.getStats().connected).toBe(false) + if (reason === 'local-close') expect(diagnostic).not.toHaveBeenCalled() + else expect(diagnostic.mock.calls).toEqual([[{ + reason: reason === 'retryable-control-error' ? 'control-error' : reason, + ...(reason === 'control-closed' ? { closeCode: 4003, closeReason: 'private upstream detail' } : {}), + ...(reason === 'webrtc-closed' ? { transport: 'p2p' } : {}), + ...(reason === 'retryable-control-error' ? { errorCode: 'CONNECTION_FAILED' } : {}), + ...(reason === 'invalid-control-frame' ? { errorCode: 'INVALID_MESSAGE' } : {}), + }]]) + socket.onclose?.({ code: 1006, reason: '' }) + expect(closed).toHaveBeenCalledOnce() + }, + })), cleanupScenario1) + }) + it('separates authorization from RTC timeout while clamping Server budgets', async () => { + await runScenarios([ + { name: 'old Server without timeout', server: undefined, local: undefined, budget: 8000 }, + { name: 'Server twenty seconds clamped to the mobile ceiling', server: 20000, local: undefined, budget: 12000 }, + { name: 'local budget wins over larger Server budget', server: 20000, local: 12000, budget: 12000 }, + { name: 'local budget exceeds Server budget', server: 8000, local: 12000, budget: 12000 }, + ].map(row => ({ name: row.name, run: async () => { + vi.useFakeTimers() + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const fallback = vi.fn() + const transport = createAdaptiveTransport({ + rtcFactory: rtc.factory, + negotiateTimeoutMs: row.local, + fetchIceServers: async () => [{ urls: 'stun:stun.example.test' }], + onWebRtcFallback: fallback, + }) + let ready = false + const connecting = transport.connect().then(() => { ready = true }) + const socket = FakeWebSocket.latest! + socket.open() + await vi.advanceTimersByTimeAsync(4000) + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.relay'], webrtcFallbackTimeoutMs: row.server })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await vi.advanceTimersByTimeAsync(row.budget - 1) + expect(ready).toBe(false) + expect(socket.readyState).toBe(FakeWebSocket.OPEN) + await vi.advanceTimersByTimeAsync(301) + await connecting + expect(fallback).toHaveBeenCalledOnce() + expect(lastSentPayload(socket, 'transport.selected')).toMatchObject({ transport: 'relay' }) + expect(rtc.pc.close).toHaveBeenCalled() + await transport.close() + expect(vi.getTimerCount()).toBe(0) + } })), cleanupScenario1) + }) + + it('bounds ICE discovery separately and ignores credentials arriving after cancellation or timeout', async () => { + await runScenarios(['timeout', 'close', 'socket close', 'abort', 'reconnect'].map(action => ({ name: action, run: async () => { + vi.useFakeTimers() + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const abort = new AbortController() + let deliver!: (servers: []) => void + let requestSignal: AbortSignal | undefined + const transport = createAdaptiveTransport({ rtcFactory: rtc.factory, signal: abort.signal, + fetchIceServers: (_id, signal) => { requestSignal = signal; return new Promise(resolve => { deliver = resolve }) }, + }) + const outcome = transport.connect().then(() => 'ready', error => error.message as string) + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.relay'], webrtcFallbackTimeoutMs: 20000 })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await vi.advanceTimersByTimeAsync(0) + if (action === 'timeout') { + await vi.advanceTimersByTimeAsync(10000) + expect(requestSignal?.aborted).toBe(true) + await vi.advanceTimersByTimeAsync(20300) + expect(await outcome).toBe('ready') + } else { + if (action === 'close' || action === 'reconnect') await transport.close() + else if (action === 'abort') abort.abort() + else socket.onclose?.({ code: 1006, reason: '' }) + expect(await outcome).not.toBe('ready') + expect(requestSignal?.aborted).toBe(true) + expect(rtc.factory.create).not.toHaveBeenCalled() + } + if (action === 'reconnect') { + const reconnecting = transport.connect() + const replacement = FakeWebSocket.latest! + replacement.open() + replacement.receive(helloAck({ capabilities: ['transport.relay'] })) + replacement.receive(createControlFrame('connect.accepted', { connectionId: 'connection-2' })) + await reconnecting + socket.onclose?.({ code: 1006, reason: 'late close' }) + expect(transport.connectionInfo().connectionId).toBe('connection-2') + expect(transport.getStats().connected).toBe(true) + } + const sent = socket.sent.length + deliver([]) + await vi.advanceTimersByTimeAsync(0) + expect(socket.sent).toHaveLength(sent) + await transport.close() + expect(vi.getTimerCount()).toBe(0) + } })), cleanupScenario1) + }) + + it('settles control and RTC cancellation without allowing stale attempts to select a transport', async () => { + await runScenarios(['control timeout', 'control close', 'rtc close', 'rtc abort', 'late RTC success', 'statistics timeout'].map(action => ({ name: action, run: async () => { + vi.useFakeTimers() + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const abort = new AbortController() + const transport = createAdaptiveTransport({ + rtcFactory: rtc.factory, + signal: abort.signal, + // Keep a wide negotiation window: these scenarios cancel in the + // middle of pending RTC, which must stay pending until acted on. + negotiateTimeoutMs: 20_000, + fetchIceServers: async () => [{ urls: 'stun:stun.example.test' }], + }) + const outcome = transport.connect().then(() => 'ready', error => error.message as string) + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.relay'], webrtcFallbackTimeoutMs: 20000 })) + if (!action.startsWith('control')) { + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await vi.advanceTimersByTimeAsync(16000) + } + if (action === 'late RTC success' || action === 'statistics timeout') { + if (action === 'statistics timeout') vi.spyOn(rtc.pc, 'getStats').mockImplementation(() => new Promise(() => {})) + rtc.channel.readyState = 'open' + rtc.channel.onopen?.() + await vi.advanceTimersByTimeAsync(300) + expect(await outcome).toBe('ready') + expect(lastSentPayload(socket, 'transport.selected')).toMatchObject({ transport: 'p2p' }) + } else { + if (action === 'control timeout') await vi.advanceTimersByTimeAsync(15000) + else if (action === 'rtc abort') abort.abort() + else await transport.close() + expect(await outcome).not.toBe('ready') + rtc.channel.onopen?.() + await vi.advanceTimersByTimeAsync(30000) + expect(socket.sent.some(frame => JSON.parse(frame).type === 'transport.selected')).toBe(false) + } + await transport.close() + expect(vi.getTimerCount()).toBe(0) + } })), cleanupScenario1) + }) + + it('records heartbeat diagnostics and replies to ping', async () => { + vi.useFakeTimers() + vi.setSystemTime(new Date('2026-09-29T01:00:00.000Z')) + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport() + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.relay'] })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await connecting + + vi.setSystemTime(new Date('2026-09-29T01:00:05.000Z')) + socket.receive(createControlFrame('ping', { nonce: 'heartbeat-1' })) + + expect(JSON.parse(socket.sent.at(-1)!)).toMatchObject({ + type: 'pong', + payload: { nonce: 'heartbeat-1' }, + }) + await expect(transport.connectionDetails()).resolves.toMatchObject({ + heartbeatIntervalMs: 25_000, + lastControlReceivedAt: Date.parse('2026-09-29T01:00:05.000Z'), + lastControlSentAt: Date.parse('2026-09-29T01:00:05.000Z'), + }) + }) + + it('updates receive activity for an ordinary control frame', async () => { + vi.useFakeTimers() + vi.setSystemTime(new Date('2026-09-29T02:00:00.000Z')) + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport() + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.relay'] })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await connecting + const before = await transport.connectionDetails() + + vi.setSystemTime(new Date('2026-09-29T02:00:07.000Z')) + socket.receive(createControlFrame('transport.selected', { + connectionId: 'connection-1', + targetDeviceId: 'client-1', + transport: 'relay', + })) + + await expect(transport.connectionDetails()).resolves.toMatchObject({ + lastControlReceivedAt: Date.parse('2026-09-29T02:00:07.000Z'), + lastControlSentAt: before.lastControlSentAt, + }) + }) + + it('constrains TURN-only ICE, preserves automatic ICE, and keeps Relay fallback', async () => { + await runScenarios([ + { name: 'TURN-only', preferred: ['turn', 'relay'] as const, policy: 'relay' }, + { name: 'automatic', preferred: ['lan', 'p2p', 'turn', 'relay'] as const, policy: 'all' }, + ].map(row => ({ name: row.name, run: async () => { + vi.useFakeTimers() + vi.stubGlobal('WebSocket', FakeWebSocket) + const rtc = stalledRtc() + const transport = createAdaptiveTransport({ + rtcFactory: rtc.factory, + preferredTransports: [...row.preferred], + negotiateTimeoutMs: 1000, + fetchIceServers: async () => [{ urls: 'turn:turn.example.test', username: 'user', credential: 'secret' }], + }) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p', 'transport.turn', 'transport.relay'] })) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await vi.advanceTimersByTimeAsync(1) + expect(rtc.factory.create).toHaveBeenCalledWith(expect.objectContaining({ iceTransportPolicy: row.policy })) + expect(lastSentPayload(socket, 'connect.request')).toMatchObject({ + preferredTransports: row.preferred.filter(value => value !== 'lan'), + }) + await vi.advanceTimersByTimeAsync(1300) + await connecting + expect(lastSentPayload(socket, 'transport.selected')).toMatchObject({ transport: 'relay' }) + await transport.close() + } })), cleanupScenario1) + }) + + it('requests only transports present in hello.ack capabilities', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = new AdaptiveTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + }) + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(createControlFrame('hello.ack', { + protocol: 1, + serverVersion: '0.1.0', + connectionSessionId: 'control-1', + heartbeatIntervalMs: 25_000, + maxControlFrameBytes: 65_536, + maxRelayFrameBytes: 1_048_576, + capabilities: ['transport.relay'], + })) + await Promise.resolve() + expect(JSON.parse(socket.sent[1]!)).toMatchObject({ + type: 'connect.request', + payload: { preferredTransports: ['relay'] }, + }) + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await connecting + }) + + it('rejects selected transports outside negotiated capabilities', async () => { + const rows = [ + { + name: 'preserves LAN when LAN was negotiated', + capabilities: ['transport.lan', 'transport.p2p'], + selected: 'lan' as const, + expected: 'lan', + }, + { + name: 'downgrades LAN for an older P2P-only server', + capabilities: ['transport.p2p'], + selected: 'lan' as const, + expected: 'p2p', + }, + { + name: 'falls back when TURN-only negotiation selects P2P', + capabilities: ['transport.turn', 'transport.relay'], + selected: 'p2p' as const, + expected: 'relay', + }, + { + name: 'rejects when P2P-only negotiation selects TURN', + capabilities: ['transport.p2p'], + selected: 'turn' as const, + expected: 'reject', + }, + ] as const + await runScenarios( + rows.map((row, index) => { + const { capabilities, selected, expected } = row + return { + name: scenarioName('$name', row, index), + run: async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + vi.spyOn(RtcDataChannelTransport.prototype, 'connect').mockResolvedValue() + vi.spyOn(RtcDataChannelTransport.prototype, 'selectedTransport').mockReturnValue(selected) + vi.spyOn(RtcDataChannelTransport.prototype, 'diagnostics').mockReturnValue({} as never) + vi.spyOn(RtcDataChannelTransport.prototype, 'close').mockResolvedValue() + const transport = createAdaptiveTransport() + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + if (expected === 'reject') { + await expect(connecting).rejects.toThrow(`WebRTC selected unnegotiated transport: ${selected}`) + } else { + await connecting + expect(lastSentPayload(socket, 'transport.selected')).toMatchObject({ transport: expected }) + } + }, + } + }), + async () => { + await cleanupScenario1() + }, + ) + }) + + it('rejects P2P-only negotiation when WebRTC is disabled', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport() + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ capabilities: ['transport.p2p'], webrtcEnabled: false })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { connectionId: 'connection-1' })) + await expect(connecting).rejects.toThrow('No negotiated transport is available') + }) + + it('enforces the negotiated Control limit on incoming frames', async () => { + vi.stubGlobal('WebSocket', FakeWebSocket) + const transport = createAdaptiveTransport() + const connecting = transport.connect() + const socket = FakeWebSocket.latest! + socket.open() + socket.receive(helloAck({ + capabilities: ['transport.relay'], + maxControlFrameBytes: 256, + })) + await Promise.resolve() + socket.receive(createControlFrame('connect.accepted', { + connectionId: 'x'.repeat(300), + })) + + await expect(connecting).rejects.toThrow('Control frame exceeds') + }) +}) + +function createAdaptiveTransport(options: Partial = {}): AdaptiveTransport { + return new AdaptiveTransport('wss://remote.example/ws/v1/connect', { + role: 'client', + deviceId: 'client-1', + accessToken: 'access-token', + targetDeviceId: 'host-1', + rtcFactory: { create: vi.fn(() => ({})) } as unknown as RtcPeerConnectionFactory, + ...options, + }) +} + +function helloAck(overrides: { + capabilities: string[] + webrtcEnabled?: boolean + webrtcFallbackTimeoutMs?: number + maxControlFrameBytes?: number + maxRelayFrameBytes?: number +}): unknown { + return createControlFrame('hello.ack', { + protocol: 1, + serverVersion: '0.1.0', + connectionSessionId: 'control-1', + heartbeatIntervalMs: 25_000, + maxControlFrameBytes: 65_536, + maxRelayFrameBytes: 1_048_576, + ...overrides, + }) +} + +function stalledRtc() { + const channel = { label: 'dsh', ordered: true, readyState: 'connecting', bufferedAmount: 0, + onopen: null as (() => void) | null, close: vi.fn(), send: vi.fn() } + const pc = { + connectionState: 'new', iceConnectionState: 'new', iceGatheringState: 'new', + createDataChannel: () => channel, + createOffer: async () => ({ type: 'offer', sdp: 'v=0 offer' }), + setLocalDescription: async () => {}, + getStats: async () => [ + ['lc', { id: 'lc', type: 'local-candidate', candidateType: 'host' }], + ['rc', { id: 'rc', type: 'remote-candidate', candidateType: 'srflx' }], + ['cp', { type: 'candidate-pair', selected: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }], + ], + close: vi.fn(), + } + return { pc, channel, factory: { create: vi.fn(() => pc) } as unknown as RtcPeerConnectionFactory } +} + +function lastSentPayload(socket: FakeWebSocket, type: string): Record { + const frame = socket.sent + .map(value => JSON.parse(value) as { type?: string; payload?: Record }) + .findLast(value => value.type === type) + if (frame?.payload === undefined) throw new Error(`Missing ${type} frame`) + return frame.payload +}