From 1c8b7901e9ccf4a410514c70580b59ce73d56d1f Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 15:04:22 +0800 Subject: [PATCH] Import packages/protocol/tests/control-frame.test.ts --- packages/protocol/tests/control-frame.test.ts | 703 ++++++++++++++++++ 1 file changed, 703 insertions(+) create mode 100644 packages/protocol/tests/control-frame.test.ts diff --git a/packages/protocol/tests/control-frame.test.ts b/packages/protocol/tests/control-frame.test.ts new file mode 100644 index 0000000..f711e94 --- /dev/null +++ b/packages/protocol/tests/control-frame.test.ts @@ -0,0 +1,703 @@ +import { runScenarios } from '../../../scripts/test-scenarios.mjs' +import { describe, expect, it } from 'vitest' +import { + type HelloPayload, + type HelloAckPayload, + type ConnectIncomingPayload, + type RelayPayload, + type SignalPayload, + type SignalIcePayload, + type TransportSelectedPayload, + type ControlErrorPayload, + PROTOCOL_VERSION, + controlFrameTypes, + createControlFrame, + parseControlFrame, +} from '../src/index.js' + +// Shared conformance fixtures cover the baseline envelopes, hello/connect/relay +// payloads and errors. Keep only additional boundaries and factory checks here. + +// ──────────────────────────────────────────────────────────────────────────── +// Helpers +// ──────────────────────────────────────────────────────────────────────────── + +function makeFrame(type: string, payload: unknown, v = PROTOCOL_VERSION): unknown { + return { + v, + id: `frame-${Date.now()}`, + type, + timestamp: Date.now(), + payload, + } +} + +// Valid payloads for each frame type (used in negative tests) +const validPayloads: Record = { + 'hello': { role: 'client', deviceId: 'dev-1', accessToken: 'token-1', protocols: [1], capabilities: [] }, + 'hello.ack': { protocol: 1, serverVersion: '1.0.0', connectionSessionId: 'sess-1', heartbeatIntervalMs: 25000, maxControlFrameBytes: 65536, maxRelayFrameBytes: 1048576 }, + 'connect.request': { hostDeviceId: 'host-1', preferredTransports: ['relay'] }, + 'connect.incoming': { connectionId: 'conn-1', clientDeviceId: 'client-1', clientIdentityKey: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA', authorization: 'account', preferredTransports: ['relay'] }, + 'connect.accepted': { connectionId: 'conn-1' }, + 'connect.rejected': { connectionId: 'conn-1' }, + 'secure.handshake': { connectionId: 'conn-1', targetDeviceId: 'host-1', step: 1, data: 'AQIDBA' }, + 'relay': { connectionId: 'conn-1', targetDeviceId: 'host-1', counter: 0, ciphertext: 'AQIDBA' }, + 'signal.offer': { connectionId: 'conn-1', targetDeviceId: 'host-1', sdp: 'v=0...' }, + 'signal.answer': { connectionId: 'conn-1', targetDeviceId: 'host-1', sdp: 'v=0...' }, + 'signal.ice': { connectionId: 'conn-1', targetDeviceId: 'host-1', candidate: { candidate: 'candidate:1' } }, + 'transport.selected': { connectionId: 'conn-1', targetDeviceId: 'host-1', transport: 'relay' }, + 'connection.lease.request': { connectionId: 'conn-1', requestId: 'request-1', ticket: 'signed-ticket' }, + 'connection.lease.ack': { connectionId: 'conn-1', requestId: 'request-1', ticket: 'signed-ticket', leaseMs: 300000 }, + 'connection.lease.close': { connectionId: 'conn-1' }, + 'ping': { nonce: 'nonce-1' }, + 'pong': { nonce: 'nonce-1' }, + 'error': { code: 'ERROR', message: 'Something failed' }, +} + +// ──────────────────────────────────────────────────────────────────────────── +// §10.2 Control frame envelope +// ──────────────────────────────────────────────────────────────────────────── + +describe('control frame envelope', () => { + it('rejects invalid control frame envelope fields', async () => { + await runScenarios([ + { + name: 'rejects v !== 1', + run: () => { + expect(() => parseControlFrame(makeFrame('ping', { nonce: 'test' }, 0))).toThrow() + expect(() => parseControlFrame(makeFrame('ping', { nonce: 'test' }, 2))).toThrow() + }, + }, + { + name: 'rejects empty id', + run: () => { + const frame = { v: 1, id: '', type: 'ping', timestamp: Date.now(), payload: { nonce: 'test' } } + expect(() => parseControlFrame(frame)).toThrow() + }, + }, + { + name: 'rejects non-positive timestamp', + run: () => { + const frame = { v: 1, id: 'x', type: 'ping', timestamp: 0, payload: { nonce: 'test' } } + expect(() => parseControlFrame(frame)).toThrow() + }, + }, + ]) + }, 15000) + + it('round-trips through createControlFrame', () => { + const original = createControlFrame('ping', { nonce: 'abc' }) + const reparsed = parseControlFrame(original) + expect(reparsed).toEqual(original) + }) + + it('accepts all defined control frame types with valid payloads', () => { + for (const type of controlFrameTypes) { + const frame = makeFrame(type, validPayloads[type]) + expect(parseControlFrame(frame)).toMatchObject({ type }) + } + }) +}) + +// ──────────────────────────────────────────────────────────────────────────── +// Payload schema validation - positive tests +// ──────────────────────────────────────────────────────────────────────────── + +describe('hello payload validation', () => { + const valid: HelloPayload = { + role: 'client', + deviceId: 'dev-1', + accessToken: 'token-1', + protocols: [1], + capabilities: ['transport.relay'], + } + + it('accepts additive hello metadata within version bounds', async () => { + await runScenarios([ + { + name: 'accepts Host hello with harnessVersion', + run: () => { + const frame = parseControlFrame( + makeFrame('hello', { + ...valid, + role: 'host', + harnessVersion: '0.1.0-rc.8', + }), + ) + expect(frame.payload).toMatchObject({ harnessVersion: '0.1.0-rc.8' }) + }, + }, + { + name: 'accepts protocol versions at both safe integer boundaries', + run: () => { + expect(parseControlFrame(makeFrame('hello', { ...valid, protocols: [0] }))).toBeDefined() + expect( + parseControlFrame( + makeFrame('hello', { + ...valid, + protocols: [Number.MAX_SAFE_INTEGER], + }), + ), + ).toBeDefined() + }, + }, + { + name: 'accepts unknown capabilities for additive negotiation', + run: () => { + expect( + parseControlFrame( + makeFrame('hello', { + ...valid, + capabilities: ['transport.relay', 'example.future.v1'], + }), + ), + ).toBeDefined() + }, + }, + { + name: 'returns parsed payload with stripped unknown fields', + run: () => { + const withExtra = { ...valid, unknownField: 'should-be-stripped' } + const result = parseControlFrame(makeFrame('hello', withExtra)) + expect(result.payload).not.toHaveProperty('unknownField') + }, + }, + ]) + }, 20000) + +}) + +describe('hello.ack payload validation', () => { + const valid: HelloAckPayload = { + protocol: 1, + serverVersion: '1.0.0', + connectionSessionId: 'sess-1', + heartbeatIntervalMs: 25000, + maxControlFrameBytes: 65536, + maxRelayFrameBytes: 1048576, + } + + it('accepts hello.ack with optional webrtc fields', () => { + const withWebrtc = { + ...valid, + capabilities: ['transport.relay', 'transport.p2p'], + webrtcEnabled: true, + webrtcFallbackTimeoutMs: 5000, + } + expect(parseControlFrame(makeFrame('hello.ack', withWebrtc))).toBeDefined() + }) + + it('rejects empty and duplicate negotiated capabilities', () => { + expect(() => parseControlFrame(makeFrame('hello.ack', { ...valid, capabilities: [''] }))).toThrow() + expect(() => parseControlFrame(makeFrame('hello.ack', { + ...valid, + capabilities: ['transport.relay', 'transport.relay'], + }))).toThrow() + }) +}) + +describe('signal.ice payload validation', () => { + const valid: SignalIcePayload = { + connectionId: 'conn-1', + targetDeviceId: 'host-1', + candidate: { + candidate: 'candidate:1 1 UDP 2122252543 192.168.1.100 50000 typ host', + sdpMid: '0', + sdpMLineIndex: 0, + }, + } + + it('normalizes valid ICE candidate variants', async () => { + await runScenarios([ + { + name: 'accepts valid signal.ice', + run: () => { + expect(parseControlFrame(makeFrame('signal.ice', valid))).toBeDefined() + }, + }, + { + name: 'accepts candidate with null sdpMid', + run: () => { + const withNull = { ...valid, candidate: { ...valid.candidate, sdpMid: null } } + expect(parseControlFrame(makeFrame('signal.ice', withNull))).toBeDefined() + }, + }, + { + name: 'normalizes invalid native sdpMLineIndex values to null', + run: () => { + const parsed = parseControlFrame( + makeFrame('signal.ice', { + ...valid, + candidate: { ...valid.candidate, sdpMLineIndex: 1.167066568144e-312 }, + }), + ) + expect(parsed.payload.candidate.sdpMLineIndex).toBeNull() + }, + }, + ]) + }, 15000) + +}) + +// ──────────────────────────────────────────────────────────────────────────── +// Payload schema validation - NEGATIVE tests +// ──────────────────────────────────────────────────────────────────────────── + +describe('hello payload rejection', () => { + it('rejects invalid hello identity and negotiation fields', async () => { + await runScenarios([ + { + name: 'rejects invalid role', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + role: 'admin', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects missing role', + run: () => { + const { role, ...noRole } = validPayloads['hello'] as HelloPayload + expect(() => parseControlFrame(makeFrame('hello', noRole))).toThrow() + }, + }, + { + name: 'rejects empty deviceId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + deviceId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects missing accessToken', + run: () => { + const { accessToken, ...noToken } = validPayloads['hello'] as HelloPayload + expect(() => parseControlFrame(makeFrame('hello', noToken))).toThrow() + }, + }, + { + name: 'rejects empty protocols', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + protocols: [], + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects protocol versions outside the safe integer range', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + protocols: [-1], + }), + ), + ).toThrow() + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + protocols: [Number.MAX_SAFE_INTEGER + 1], + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty and duplicate capabilities', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + capabilities: [''], + }), + ), + ).toThrow() + expect(() => + parseControlFrame( + makeFrame('hello', { + ...(validPayloads['hello'] as HelloPayload), + capabilities: ['transport.relay', 'transport.relay'], + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects missing protocols', + run: () => { + const { protocols, ...noProtocols } = validPayloads['hello'] as HelloPayload + expect(() => parseControlFrame(makeFrame('hello', noProtocols))).toThrow() + }, + }, + ]) + }, 40000) + +}) + +describe('hello.ack payload rejection', () => { + it('rejects invalid hello acknowledgement limits', async () => { + await runScenarios([ + { + name: 'rejects empty serverVersion', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello.ack', { + ...(validPayloads['hello.ack'] as HelloAckPayload), + serverVersion: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects zero heartbeatIntervalMs', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello.ack', { + ...(validPayloads['hello.ack'] as HelloAckPayload), + heartbeatIntervalMs: 0, + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects negative maxControlFrameBytes', + run: () => { + expect(() => + parseControlFrame( + makeFrame('hello.ack', { + ...(validPayloads['hello.ack'] as HelloAckPayload), + maxControlFrameBytes: -1, + }), + ), + ).toThrow() + }, + }, + ]) + }, 15000) + +}) + +describe('connect.incoming payload rejection', () => { + const valid = validPayloads['connect.incoming'] as ConnectIncomingPayload + + it('rejects invalid incoming connection authorization and routing', async () => { + await runScenarios([ + { + name: 'rejects empty authorization', + run: () => { + expect(() => + parseControlFrame( + makeFrame('connect.incoming', { + ...valid, + authorization: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects missing authorization', + run: () => { + const { authorization, ...noAuth } = valid + expect(() => parseControlFrame(makeFrame('connect.incoming', noAuth))).toThrow() + }, + }, + { + name: 'rejects empty connectionId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('connect.incoming', { + ...valid, + connectionId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty clientDeviceId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('connect.incoming', { + ...valid, + clientDeviceId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty preferredTransports', + run: () => { + expect(() => + parseControlFrame( + makeFrame('connect.incoming', { + ...valid, + preferredTransports: [], + }), + ), + ).toThrow() + }, + }, + ]) + }, 25000) + +}) + +describe('relay payload rejection', () => { + const valid = validPayloads['relay'] as RelayPayload + + it('rejects empty connectionId', () => { + expect(() => parseControlFrame(makeFrame('relay', { + ...valid, + connectionId: '', + }))).toThrow() + }) +}) + +describe('signal payload rejection', () => { + const valid = validPayloads['signal.offer'] as SignalPayload + + it('rejects invalid SDP signal routing and content', async () => { + await runScenarios([ + { + name: 'rejects empty connectionId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('signal.offer', { + ...valid, + connectionId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty targetDeviceId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('signal.offer', { + ...valid, + targetDeviceId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty sdp', + run: () => { + expect(() => + parseControlFrame( + makeFrame('signal.offer', { + ...valid, + sdp: '', + }), + ), + ).toThrow() + }, + }, + ]) + }, 15000) + +}) + +describe('transport.selected payload rejection', () => { + const valid = validPayloads['transport.selected'] as TransportSelectedPayload + + it('accepts LAN as a selected wire transport', () => { + expect(parseControlFrame(makeFrame('transport.selected', { + ...valid, + transport: 'lan', + })).payload).toMatchObject({ transport: 'lan' }) + }) + + it('preserves the optional TURN node diagnostic', () => { + expect(parseControlFrame(makeFrame('transport.selected', { + ...valid, + transport: 'turn', + turnNode: 'turn.example.com:3478', + })).payload).toMatchObject({ transport: 'turn', turnNode: 'turn.example.com:3478' }) + expect(parseControlFrame(makeFrame('transport.selected', { ...valid })).payload) + .not.toHaveProperty('turnNode') + }) + + it('rejects invalid selected transport payloads', async () => { + await runScenarios([ + { + name: 'rejects empty connectionId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('transport.selected', { + ...valid, + connectionId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects empty targetDeviceId', + run: () => { + expect(() => + parseControlFrame( + makeFrame('transport.selected', { + ...valid, + targetDeviceId: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects invalid transport', + run: () => { + expect(() => + parseControlFrame( + makeFrame('transport.selected', { + ...valid, + transport: 'direct', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects missing transport', + run: () => { + const { transport, ...noTransport } = valid + expect(() => parseControlFrame(makeFrame('transport.selected', noTransport))).toThrow() + }, + }, + { + name: 'rejects empty turnNode', + run: () => { + expect(() => + parseControlFrame( + makeFrame('transport.selected', { + ...valid, + transport: 'turn', + turnNode: '', + }), + ), + ).toThrow() + }, + }, + { + name: 'rejects oversized turnNode', + run: () => { + expect(() => + parseControlFrame( + makeFrame('transport.selected', { + ...valid, + transport: 'turn', + turnNode: 'a'.repeat(254), + }), + ), + ).toThrow() + }, + }, + ]) + }, 20000) + +}) + +describe('ping/pong payload rejection', () => { + it('requires nonempty ping and pong nonces', async () => { + await runScenarios([ + { + name: 'rejects empty nonce in ping', + run: () => { + expect(() => parseControlFrame(makeFrame('ping', { nonce: '' }))).toThrow() + }, + }, + { + name: 'rejects missing nonce in ping', + run: () => { + expect(() => parseControlFrame(makeFrame('ping', {}))).toThrow() + }, + }, + { + name: 'rejects empty nonce in pong', + run: () => { + expect(() => parseControlFrame(makeFrame('pong', { nonce: '' }))).toThrow() + }, + }, + { + name: 'rejects missing nonce in pong', + run: () => { + expect(() => parseControlFrame(makeFrame('pong', {}))).toThrow() + }, + }, + ]) + }, 20000) + +}) + +describe('error payload rejection', () => { + const valid = validPayloads['error'] as ControlErrorPayload + + it('requires error codes and messages', async () => { + await runScenarios([ + { + name: 'rejects missing code', + run: () => { + const { code, ...noCode } = valid + expect(() => parseControlFrame(makeFrame('error', noCode))).toThrow() + }, + }, + { + name: 'rejects missing message', + run: () => { + const { message, ...noMessage } = valid + expect(() => parseControlFrame(makeFrame('error', noMessage))).toThrow() + }, + }, + ]) + }, 10000) + +}) + +// ──────────────────────────────────────────────────────────────────────────── +// Golden vectors - complete type enumeration +// ──────────────────────────────────────────────────────────────────────────── + +describe('golden vectors', () => { + it('control frame types are complete and ordered', () => { + const expected = [ + 'hello', 'hello.ack', 'connect.request', 'connect.incoming', + 'connect.accepted', 'connect.rejected', 'secure.handshake', + 'relay', 'signal.offer', 'signal.answer', 'signal.ice', + 'transport.selected', 'connection.lease.request', 'connection.lease.ack', 'connection.lease.close', 'ping', 'pong', 'error', + ] + expect([...expected].sort()).toEqual([...Array.from(controlFrameTypes)].sort()) + }) +})