diff --git a/packages/webrtc/tests/rtc-data-channel.test.ts b/packages/webrtc/tests/rtc-data-channel.test.ts new file mode 100644 index 0000000..8445ed5 --- /dev/null +++ b/packages/webrtc/tests/rtc-data-channel.test.ts @@ -0,0 +1,634 @@ +import { runScenarios } from '../../../scripts/test-scenarios.mjs' +import { describe, expect, it, vi } from 'vitest' +import type { + RtcDataChannel, + RtcIceCandidateInit, + RtcPeerConnection, + RtcPeerConnectionFactory, + RtcStats, + RtcStatsEntry, +} from '../src/rtc-adapter.js' +import { browserRtcFactory, stunOnlyIceServers } from '../src/rtc-adapter.js' +import { + detectSelectedPath, + detectSelectedTransport, + inspectCandidatePairs, + inspectSelectedPath, + RtcConnectError, + RtcDataChannelTransport, + type RtcDiagnosticEvent, +} from '../src/rtc-data-channel.js' + +const flush = () => new Promise(resolve => setTimeout(resolve, 0)) + +function asStats(entries: RtcStatsEntry[]): RtcStats { + return entries.map((entry, index) => [String(index), entry] as const) +} + +class FakeChannel implements RtcDataChannel { + readonly label = 'dsh' + readonly ordered = true + readyState: RtcDataChannel['readyState'] = 'connecting' + bufferedAmount = 0 + binaryType = '' + onopen: (() => void) | null = null + onmessage: ((event: { data: ArrayBuffer | string }) => void) | null = null + onclose: (() => void) | null = null + onerror: (() => void) | null = null + onbufferedamountlow: (() => void) | null = null + sent: (ArrayBuffer | string)[] = [] + + send(data: ArrayBuffer | string): void { this.sent.push(data) } + close(): void { this.readyState = 'closed'; this.onclose?.() } + open(): void { this.readyState = 'open'; this.onopen?.() } + receive(data: ArrayBuffer | string): void { this.onmessage?.({ data }) } +} + +class FakePeerConnection implements RtcPeerConnection { + connectionState = 'new' + iceConnectionState = 'new' + iceGatheringState = 'new' + signalingState = 'stable' + onconnectionstatechange: (() => void) | null = null + oniceconnectionstatechange: (() => void) | null = null + onicegatheringstatechange: (() => void) | null = null + onicecandidate: ((event: { candidate: RtcIceCandidateInit | null }) => void) | null = null + ondatachannel: ((event: { channel: RtcDataChannel }) => void) | null = null + localDescription: { type: 'offer' | 'answer'; sdp?: string } | undefined + remoteDescription: { type: 'offer' | 'answer'; sdp?: string } | undefined + channels: FakeChannel[] = [] + candidates: RtcIceCandidateInit[] = [] + stats: RtcStatsEntry[] = [] + + createDataChannel(): RtcDataChannel { + const channel = new FakeChannel() + this.channels.push(channel) + return channel + } + async createOffer(): Promise<{ type: 'offer'; sdp?: string }> { return { type: 'offer', sdp: 'v=0 offer' } } + async createAnswer(): Promise<{ type: 'answer'; sdp?: string }> { return { type: 'answer', sdp: 'v=0 answer' } } + async setLocalDescription(description: { type: 'offer' | 'answer'; sdp?: string }): Promise { this.localDescription = description } + async setRemoteDescription(description: { type: 'offer' | 'answer'; sdp?: string }): Promise { this.remoteDescription = description } + async addIceCandidate(candidate: RtcIceCandidateInit): Promise { this.candidates.push(candidate) } + async getStats(): Promise> { + return this.stats.map((entry, index) => [String(index), entry] as const) + } + close(): void { this.connectionState = 'closed' } + emitIceCandidate(candidate: RtcIceCandidateInit | null): void { this.onicecandidate?.({ candidate }) } + emitDataChannel(channel: RtcDataChannel): void { this.ondatachannel?.({ channel }) } +} + +function factoryFor(pc: FakePeerConnection): RtcPeerConnectionFactory { + return { create: () => pc } +} + +function p2pStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'host', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'srflx', id: 'rc' }, + { type: 'candidate-pair', selected: true, nominated: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +function lanStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'host', address: '192.168.1.20', port: 51_001, protocol: 'udp', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'host', address: '192.168.1.30', port: 51_002, protocol: 'udp', id: 'rc' }, + { + type: 'candidate-pair', id: 'cp', state: 'succeeded', localCandidateId: 'lc', remoteCandidateId: 'rc', + currentRoundTripTime: 0.0124, availableOutgoingBitrate: 8_500_000, bytesSent: 2_048, bytesReceived: 4_096, + }, + { type: 'transport', selectedCandidatePairId: 'cp' }, + ] +} + +function privatePeerReflexiveLanStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'host', address: '192.168.31.225', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'prflx', address: '192.168.31.9', id: 'rc' }, + { type: 'candidate-pair', selected: true, nominated: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +function publicPeerReflexiveP2pStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'host', address: '192.168.31.225', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'prflx', address: '203.0.113.9', id: 'rc' }, + { type: 'candidate-pair', selected: true, nominated: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +function hiddenPeerReflexiveLanStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'host', address: '192.168.31.225', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'prflx', id: 'rc' }, + { type: 'candidate-pair', selected: true, nominated: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +function tailscaleP2pStats(localType: 'host' | 'prflx' = 'prflx'): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: localType, id: 'lc' }, + { type: 'remote-candidate', candidateType: 'host', address: 'fd7a:115c:a1e0::c', id: 'rc' }, + { type: 'candidate-pair', selected: true, nominated: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +function turnStats(): RtcStatsEntry[] { + return [ + { type: 'local-candidate', candidateType: 'relay', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'host', id: 'rc' }, + { type: 'candidate-pair', selected: true, localCandidateId: 'lc', remoteCandidateId: 'rc' }, + ] +} + +describe('detectSelectedTransport', () => { + it('classifies selected candidate pairs as LAN, P2P or TURN', async () => { + await runScenarios([ + { + name: 'classifies a selected private host-to-host pair as LAN on the wire', + run: () => { + expect(detectSelectedPath(asStats(lanStats()))).toEqual({ transport: 'lan', mode: 'LAN' }) + expect(detectSelectedTransport(asStats(lanStats()))).toBe('lan') + expect(inspectSelectedPath(asStats(lanStats()))).toMatchObject({ + localCandidateType: 'host', + remoteCandidateType: 'host', + localAddress: '192.168.1.20:51001', + remoteAddress: '192.168.1.30:51002', + protocol: 'udp', + currentRoundTripTimeMs: 12, + availableOutgoingBitrate: 8_500_000, + bytesSent: 2_048, + bytesReceived: 4_096, + }) + expect(inspectCandidatePairs(asStats(lanStats()))).toMatchObject({ + total: 1, + byState: { succeeded: 1 }, + byLocalType: { host: 1 }, + byRemoteType: { host: 1 }, + byLocalScope: { private: 1 }, + byRemoteScope: { private: 1 }, + }) + }, + }, + { + name: 'classifies a private host-to-peer-reflexive pair as LAN', + run: () => { + expect(detectSelectedPath(asStats(privatePeerReflexiveLanStats()))).toEqual({ + transport: 'lan', + mode: 'LAN', + }) + expect(inspectSelectedPath(asStats(privatePeerReflexiveLanStats()))).toMatchObject({ + localCandidateType: 'host', + remoteCandidateType: 'prflx', + localAddressScope: 'private', + remoteAddressScope: 'private', + }) + }, + }, + { + name: 'keeps a public peer-reflexive pair classified as P2P', + run: () => { + expect(detectSelectedPath(asStats(publicPeerReflexiveP2pStats()))).toEqual({ + transport: 'p2p', + mode: 'P2P', + }) + }, + }, + { + name: 'classifies an address-hidden peer-reflexive candidate beside a private host as LAN', + run: () => { + expect(detectSelectedPath(asStats(hiddenPeerReflexiveLanStats()))).toEqual({ + transport: 'lan', + mode: 'LAN', + }) + }, + }, + { + name: 'classifies a loopback host beside an address-hidden prflx candidate as LAN', + run: () => { + expect( + detectSelectedPath( + asStats([ + { type: 'local-candidate', candidateType: 'prflx', id: 'lc' }, + { type: 'remote-candidate', candidateType: 'host', address: '127.0.0.1', id: 'rc' }, + { + type: 'candidate-pair', + selected: true, + nominated: true, + localCandidateId: 'lc', + remoteCandidateId: 'rc', + }, + ]), + ), + ).toEqual({ transport: 'lan', mode: 'LAN' }) + }, + }, + { + name: 'classifies a Tailscale IPv6 overlay pair as P2P', + run: () => { + expect(detectSelectedPath(asStats(tailscaleP2pStats()))).toEqual({ transport: 'p2p', mode: 'P2P' }) + expect(inspectSelectedPath(asStats(tailscaleP2pStats()))).toMatchObject({ + localCandidateType: 'prflx', + remoteCandidateType: 'host', + remoteAddressScope: 'cgnat', + }) + }, + }, + { + name: 'does not treat host-to-host Tailscale overlay candidates as LAN', + run: () => { + expect(detectSelectedPath(asStats(tailscaleP2pStats('host')))).toEqual({ + transport: 'p2p', + mode: 'P2P', + }) + }, + }, + { + name: 'detects p2p from a selected host/srflx candidate pair', + run: () => { + expect(detectSelectedTransport(asStats(p2pStats()))).toBe('p2p') + }, + }, + { + name: 'detects turn when any selected candidate is a relay candidate', + run: () => { + expect(detectSelectedTransport(asStats(turnStats()))).toBe('turn') + }, + }, + { + name: 'returns undefined when no selected pair exists', + run: () => { + expect( + detectSelectedTransport(asStats([{ type: 'local-candidate', candidateType: 'host', id: 'lc' }])), + ).toBeUndefined() + }, + }, + ]) + }, 50000) + +}) + +describe('stunOnlyIceServers', () => { + it('keeps direct STUN URLs and strips TURN URLs and credentials', () => { + expect(stunOnlyIceServers([ + { + urls: [ + 'stun:turn.example.com:3478', + 'turn:turn.example.com:3478?transport=udp', + 'turns:turn.example.com:5349?transport=tcp', + ], + username: 'turn-user', + credential: 'turn-secret', + }, + { urls: 'stuns:stun.example.com:5349' }, + { urls: 'turn:relay.example.com:3478?transport=tcp', username: 'relay', credential: 'secret' }, + ])).toEqual([ + { urls: ['stun:turn.example.com:3478'] }, + { urls: 'stuns:stun.example.com:5349' }, + ]) + }) +}) + +describe('RtcDataChannelTransport initiator', () => { + it('reports LAN for a private host-to-host data path', async () => { + const pc = new FakePeerConnection() + pc.stats = lanStats() + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + }) + const connecting = transport.connect() + await flush() + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await flush() + pc.channels[0]!.open() + await connecting + expect(transport.selectedTransport()).toBe('lan') + expect(transport.selectedPathMode()).toBe('LAN') + expect(transport.getStats().mode).toBe('LAN') + await expect(transport.connectionDetails()).resolves.toMatchObject({ + mode: 'LAN', + connectionState: 'new', + iceConnectionState: 'new', + dataChannelState: 'open', + localAddress: '192.168.1.20:51001', + remoteAddress: '192.168.1.30:51002', + currentRoundTripTimeMs: 12, + }) + await transport.close() + }) + + it('waits for native stats to expose the selected LAN candidate pair', async () => { + const pc = new FakePeerConnection() + const getStats = vi.spyOn(pc, 'getStats') + .mockResolvedValueOnce(asStats([])) + .mockResolvedValue(asStats(lanStats())) + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + }) + const connecting = transport.connect() + await flush() + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await flush() + pc.channels[0]!.open() + await connecting + + expect(getStats).toHaveBeenCalledTimes(2) + expect(transport.selectedPathMode()).toBe('LAN') + expect(transport.getStats()).toMatchObject({ mode: 'LAN', connected: true }) + await transport.close() + }) + + it('creates an offer and resolves with p2p once the data channel opens', async () => { + const pc = new FakePeerConnection() + pc.stats = p2pStats() + const signals: unknown[] = [] + const diagnostics: RtcDiagnosticEvent[] = [] + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: signal => signals.push(signal), + onDiagnostic: event => diagnostics.push(event), + }) + let connected = false + const connecting = transport.connect().then(() => { connected = true }) + await flush() + + expect(pc.channels).toHaveLength(1) + expect(pc.localDescription?.type).toBe('offer') + expect(signals).toEqual([{ type: 'offer', sdp: 'v=0 offer' }]) + + const hostCandidate = { candidate: 'candidate:1 1 udp 2130706431 192.168.1.20 5000 typ host generation 0' } + pc.emitIceCandidate(hostCandidate) + expect(signals.at(-1)).toEqual({ type: 'ice', candidate: hostCandidate }) + expect(diagnostics).toContainEqual(expect.objectContaining({ + type: 'local-candidate', + candidate: expect.objectContaining({ + candidateType: 'host', + protocol: 'udp', + addressFamily: 'ipv4', + addressScope: 'private', + }), + })) + + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await flush() + expect(pc.remoteDescription?.type).toBe('answer') + + pc.channels[0]!.open() + await connecting + expect(connected).toBe(true) + expect(transport.selectedTransport()).toBe('p2p') + expect(transport.getStats()).toMatchObject({ mode: 'P2P', connected: true }) + expect(transport.diagnostics()).toMatchObject({ + localCandidates: { total: 1, byType: { host: 1 }, byFamily: { ipv4: 1 }, byScope: { private: 1 } }, + candidatePairs: { total: 1, selected: 1, byState: { selected: 1 } }, + selectedPath: { transport: 'p2p', mode: 'P2P' }, + }) + + await transport.send(new Uint8Array([1, 2, 3])) + expect(pc.channels[0]!.sent).toHaveLength(1) + await transport.close() + }) + + it('keeps an active or unmonitored send queue connected', async () => { + await runScenarios([ + { + name: 'does not treat continued sends as a stalled DataChannel queue', + run: async () => { + vi.useFakeTimers() + try { + const pc = new FakePeerConnection() + pc.stats = lanStats() + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + sendTimeoutMs: 5_000, + }) + const connecting = transport.connect() + await vi.advanceTimersByTimeAsync(0) + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await vi.advanceTimersByTimeAsync(0) + const channel = pc.channels[0]! + channel.open() + await connecting + + channel.bufferedAmount = 10 + await transport.send(new Uint8Array([1])) + await vi.advanceTimersByTimeAsync(4_000) + + // Loading a conversation sends more requests while earlier writes are + // still draining. The newer send must refresh the watchdog baseline; + // it is evidence of active traffic, not evidence that the first write + // has been stuck for five seconds. + channel.bufferedAmount = 20 + await transport.send(new Uint8Array([2])) + await vi.advanceTimersByTimeAsync(1_100) + expect(transport.getStats()).toMatchObject({ mode: 'LAN', connected: true }) + + channel.bufferedAmount = 0 + await vi.advanceTimersByTimeAsync(4_000) + expect(transport.getStats()).toMatchObject({ mode: 'LAN', connected: true }) + await transport.close() + } finally { + vi.useRealTimers() + } + }, + }, + { + name: 'does not infer a dead connection from bufferedAmount by default', + run: async () => { + vi.useFakeTimers() + try { + const pc = new FakePeerConnection() + pc.stats = lanStats() + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + }) + const connecting = transport.connect() + await vi.advanceTimersByTimeAsync(0) + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await vi.advanceTimersByTimeAsync(0) + const channel = pc.channels[0]! + channel.open() + await connecting + + // React Native may retain a positive bufferedAmount even after SCTP has + // delivered the frame. It is not an acknowledgement or liveness signal. + channel.bufferedAmount = 64 * 1024 + await transport.send(new Uint8Array([1, 2, 3])) + await vi.advanceTimersByTimeAsync(60_000) + expect(transport.getStats()).toMatchObject({ mode: 'LAN', connected: true }) + await transport.close() + } finally { + vi.useRealTimers() + } + }, + }, + ]) + }, 10000) + + it('detects turn from the selected candidate pair', async () => { + const pc = new FakePeerConnection() + pc.stats = turnStats() + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + }) + const connecting = transport.connect() + await flush() + transport.handleSignal({ type: 'answer', sdp: 'v=0 answer' }) + await flush() + pc.channels[0]!.open() + await connecting + expect(transport.selectedTransport()).toBe('turn') + expect(transport.getStats().mode).toBe('TURN') + await transport.close() + }) + + it('rejects on negotiation timeout', async () => { + vi.useFakeTimers() + try { + const pc = new FakePeerConnection() + const transport = new RtcDataChannelTransport({ + role: 'initiator', + factory: factoryFor(pc), + onSignal: () => undefined, + negotiateTimeoutMs: 1000, + }) + let caught: Error | undefined + const connecting = transport.connect().catch((error: Error) => { caught = error }) + await vi.advanceTimersByTimeAsync(1100) + await connecting + expect(caught).toMatchObject({ code: 'RTC_CONNECT_TIMEOUT' }) + expect(transport.getStats().connected).toBe(false) + } finally { + vi.useRealTimers() + } + }) +}) + +describe('RtcDataChannelTransport responder', () => { + it('answers an offer and resolves when the remote data channel opens', async () => { + const pc = new FakePeerConnection() + pc.stats = p2pStats() + const signals: unknown[] = [] + const transport = new RtcDataChannelTransport({ + role: 'responder', + factory: factoryFor(pc), + onSignal: signal => signals.push(signal), + }) + let connected = false + const connecting = transport.connect().then(() => { connected = true }) + + transport.handleSignal({ type: 'offer', sdp: 'v=0 offer' }) + await flush() + expect(pc.remoteDescription?.type).toBe('offer') + expect(signals).toEqual([{ type: 'answer', sdp: 'v=0 answer' }]) + + const channel = new FakeChannel() + pc.emitDataChannel(channel) + channel.open() + await connecting + expect(connected).toBe(true) + + const received: Uint8Array[] = [] + transport.onMessage(data => received.push(data)) + channel.receive(new Uint8Array([9, 8, 7]).buffer) + expect(received).toHaveLength(1) + await transport.close() + }) + + it('buffers trickle ICE until the offer is processed', async () => { + const pc = new FakePeerConnection() + const diagnostics: RtcDiagnosticEvent[] = [] + const transport = new RtcDataChannelTransport({ + role: 'responder', + factory: factoryFor(pc), + onSignal: () => undefined, + onDiagnostic: event => diagnostics.push(event), + }) + const connecting = expect(transport.connect()).rejects.toThrow('closed') + const early: RtcIceCandidateInit = { + candidate: 'candidate:1 1 udp 1694498815 203.0.113.8 5002 typ srflx raddr 192.168.1.20 rport 5000', + sdpMid: '0', + sdpMLineIndex: 0, + } + transport.handleSignal({ type: 'ice', candidate: early }) + await flush() + expect(pc.candidates).toHaveLength(0) // buffered, remote description not set yet + expect(diagnostics).toContainEqual(expect.objectContaining({ + type: 'remote-candidate', + action: 'buffered', + candidate: expect.objectContaining({ + candidateType: 'srflx', + addressFamily: 'ipv4', + addressScope: 'public', + relatedAddressScope: 'private', + }), + })) + + transport.handleSignal({ type: 'offer', sdp: 'v=0 offer' }) + await flush() + expect(pc.candidates).toHaveLength(1) + expect(transport.diagnostics().remoteCandidates).toMatchObject({ + total: 1, + byType: { srflx: 1 }, + byScope: { public: 1 }, + }) + await transport.close() + await connecting + }) + + it('is an idempotent close', async () => { + const pc = new FakePeerConnection() + const transport = new RtcDataChannelTransport({ + role: 'responder', + factory: factoryFor(pc), + onSignal: () => undefined, + }) + await transport.close() + await transport.close() + expect(transport.getStats().connected).toBe(false) + }) +}) + +describe('RtcConnectError', () => { + it('carries a stable code', () => { + expect(new RtcConnectError('RTC_CONNECT_TIMEOUT', 'x').code).toBe('RTC_CONNECT_TIMEOUT') + }) +}) + + +describe('browser/native RTC policy', () => { + it('passes relay-only ICE to the native peer connection', () => { + let configuration: unknown + class NativePeerConnection { + constructor(value: unknown) { configuration = value } + } + vi.stubGlobal('RTCPeerConnection', NativePeerConnection) + try { + new RtcDataChannelTransport({ + role: 'initiator', + factory: browserRtcFactory(), + iceTransportPolicy: 'relay', + iceServers: [{ urls: 'turn:turn.example.test' }], + onSignal: () => {}, + }) + expect(configuration).toEqual({ + iceTransportPolicy: 'relay', + iceServers: [{ urls: 'turn:turn.example.test' }], + }) + } finally { + vi.unstubAllGlobals() + } + }) +})