@comprehend/telemetry-node 0.1.3 → 0.2.0

package/src/WebSocketConnection.test.ts

@@ -0,0 +1,616 @@
+import { WebSocketConnection } from './WebSocketConnection';
+import {
+    InitMessage,
+    NewObservedServiceMessage,
+    NewObservedHttpRouteMessage,
+    ObservationMessage,
+    HttpServerObservation,
+    ObservationOutputMessage,
+    TimeSeriesMetricsMessage,
+    CumulativeMetricsMessage,
+    TraceSpansMessage,
+    DatabaseQueryMessage,
+    InitAck,
+    CustomMetricSpecification,
+} from './wire-protocol';
+
+// Mock the ws WebSocket library
+jest.mock('ws');
+
+// Mock crypto.randomUUID
+jest.mock('crypto', () => ({
+    randomUUID: jest.fn().mockReturnValue('test-uuid-1234'),
+}));
+
+import WebSocket from 'ws';
+
+const MockedWebSocket = WebSocket as jest.MockedClass<typeof WebSocket>;
+
+// Mock WebSocket instance
+interface MockWebSocketInstance {
+    on: jest.Mock;
+    send: jest.Mock;
+    close: jest.Mock;
+    readyState: number;
+    OPEN: number;
+    CLOSED: number;
+    _triggerOpen: () => void;
+    _triggerMessage: (data: string) => void;
+    _triggerClose: (code: number, reason: string) => void;
+    _triggerError: (error: Error) => void;
+}
+
+function authAck(customMetrics: CustomMetricSpecification[] = []): string {
+    return JSON.stringify({ type: 'ack-authorized', customMetrics } as InitAck);
+}
+
+describe('WebSocketConnection', () => {
+    let mockSocket: MockWebSocketInstance;
+    let connection: WebSocketConnection;
+    let logMessages: string[];
+    let mockLogger: jest.Mock;
+
+    beforeEach(() => {
+        jest.clearAllMocks();
+        jest.clearAllTimers();
+        jest.useFakeTimers();
+
+        logMessages = [];
+        mockLogger = jest.fn((message: string) => {
+            logMessages.push(message);
+        });
+
+        mockSocket = {
+            on: jest.fn(),
+            send: jest.fn(),
+            close: jest.fn(),
+            readyState: WebSocket.CLOSED,
+            OPEN: WebSocket.OPEN,
+            CLOSED: WebSocket.CLOSED,
+            _triggerOpen: function() {},
+            _triggerMessage: function(data: string) {},
+            _triggerClose: function(code: number, reason: string) {},
+            _triggerError: function(error: Error) {}
+        };
+
+        const eventHandlers: Record<string, Function> = {};
+        mockSocket.on.mockImplementation((event: string, handler: Function) => {
+            eventHandlers[event] = handler;
+        });
+
+        mockSocket._triggerOpen = () => {
+            mockSocket.readyState = WebSocket.OPEN;
+            eventHandlers['open']?.();
+        };
+        mockSocket._triggerMessage = (data: string) => {
+            const buffer = Buffer.from(data);
+            eventHandlers['message']?.(buffer);
+        };
+        mockSocket._triggerClose = (code: number, reason: string) => {
+            mockSocket.readyState = WebSocket.CLOSED;
+            eventHandlers['close']?.(code, Buffer.from(reason));
+        };
+        mockSocket._triggerError = (error: Error) => {
+            eventHandlers['error']?.(error);
+        };
+
+        MockedWebSocket.mockImplementation(() => mockSocket as any);
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+        if (connection) {
+            connection.close();
+        }
+    });
+
+    describe('Connection Establishment', () => {
+        it('should create WebSocket connection with correct URL', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+
+            expect(MockedWebSocket).toHaveBeenCalledWith('wss://ingestion.comprehend.dev/test-org/observations');
+            expect(mockSocket.on).toHaveBeenCalledWith('open', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('message', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('close', expect.any(Function));
+            expect(mockSocket.on).toHaveBeenCalledWith('error', expect.any(Function));
+        });
+
+        it('should send V2 init message on connection open', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+
+            mockSocket._triggerOpen();
+
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify({
+                event: 'init',
+                protocolVersion: 2,
+                token: 'test-token'
+            }));
+            expect(logMessages).toContain('WebSocket connected. Sending init/auth message.');
+        });
+
+        it('should work without logger', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token' });
+
+            mockSocket._triggerOpen();
+
+            expect(MockedWebSocket).toHaveBeenCalled();
+            expect(mockSocket.send).toHaveBeenCalled();
+        });
+    });
+
+    describe('Authorization Flow', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            mockSocket._triggerOpen();
+            jest.clearAllMocks();
+        });
+
+        it('should handle authorization acknowledgment with customMetrics', () => {
+            mockSocket._triggerMessage(authAck([{ type: 'cumulative', id: 'test', attributes: [], subject: 'sub' }]));
+
+            expect(logMessages).toContain('Authorization acknowledged by server.');
+        });
+
+        it('should call onAuthorized callback with InitAck', () => {
+            const onAuthorized = jest.fn();
+            connection = new WebSocketConnection({
+                organization: 'test-org', token: 'test-token', logger: mockLogger, onAuthorized
+            });
+            mockSocket._triggerOpen();
+
+            const customMetrics: CustomMetricSpecification[] = [{ type: 'cumulative', id: 'test', attributes: [], subject: 'sub' }];
+            mockSocket._triggerMessage(authAck(customMetrics));
+
+            expect(onAuthorized).toHaveBeenCalledWith({ type: 'ack-authorized', customMetrics });
+        });
+
+        it('should replay queued messages after authorization', () => {
+            const serviceMessage: NewObservedServiceMessage = {
+                event: 'new-entity',
+                type: 'service',
+                hash: 'test-hash-1',
+                name: 'test-service'
+            };
+
+            const observationMessage: ObservationMessage = {
+                event: 'observations',
+                seq: 1,
+                observations: [{
+                    type: 'http-server',
+                    subject: 'test-subject',
+                    spanId: 'span1',
+                    traceId: 'trace1',
+                    timestamp: [1700000000, 0],
+                    path: '/test',
+                    status: 200,
+                    duration: [0, 100000000]
+                } as HttpServerObservation]
+            };
+
+            connection.sendMessage(serviceMessage);
+            connection.sendMessage(observationMessage);
+
+            expect(mockSocket.send).not.toHaveBeenCalled();
+
+            mockSocket._triggerMessage(authAck());
+
+            expect(mockSocket.send).toHaveBeenCalledTimes(2);
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(serviceMessage));
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(observationMessage));
+        });
+
+        it('should send messages immediately when already authorized', () => {
+            mockSocket._triggerMessage(authAck());
+            jest.clearAllMocks();
+
+            const serviceMessage: NewObservedServiceMessage = {
+                event: 'new-entity',
+                type: 'service',
+                hash: 'test-hash',
+                name: 'test-service'
+            };
+
+            connection.sendMessage(serviceMessage);
+
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(serviceMessage));
+        });
+    });
+
+    describe('Context Handling', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            mockSocket._triggerOpen();
+        });
+
+        it('should send context-start after auth when process context is set before auth', () => {
+            connection.setProcessContext('service-hash', { 'service.name': 'test' });
+
+            // Not authorized yet, so no context-start sent
+            mockSocket.send.mockClear();
+
+            mockSocket._triggerMessage(authAck());
+
+            // Should have sent context-start first
+            const sentMessages = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]));
+            const contextMsg = sentMessages.find((m: any) => m.event === 'context-start');
+            expect(contextMsg).toMatchObject({
+                event: 'context-start',
+                type: 'process',
+                serviceEntityHash: 'service-hash',
+                resources: { 'service.name': 'test' },
+                ingestionId: expect.any(String),
+            });
+        });
+
+        it('should send context-start immediately when already authorized', () => {
+            mockSocket._triggerMessage(authAck());
+            mockSocket.send.mockClear();
+
+            connection.setProcessContext('service-hash', { 'service.name': 'test' });
+
+            const sentMessages = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]));
+            expect(sentMessages[0]).toMatchObject({
+                event: 'context-start',
+                type: 'process',
+                serviceEntityHash: 'service-hash',
+            });
+        });
+
+        it('should re-send context-start on reconnect before other replays', () => {
+            connection.setProcessContext('service-hash', { 'service.name': 'test' });
+            mockSocket._triggerMessage(authAck());
+
+            // Send an entity message
+            const entityMsg: NewObservedServiceMessage = {
+                event: 'new-entity', type: 'service', hash: 'h1', name: 'svc'
+            };
+            connection.sendMessage(entityMsg);
+
+            // Reconnect
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+
+            mockSocket._triggerMessage(authAck());
+
+            const sentMessages = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]));
+            // Context should come first
+            expect(sentMessages[0].event).toBe('context-start');
+        });
+    });
+
+    describe('Message Acknowledgment Handling', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            mockSocket._triggerOpen();
+            mockSocket._triggerMessage(authAck());
+            jest.clearAllMocks();
+        });
+
+        it('should handle entity/interaction acknowledgments', () => {
+            const serviceMessage: NewObservedServiceMessage = {
+                event: 'new-entity', type: 'service', hash: 'service-hash', name: 'test-service'
+            };
+            const routeMessage: NewObservedHttpRouteMessage = {
+                event: 'new-entity', type: 'http-route', hash: 'route-hash',
+                parent: 'service-hash', method: 'GET', route: '/test'
+            };
+
+            connection.sendMessage(serviceMessage);
+            connection.sendMessage(routeMessage);
+
+            // Acknowledge the service
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-observed', hash: 'service-hash' }));
+
+            mockSocket.send.mockClear();
+
+            // Reconnect — only unacked route should replay
+            mockSocket._triggerClose(1000, 'test close');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+
+            mockSocket._triggerMessage(authAck());
+
+            expect(mockSocket.send).toHaveBeenCalledTimes(1);
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(routeMessage));
+        });
+
+        it('should handle observation acknowledgments', () => {
+            const obs1: ObservationMessage = { event: 'observations', seq: 1, observations: [] };
+            const obs2: ObservationMessage = { event: 'observations', seq: 2, observations: [] };
+
+            connection.sendMessage(obs1);
+            connection.sendMessage(obs2);
+
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-observations', seq: 1 }));
+
+            mockSocket.send.mockClear();
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+
+            mockSocket._triggerMessage(authAck());
+
+            expect(mockSocket.send).toHaveBeenCalledTimes(1);
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(obs2));
+        });
+
+        it('should handle timeseries acknowledgments', () => {
+            const msg: TimeSeriesMetricsMessage = {
+                event: 'timeseries', seq: 5, data: []
+            };
+            connection.sendMessage(msg);
+
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-timeseries', seq: 5 }));
+
+            mockSocket.send.mockClear();
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+            mockSocket._triggerMessage(authAck());
+
+            // Should not replay the acked message
+            const sentEvents = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]).event);
+            expect(sentEvents).not.toContain('timeseries');
+        });
+
+        it('should handle cumulative acknowledgments', () => {
+            const msg: CumulativeMetricsMessage = { event: 'cumulative', seq: 3, data: [] };
+            connection.sendMessage(msg);
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-cumulative', seq: 3 }));
+
+            mockSocket.send.mockClear();
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+            mockSocket._triggerMessage(authAck());
+
+            const sentEvents = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]).event);
+            expect(sentEvents).not.toContain('cumulative');
+        });
+
+        it('should handle tracespans acknowledgments', () => {
+            const msg: TraceSpansMessage = { event: 'tracespans', seq: 7, data: [] };
+            connection.sendMessage(msg);
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-tracespans', seq: 7 }));
+
+            mockSocket.send.mockClear();
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+            mockSocket._triggerMessage(authAck());
+
+            const sentEvents = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]).event);
+            expect(sentEvents).not.toContain('tracespans');
+        });
+
+        it('should handle db-query acknowledgments', () => {
+            const msg: DatabaseQueryMessage = {
+                event: 'db-query', seq: 9, query: 'SELECT 1', from: 'a', to: 'b',
+                timestamp: [0, 0], duration: [0, 0]
+            };
+            connection.sendMessage(msg);
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-db-query', seq: 9 }));
+
+            mockSocket.send.mockClear();
+            mockSocket._triggerClose(1000, 'test');
+            jest.advanceTimersByTime(1000);
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+            mockSocket._triggerMessage(authAck());
+
+            const sentEvents = mockSocket.send.mock.calls.map(c => JSON.parse(c[0]).event);
+            expect(sentEvents).not.toContain('db-query');
+        });
+
+        it('should handle context acknowledgments', () => {
+            connection.setProcessContext('svc-hash', { 'service.name': 'test' });
+            mockSocket._triggerMessage(authAck());
+
+            // Find the context seq
+            const contextCall = mockSocket.send.mock.calls.find(c => {
+                const m = JSON.parse(c[0]);
+                return m.event === 'context-start';
+            });
+            const contextSeq = JSON.parse(contextCall![0]).seq;
+
+            mockSocket._triggerMessage(JSON.stringify({ type: 'ack-context', seq: contextSeq }));
+
+            // On reconnect, context-start should still be sent (because setProcessContext data persists)
+            // but the acked one should be removed from the unack queue
+        });
+    });
+
+    describe('Custom Metric Change', () => {
+        it('should call onCustomMetricChange callback', () => {
+            const onCustomMetricChange = jest.fn();
+            connection = new WebSocketConnection({
+                organization: 'test-org', token: 'test-token', onCustomMetricChange
+            });
+            mockSocket._triggerOpen();
+            mockSocket._triggerMessage(authAck());
+
+            const specs: CustomMetricSpecification[] = [
+                { type: 'timeseries', id: 'metric1', attributes: ['a'], subject: 'sub1' }
+            ];
+            mockSocket._triggerMessage(JSON.stringify({
+                type: 'custom-metric-change',
+                customMetrics: specs
+            }));
+
+            expect(onCustomMetricChange).toHaveBeenCalledWith(specs);
+        });
+    });
+
+    describe('Shared Sequence Counter', () => {
+        it('should provide incrementing sequence numbers', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token' });
+
+            expect(connection.nextSeq()).toBe(1);
+            expect(connection.nextSeq()).toBe(2);
+            expect(connection.nextSeq()).toBe(3);
+        });
+    });
+
+    describe('Reconnection Logic', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            mockSocket._triggerOpen();
+        });
+
+        it('should reconnect automatically on close', () => {
+            const setTimeoutSpy = jest.spyOn(global, 'setTimeout');
+
+            mockSocket._triggerClose(1000, 'Normal closure');
+
+            expect(logMessages).toContain('WebSocket disconnected. Code: 1000, Reason: Normal closure');
+            expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 1000);
+
+            jest.advanceTimersByTime(1000);
+            expect(MockedWebSocket).toHaveBeenCalledTimes(2);
+
+            setTimeoutSpy.mockRestore();
+        });
+
+        it('should reset authorization state on close', () => {
+            mockSocket._triggerMessage(authAck());
+
+            const testMessage: NewObservedServiceMessage = {
+                event: 'new-entity', type: 'service', hash: 'test-hash', name: 'test-service'
+            };
+            connection.sendMessage(testMessage);
+            expect(mockSocket.send).toHaveBeenCalled();
+
+            jest.clearAllMocks();
+            mockSocket._triggerClose(1000, 'test');
+
+            connection.sendMessage(testMessage);
+            expect(mockSocket.send).not.toHaveBeenCalled();
+        });
+
+        it('should not reconnect when explicitly closed', () => {
+            connection.close();
+            mockSocket._triggerClose(1000, 'Explicit close');
+
+            jest.advanceTimersByTime(5000);
+            expect(MockedWebSocket).toHaveBeenCalledTimes(1);
+        });
+    });
+
+    describe('Error Handling', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+        });
+
+        it('should log WebSocket errors', () => {
+            const testError = new Error('Connection failed');
+            mockSocket._triggerError(testError);
+
+            expect(logMessages).toContain('WebSocket encountered an error: Connection failed');
+        });
+
+        it('should handle malformed server messages gracefully', () => {
+            mockSocket._triggerOpen();
+            mockSocket._triggerMessage('{invalid json}');
+
+            const errorLogExists = logMessages.some(msg =>
+                msg.startsWith('Error parsing message from server:') &&
+                msg.includes('JSON')
+            );
+            expect(errorLogExists).toBe(true);
+        });
+
+        it('should not send messages when socket is not open', () => {
+            mockSocket.readyState = WebSocket.CLOSED;
+            mockSocket._triggerOpen();
+            mockSocket._triggerMessage(authAck());
+            mockSocket.send.mockClear();
+
+            mockSocket.readyState = WebSocket.CLOSED;
+
+            const testMessage: NewObservedServiceMessage = {
+                event: 'new-entity', type: 'service', hash: 'test-hash', name: 'test-service'
+            };
+            connection.sendMessage(testMessage);
+
+            expect(mockSocket.send).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('Connection Lifecycle', () => {
+        it('should close WebSocket connection properly', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            connection.close();
+            expect(mockSocket.close).toHaveBeenCalled();
+        });
+
+        it('should handle close when socket is null', () => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            (connection as any).socket = null;
+            expect(() => connection.close()).not.toThrow();
+        });
+    });
+
+    describe('Message Queuing for All Types', () => {
+        beforeEach(() => {
+            connection = new WebSocketConnection({ organization: 'test-org', token: 'test-token', logger: mockLogger });
+            mockSocket._triggerOpen();
+            mockSocket.send.mockClear();
+        });
+
+        it('should queue and replay timeseries messages', () => {
+            const msg: TimeSeriesMetricsMessage = {
+                event: 'timeseries', seq: 1, data: [
+                    { subject: 's', type: 't', timestamp: [0, 0], value: 42, unit: 'By', attributes: {} }
+                ]
+            };
+            connection.sendMessage(msg);
+            expect(mockSocket.send).not.toHaveBeenCalled();
+
+            mockSocket._triggerMessage(authAck());
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(msg));
+        });
+
+        it('should queue and replay cumulative messages', () => {
+            const msg: CumulativeMetricsMessage = {
+                event: 'cumulative', seq: 2, data: []
+            };
+            connection.sendMessage(msg);
+            expect(mockSocket.send).not.toHaveBeenCalled();
+
+            mockSocket._triggerMessage(authAck());
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(msg));
+        });
+
+        it('should queue and replay tracespans messages', () => {
+            const msg: TraceSpansMessage = {
+                event: 'tracespans', seq: 3, data: [
+                    { trace: 't1', span: 's1', parent: '', name: 'test', timestamp: [0, 0] }
+                ]
+            };
+            connection.sendMessage(msg);
+            expect(mockSocket.send).not.toHaveBeenCalled();
+
+            mockSocket._triggerMessage(authAck());
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(msg));
+        });
+
+        it('should queue and replay db-query messages', () => {
+            const msg: DatabaseQueryMessage = {
+                event: 'db-query', seq: 4, query: 'SELECT 1', from: 'a', to: 'b',
+                timestamp: [0, 0], duration: [0, 1000000]
+            };
+            connection.sendMessage(msg);
+            expect(mockSocket.send).not.toHaveBeenCalled();
+
+            mockSocket._triggerMessage(authAck());
+            expect(mockSocket.send).toHaveBeenCalledWith(JSON.stringify(msg));
+        });
+    });
+});