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 }