@yousolution/node-red-contrib-you-tunnel-websocket 1.1.1 → 1.2.0

package/test/output-events.test.js

@@ -0,0 +1,241 @@
+/**
+ * wstunnel server — Output Events (Regression Test)
+ *
+ * Tests that the wstunnel server node emits connect and disconnect events
+ * on its output when tunnels register (CONFIG handshake) and close.
+ */
+
+const path = require('path');
+const { EventEmitter } = require('events');
+
+const WS_TUNNEL_PATH = path.join(__dirname, '..', 'nodes', 'wsTunnel.js');
+
+const PORT = 1880;
+const TUNNEL_ID = 'test-tunnel-uuid-001';
+
+let serverHandlers = {};
+let mockTunnels = {};
+
+const mockStopWebSocketServer = jest.fn(() => Promise.resolve());
+
+const mockStartWebSocketServer = jest.fn((opts) => {
+  serverHandlers = {};
+  mockTunnels = {};
+  return Promise.resolve({
+    [opts.port]: {
+      webSocketServer: {
+        on: jest.fn((event, handler) => {
+          serverHandlers[event] = handler;
+        }),
+        clients: new Set(),
+      },
+      websocketTunnels: mockTunnels,
+    },
+  });
+});
+
+const mockLogger = {
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+  trace: jest.fn(),
+};
+const mockSetLogContext = jest.fn();
+const mockSetLogLevel = jest.fn();
+
+function createMockRED() {
+  const registeredTypes = {};
+  return {
+    nodes: {
+      createNode: jest.fn((node) => {
+        if (!node.id) node.id = 'node-' + Math.random().toString(36).slice(2, 9);
+        node.status = jest.fn();
+        node.send = jest.fn();
+        node.on = jest.fn((event, handler) => {
+          node._handlers = node._handlers || {};
+          node._handlers[event] = handler;
+        });
+      }),
+      registerType: jest.fn((type, constructor) => {
+        registeredTypes[type] = constructor;
+      }),
+      getNode: jest.fn(() => ({
+        options: {
+          name: 'test-tunnel',
+          host: 'localhost',
+          port: PORT,
+          path: '',
+          tunnelIdHeaderName: 'x-tunnel-id',
+          logLevel: 'info',
+        },
+      })),
+    },
+    _registeredTypes: registeredTypes,
+  };
+}
+
+function createMockWs(remoteAddress = '192.168.1.10') {
+  const ws = new EventEmitter();
+  ws._socket = { remoteAddress, remotePort: 54321 };
+  ws.readyState = 1;
+  return ws;
+}
+
+describe('wstunnel server — output events', () => {
+  beforeAll(() => {
+    const serverModule = require('@remotelinker/reverse-ws-tunnel/server');
+    serverModule.stopWebSocketServer = mockStopWebSocketServer;
+    serverModule.startWebSocketServer = mockStartWebSocketServer;
+
+    const utilsModule = require('@remotelinker/reverse-ws-tunnel/utils');
+    utilsModule.logger = mockLogger;
+    utilsModule.setLogContext = mockSetLogContext;
+    utilsModule.setLogLevel = mockSetLogLevel;
+  });
+
+  beforeEach(() => {
+    serverHandlers = {};
+    mockTunnels = {};
+    mockStopWebSocketServer.mockClear();
+    mockStartWebSocketServer.mockClear();
+    mockLogger.info.mockClear();
+    mockLogger.error.mockClear();
+    mockLogger.debug.mockClear();
+  });
+
+  test('emits connect event when tunnel registers via CONFIG', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = { id: 'testNode' };
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const mockWs = createMockWs('10.0.0.1');
+    const connectedAt = Date.now();
+
+    mockTunnels[TUNNEL_ID] = { ws: mockWs };
+
+    serverHandlers['connection'](mockWs);
+
+    mockWs.emit('message', Buffer.from('config'));
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(node.send).toHaveBeenCalledTimes(1);
+    expect(node.send).toHaveBeenCalledWith({
+      event: 'connect',
+      tunnelId: TUNNEL_ID,
+      remoteAddress: '10.0.0.1',
+      connectedAt: expect.any(Number),
+      serverPort: PORT,
+    });
+  });
+
+  test('emits disconnect event when registered tunnel closes', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = { id: 'testNode' };
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const mockWs = createMockWs('10.0.0.2');
+    mockTunnels[TUNNEL_ID] = { ws: mockWs };
+
+    serverHandlers['connection'](mockWs);
+    mockWs.emit('message', Buffer.from('config'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    node.send.mockClear();
+
+    mockWs.emit('close');
+
+    expect(node.send).toHaveBeenCalledTimes(1);
+    expect(node.send).toHaveBeenCalledWith({
+      event: 'disconnect',
+      tunnelId: TUNNEL_ID,
+      remoteAddress: '10.0.0.2',
+      serverPort: PORT,
+    });
+  });
+
+  test('does not emit events for connections without CONFIG', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = { id: 'testNode' };
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const mockWs = createMockWs('10.0.0.3');
+
+    serverHandlers['connection'](mockWs);
+
+    mockWs.emit('close');
+
+    expect(node.send).not.toHaveBeenCalled();
+  });
+
+  test('connect event contains all expected fields', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = { id: 'testNode' };
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const mockWs = createMockWs('172.16.0.5');
+    mockTunnels[TUNNEL_ID] = { ws: mockWs };
+
+    serverHandlers['connection'](mockWs);
+    mockWs.emit('message', Buffer.from('config'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const sentMsg = node.send.mock.calls[0][0];
+    expect(sentMsg).toHaveProperty('event', 'connect');
+    expect(sentMsg).toHaveProperty('tunnelId', TUNNEL_ID);
+    expect(sentMsg).toHaveProperty('remoteAddress', '172.16.0.5');
+    expect(sentMsg).toHaveProperty('connectedAt');
+    expect(typeof sentMsg.connectedAt).toBe('number');
+    expect(sentMsg).toHaveProperty('serverPort', PORT);
+  });
+
+  test('disconnect event is not emitted for unconfirmed connections', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = { id: 'testNode' };
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const mockWs = createMockWs('10.0.0.4');
+
+    serverHandlers['connection'](mockWs);
+
+    mockWs.emit('message', Buffer.from('config'));
+    await new Promise((resolve) => setImmediate(resolve));
+
+    node.send.mockClear();
+
+    mockWs.emit('close');
+
+    expect(node.send).not.toHaveBeenCalled();
+  });
+});

package/test/rwt-001-port-exclusivity.test.js

@@ -0,0 +1,171 @@
+/**
+ * RWT-001 — Exclusive Server Ownership of a Port
+ *
+ * A replacement managed WebSocket server must not be started on a port until
+ * the previously managed server on that port has completed its shutdown.
+ */
+
+const path = require('path');
+
+const WS_TUNNEL_PATH = path.join(__dirname, '..', 'nodes', 'wsTunnel.js');
+
+// Track call order across mocks
+let callLog = [];
+
+// Mock stopWebSocketServer
+const mockStopWebSocketServer = jest.fn((port) => {
+  callLog.push({ fn: 'stopWebSocketServer', port });
+  return new Promise((resolve) => {
+    setImmediate(() => {
+      callLog.push({ fn: 'stopWebSocketServer-resolved', port });
+      resolve();
+    });
+  });
+});
+
+// Mock startWebSocketServer
+const mockStartWebSocketServer = jest.fn((opts) => {
+  callLog.push({ fn: 'startWebSocketServer', port: opts.port });
+  return Promise.resolve({
+    [opts.port]: {
+      webSocketServer: {
+        on: jest.fn(),
+        clients: new Set(),
+      },
+    },
+  });
+});
+
+// Mock logger
+const mockLogger = {
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+  trace: jest.fn(),
+};
+
+// Mock setLogContext and setLogLevel
+const mockSetLogContext = jest.fn();
+const mockSetLogLevel = jest.fn();
+
+// Mock RED object
+function createMockRED() {
+  const registeredTypes = {};
+  return {
+    nodes: {
+      createNode: jest.fn((node, config) => {
+        node.status = jest.fn();
+        node.on = jest.fn((event, handler) => {
+          node._handlers = node._handlers || {};
+          node._handlers[event] = handler;
+        });
+      }),
+      registerType: jest.fn((type, constructor) => {
+        registeredTypes[type] = constructor;
+      }),
+      getNode: jest.fn((id) => ({
+        options: {
+          name: 'test-tunnel',
+          host: 'localhost',
+          port: 1880,
+          path: '',
+          tunnelIdHeaderName: 'x-tunnel-id',
+          logLevel: 'info',
+        },
+      })),
+    },
+    _registeredTypes: registeredTypes,
+  };
+}
+
+describe('RWT-001 — Exclusive Server Ownership of a Port', () => {
+  let originalModules;
+
+  beforeAll(() => {
+    originalModules = {
+      stopWebSocketServer: require('@remotelinker/reverse-ws-tunnel/server').stopWebSocketServer,
+    };
+
+    // Replace the module exports before requiring wsTunnel
+    const serverModule = require('@remotelinker/reverse-ws-tunnel/server');
+    serverModule.stopWebSocketServer = mockStopWebSocketServer;
+    serverModule.startWebSocketServer = mockStartWebSocketServer;
+
+    const utilsModule = require('@remotelinker/reverse-ws-tunnel/utils');
+    utilsModule.logger = mockLogger;
+    utilsModule.setLogContext = mockSetLogContext;
+    utilsModule.setLogLevel = mockSetLogLevel;
+  });
+
+  beforeEach(() => {
+    callLog = [];
+    mockStopWebSocketServer.mockClear();
+    mockStartWebSocketServer.mockClear();
+    mockLogger.info.mockClear();
+    mockSetLogContext.mockClear();
+    mockSetLogLevel.mockClear();
+  });
+
+  afterAll(() => {
+    // Restore original modules
+    const serverModule = require('@remotelinker/reverse-ws-tunnel/server');
+    serverModule.stopWebSocketServer = originalModules.stopWebSocketServer;
+  });
+
+  test('stopWebSocketServer is called before startWebSocketServer on node creation', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    // Get the registered WSTunnelServer constructor
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    expect(WSTunnelServer).toBeDefined();
+
+    // Create a mock node config
+    const nodeConfig = {
+      wstunnel: 'test-config-id',
+      name: 'test-server',
+    };
+
+    // Instantiate the node
+    const node = {};
+    WSTunnelServer.call(node, nodeConfig);
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Verify stopWebSocketServer was called
+    expect(mockStopWebSocketServer).toHaveBeenCalled();
+
+    // Verify startWebSocketServer was called
+    expect(mockStartWebSocketServer).toHaveBeenCalled();
+
+    // Verify ordering: stopWebSocketServer must complete before startWebSocketServer
+    const stopIndex = callLog.findIndex((e) => e.fn === 'stopWebSocketServer-resolved');
+    const startIndex = callLog.findIndex((e) => e.fn === 'startWebSocketServer');
+
+    expect(stopIndex).toBeGreaterThanOrEqual(0);
+    expect(startIndex).toBeGreaterThanOrEqual(0);
+    expect(stopIndex).toBeLessThan(startIndex);
+  });
+
+  test('the correct port is passed to both stop and start', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    const node = {};
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const stopCall = mockStopWebSocketServer.mock.calls[0];
+    const startCall = mockStartWebSocketServer.mock.calls[0];
+
+    expect(stopCall[0]).toBe(1880);
+    expect(startCall[0].port).toBe(1880);
+  });
+});

package/test/rwt-001-port-release.test.js

@@ -0,0 +1,58 @@
+/**
+ * RWT-001 — Port Release Guarantee (Deterministic)
+ *
+ * stopWebSocketServer(port) must release the port before resolving.
+ * A replacement server must bind to the same port without EADDRINUSE.
+ */
+
+const { startWebSocketServer, stopWebSocketServer } = require('@remotelinker/reverse-ws-tunnel/server');
+
+const TEST_PORT = 18999;
+
+describe('RWT-001 — Port release after stopWebSocketServer', () => {
+  afterEach(async () => {
+    await stopWebSocketServer(TEST_PORT);
+  });
+
+  test('port is available immediately after stopWebSocketServer resolves', async () => {
+    const state1 = await startWebSocketServer({
+      port: TEST_PORT,
+      tunnelIdHeaderName: 'x-tunnel-id',
+    });
+
+    expect(state1[TEST_PORT]).toBeDefined();
+    expect(state1[TEST_PORT].webSocketServer).toBeDefined();
+
+    await stopWebSocketServer(TEST_PORT);
+
+    const state2 = await startWebSocketServer({
+      port: TEST_PORT,
+      tunnelIdHeaderName: 'x-tunnel-id',
+    });
+
+    expect(state2[TEST_PORT]).toBeDefined();
+    expect(state2[TEST_PORT].webSocketServer).toBeDefined();
+
+    await stopWebSocketServer(TEST_PORT);
+  });
+
+  test('rapid stop-then-start cycle does not produce EADDRINUSE', async () => {
+    const state1 = await startWebSocketServer({
+      port: TEST_PORT,
+      tunnelIdHeaderName: 'x-tunnel-id',
+    });
+
+    expect(state1[TEST_PORT]).toBeDefined();
+
+    for (let i = 0; i < 3; i++) {
+      await stopWebSocketServer(TEST_PORT);
+      const state = await startWebSocketServer({
+        port: TEST_PORT,
+        tunnelIdHeaderName: 'x-tunnel-id',
+      });
+      expect(state[TEST_PORT]).toBeDefined();
+    }
+
+    await stopWebSocketServer(TEST_PORT);
+  });
+});

package/test/rwt-002-shutdown-completion.test.js

@@ -0,0 +1,226 @@
+/**
+ * RWT-002 — Node Shutdown Must Signal Completion
+ *
+ * When a WSTunnelServer node receives a Node-RED close event, its shutdown
+ * handler must always signal completion by invoking done(), including failure paths.
+ */
+
+const path = require('path');
+
+const WS_TUNNEL_PATH = path.join(__dirname, '..', 'nodes', 'wsTunnel.js');
+
+// Mock state
+let mockStopResolved = true;
+
+// Mock stopWebSocketServer
+const mockStopWebSocketServer = jest.fn((port) => {
+  return new Promise((resolve, reject) => {
+    setImmediate(() => {
+      if (mockStopResolved) {
+        resolve();
+      } else {
+        reject(new Error('Stop failed'));
+      }
+    });
+  });
+});
+
+// Mock startWebSocketServer
+const mockStartWebSocketServer = jest.fn((opts) => {
+  return Promise.resolve({
+    [opts.port]: {
+      webSocketServer: {
+        on: jest.fn(),
+        clients: new Set(),
+      },
+    },
+  });
+});
+
+// Mock logger
+const mockLogger = {
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  debug: jest.fn(),
+  trace: jest.fn(),
+};
+
+// Mock setLogContext and setLogLevel
+const mockSetLogContext = jest.fn();
+const mockSetLogLevel = jest.fn();
+
+// Mock RED object
+function createMockRED() {
+  const registeredTypes = {};
+  return {
+    nodes: {
+      createNode: jest.fn((node, config) => {
+        node.status = jest.fn();
+        node.on = jest.fn((event, handler) => {
+          node._handlers = node._handlers || {};
+          node._handlers[event] = handler;
+        });
+      }),
+      registerType: jest.fn((type, constructor) => {
+        registeredTypes[type] = constructor;
+      }),
+      getNode: jest.fn((id) => ({
+        options: {
+          name: 'test-tunnel',
+          host: 'localhost',
+          port: 1880,
+          path: '',
+          tunnelIdHeaderName: 'x-tunnel-id',
+          logLevel: 'info',
+        },
+      })),
+    },
+    _registeredTypes: registeredTypes,
+  };
+}
+
+function createNode(RED) {
+  const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+  const node = {};
+  WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+  return node;
+}
+
+describe('RWT-002 — Node Shutdown Must Signal Completion', () => {
+  beforeAll(() => {
+    const serverModule = require('@remotelinker/reverse-ws-tunnel/server');
+    serverModule.stopWebSocketServer = mockStopWebSocketServer;
+    serverModule.startWebSocketServer = mockStartWebSocketServer;
+
+    const utilsModule = require('@remotelinker/reverse-ws-tunnel/utils');
+    utilsModule.logger = mockLogger;
+    utilsModule.setLogContext = mockSetLogContext;
+    utilsModule.setLogLevel = mockSetLogLevel;
+  });
+
+  beforeEach(() => {
+    mockStopResolved = true;
+    mockStopWebSocketServer.mockClear();
+    mockStartWebSocketServer.mockClear();
+    mockLogger.info.mockClear();
+    mockSetLogContext.mockClear();
+    mockSetLogLevel.mockClear();
+  });
+
+  test('done() is called on successful stopWebSocketServer', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const node = createNode(RED);
+    const done = jest.fn();
+
+    // Simulate the close event
+    node._handlers.close.call(node, false, done);
+
+    // Wait for the close handler promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(done).toHaveBeenCalledTimes(1);
+  });
+
+  test('done() is called on failed stopWebSocketServer', async () => {
+    mockStopResolved = false;
+
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const node = createNode(RED);
+    const done = jest.fn();
+
+    // Simulate the close event
+    node._handlers.close.call(node, false, done);
+
+    // Wait for the close handler promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(done).toHaveBeenCalledTimes(1);
+  });
+
+  test('done() is called when no server state exists', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    // Create a node without waiting for server setup
+    const node = {};
+    RED.nodes.createNode = jest.fn((n, config) => {
+      n.status = jest.fn();
+      n.on = jest.fn((event, handler) => {
+        n._handlers = n._handlers || {};
+        n._handlers[event] = handler;
+      });
+    });
+
+    const WSTunnelServer = RED._registeredTypes['wstunnel server'];
+    WSTunnelServer.call(node, { wstunnel: 'test-config-id', name: 'test-server' });
+
+    // Don't wait for server setup — close immediately
+    const done = jest.fn();
+    node._handlers.close.call(node, false, done);
+
+    // The close handler calls done() synchronously when no server state exists
+    // A single microtask flush is sufficient
+    await Promise.resolve();
+
+    expect(done).toHaveBeenCalledTimes(1);
+  });
+
+  test('done() is never called more than once', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const node = createNode(RED);
+    const done = jest.fn();
+
+    node._handlers.close.call(node, false, done);
+
+    // Wait for the close handler promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    expect(done).toHaveBeenCalledTimes(1);
+  });
+
+  test('cleanup completes before done() is called', async () => {
+    const RED = createMockRED();
+    const tunnelModule = require(WS_TUNNEL_PATH);
+    tunnelModule(RED);
+
+    const node = createNode(RED);
+
+    // Wait for the constructor promise chain (mockStopWebSocketServer resolves via setImmediate)
+    await new Promise((resolve) => setImmediate(resolve));
+
+    const done = jest.fn();
+
+    // Call close handler — stopWebSocketServer starts but hasn't resolved yet
+    node._handlers.close.call(node, false, done);
+
+    // done() must NOT be called synchronously (before the promise chain resolves)
+    // The mock resolves via setImmediate, which hasn't fired yet at this point
+    expect(done).not.toHaveBeenCalled();
+
+    // Flush the promise chain
+    await new Promise((resolve) => setImmediate(resolve));
+
+    // Now done() should have been called
+    expect(done).toHaveBeenCalledTimes(1);
+  });
+});