@remotelinker/reverse-ws-tunnel 1.0.9 → 1.0.11

package/README.md

@@ -30,7 +30,46 @@ Reverse WebSocket Tunnel is a library that enables you to expose local services
 
 ---
 
-## ✨ v1.0.9 - What's New
+## ✨ v1.0.11 - What's New
+
+### ✨ New Features
+- **stopWebSocketServer(port)**: Added new function to properly stop and cleanup the WebSocket server
+  - Closes all active WebSocket connections (triggering cleanup of heartbeat intervals)
+  - Closes all TCP servers registered in state
+  - Cleans up state for the specified port
+  - Gracefully handles already-stopped servers (no errors)
+
+### 🐛 Bug Fixes
+- **Heartbeat cleanup**: Fixed issue where setInterval for heartbeat was not properly cleaned up when server stopped
+- **Node-RED integration**: Added cleanup on startup to handle cases where previous deployment didn't cleanup properly
+- **TCP server connection hang**: Fixed critical issue where TCP connections would hang indefinitely
+  - Removed `pauseOnConnect: true` option from TCP server configuration
+  - This option was added in error - it pauses sockets on connect and requires manual `socket.resume()`
+  - The fix restores proper connection flow while keeping `reuseAddr: true` for port reuse on restart
+- **TCP server port reuse**: Fixed "EADDRINUSE" error when client reconnects after Node-RED restart
+  - Now checks if TCP server is actually listening (`server.listening`) before skipping creation
+  - Previously only checked if state entry existed, not if server was active
+- **TCP server global registry**: Added global tcpServers registry to track TCP servers even when not in state
+  - When stopWebSocketServer is called, now closes ALL TCP servers in global registry
+  - When creating new TCP server, checks global registry and closes stale servers before creating new one
+
+### 🔧 Improvements
+- **Graceful shutdown**: Server now properly releases all resources (ports, memory, intervals) on shutdown
+- **State management**: Improved state cleanup to prevent stale entries after server restart
+
+---
+
+## ✨ v1.0.10 - Previous Release
+
+### 🔧 Code Quality & Developer Experience
+- **Code Cleanup**: Removed unused constants and redundant variables
+- **Input Validation**: Added tunnelId validation for incoming messages
+- **Code Formatting**: Added Prettier configuration for consistent code style
+- **Test Suite**: Reorganized tests, removed obsolete files, added new test coverage
+
+---
+
+## ✨ v1.0.9 - Previous Release
 
 ### 🐛 Bug Fixes
 - **Message Format Standardization**: Fixed inconsistent message formats between server components
@@ -332,6 +371,29 @@ Set the log level via:
 - Environment variable: `LOG_LEVEL=debug`
 - TOML config: `logLevel = "debug"`
 
+### Logger API
+
+The library exports logger functions for advanced control:
+
+```javascript
+const { setLogLevel, getLogLevel, setLogContext, getLogContext, logger } = require('@remotelinker/reverse-ws-tunnel/utils');
+
+// Set log level programmatically
+setLogLevel('debug');
+
+// Get current log level
+const currentLevel = getLogLevel();
+
+// Set context for all log messages (useful for Node-RED)
+setLogContext({ nodeId: 'my-node', session: 'abc123' });
+
+// Get current context
+const context = getLogContext();
+
+// Use logger directly
+logger.info('Custom log message', { custom: 'data' });
+```
+
 ---
 
 ## 🔧 Advanced Usage

package/client/index.js

@@ -2,7 +2,17 @@ const { startHttpProxyServer } = require('./proxyServer');
 const { connectWebSocket } = require('./tunnelClient');
 const { setLogContext } = require('../utils/logger');
 
-function startClient({ targetUrl, allowInsicureCerts, wsUrl, tunnelId, tunnelEntryUrl, tunnelEntryPort, headers, environment, autoReconnect }) {
+function startClient({
+  targetUrl,
+  allowInsicureCerts,
+  wsUrl,
+  tunnelId,
+  tunnelEntryUrl,
+  tunnelEntryPort,
+  headers,
+  environment,
+  autoReconnect,
+}) {
   setLogContext('CLIENT');
   environment = environment || 'production';
   const proxy = startHttpProxyServer(targetUrl, allowInsicureCerts);

package/client/index.mjs

@@ -1,2 +1,2 @@
 import cjsModule from './index.js';
-export const { startClient } = cjsModule;
+export const { startClient } = cjsModule;

package/client/proxyServer.js

@@ -24,23 +24,34 @@ function startHttpProxyServer(targetUrl, allowInsecureCerts = false) {
       return res.end('Missing TARGET_URL');
     }
 
-    proxy.web(req, res, { target: targetUrl, changeOrigin: true, secure: !allowInsecureCerts }, (err) => {
-      logger.error('Proxy web error:', err);
-      if (!res.headersSent) {
-        res.writeHead(502);
-        res.end('Bad gateway');
-      } else {
-        res.end();
+    proxy.web(
+      req,
+      res,
+      { target: targetUrl, changeOrigin: true, secure: !allowInsecureCerts },
+      err => {
+        logger.error('Proxy web error:', err);
+        if (!res.headersSent) {
+          res.writeHead(502);
+          res.end('Bad gateway');
+        } else {
+          res.end();
+        }
       }
-    });
+    );
   });
 
   server.on('upgrade', (req, socket, head) => {
     logger.trace(`Incoming WebSocket upgrade: ${req.url}`);
-    proxy.ws(req, socket, head, { target: targetUrl, changeOrigin: false, secure: !allowInsecureCerts }, (err) => {
-      logger.error('Proxy WS upgrade error:', err);
-      socket.end();
-    });
+    proxy.ws(
+      req,
+      socket,
+      head,
+      { target: targetUrl, changeOrigin: false, secure: !allowInsecureCerts },
+      err => {
+        logger.error('Proxy WS upgrade error:', err);
+        socket.end();
+      }
+    );
   });
 
   proxy.on('error', (err, req, res) => {

package/client/tunnelClient.js

@@ -6,7 +6,6 @@ const { buildMessageBuffer } = require('./utils');
 const { logger } = require('../utils/logger');
 const packageJson = require('../package.json');
 
-const RECONNECT_INTERVAL = 5000;
 const MESSAGE_TYPE_CONFIG = 0x01;
 const MESSAGE_TYPE_DATA = 0x02;
 const MESSAGE_TYPE_APP_PING = 0x03;
@@ -23,7 +22,17 @@ const RECONNECT_BACKOFF = [1000, 2000, 5000, 10000, 30000]; // Backoff progressi
  * @param {Object} config - Configuration for tunnel.
  */
 function connectWebSocket(config) {
-  const { wsUrl, tunnelId, targetUrl, targetPort, tunnelEntryUrl, tunnelEntryPort, headers, environment, autoReconnect = true } = config;
+  const {
+    wsUrl,
+    tunnelId,
+    targetUrl,
+    targetPort,
+    tunnelEntryUrl,
+    tunnelEntryPort,
+    headers,
+    environment,
+    autoReconnect = true,
+  } = config;
 
   const eventEmitter = new EventEmitter();
   let ws;
@@ -32,8 +41,6 @@ function connectWebSocket(config) {
   let healthMonitor;
   let isClosed = false;
   let reconnectAttempt = 0;
-  let pingSeq = 0;
-  let lastPongTs = Date.now();
 
   if (!tunnelId) {
     throw new Error(`Missing mandatory tunnelId`);
@@ -43,25 +50,59 @@ function connectWebSocket(config) {
     if (isClosed) return;
 
     try {
-      const headersParsed = headers || '{}';
+      // Parse headers - handle both string and object formats
+      let headersParsed = {};
+      if (headers) {
+        if (typeof headers === 'string') {
+          try {
+            headersParsed = JSON.parse(headers);
+          } catch (e) {
+            logger.warn(`Failed to parse headers string: ${headers}`);
+          }
+        } else if (typeof headers === 'object') {
+          headersParsed = headers;
+        }
+      }
       logger.debug(`Parsed headers: ${JSON.stringify(headersParsed)}`);
       logger.debug(`Try to connect to: ${wsUrl}`);
       ws = new WebSocket(wsUrl, { headers: headersParsed });
       logger.debug(`Connection: ${wsUrl}`);
     } catch (error) {
-      logger.error('Malformed headers:', error);
+      logger.error('Failed to create WebSocket connection:', error);
       return;
     }
 
+    // PingState condiviso tra heartbeat e message handler
+    // Reset completo dello stato per ogni connessione
+    const pingState = {
+      pingSeq: 0,
+      lastPongTs: Date.now(),
+    };
+    const pingStateCallbacks = {
+      pingSeq: () => pingState.pingSeq,
+      incPingSeq: () => pingState.pingSeq++,
+      lastPongTs: () => pingState.lastPongTs,
+      setLastPongTs: ts => (pingState.lastPongTs = ts),
+    };
+
     ws.on('open', () => {
       logger.info(`Connected to WebSocket server ${wsUrl}`);
-      logger.warn(`WS tunnel config sent: TARGET_PORT=${targetPort}, ENTRY_PORT=${tunnelEntryPort}`);
+      logger.warn(
+        `WS tunnel config sent: TARGET_PORT=${targetPort}, ENTRY_PORT=${tunnelEntryPort}`
+      );
+
+      // Reset reconnect attempt on successful connection
+      reconnectAttempt = 0;
+
       eventEmitter.emit('connected');
       ({ pingInterval } = heartBeat(ws));
 
       // Avviare heartbeat applicativo
-      appPingInterval = startAppHeartbeat(ws, tunnelId, { pingSeq: () => pingSeq, incPingSeq: () => pingSeq++ });
-      healthMonitor = startHealthMonitor(ws, tunnelId, { lastPongTs: () => lastPongTs, setLastPongTs: (ts) => lastPongTs = ts });
+      appPingInterval = startAppHeartbeat(ws, tunnelId, pingStateCallbacks);
+      healthMonitor = startHealthMonitor(ws, tunnelId, {
+        lastPongTs: () => pingState.lastPongTs,
+        setLastPongTs: ts => (pingState.lastPongTs = ts),
+      });
 
       const uuid = uuidv4();
       const payload = {
@@ -73,33 +114,50 @@ function connectWebSocket(config) {
         agentVersion: packageJson.version,
       };
 
-      const message = buildMessageBuffer(tunnelId, uuid, MESSAGE_TYPE_CONFIG, JSON.stringify(payload));
+      const message = buildMessageBuffer(
+        tunnelId,
+        uuid,
+        MESSAGE_TYPE_CONFIG,
+        JSON.stringify(payload)
+      );
       logger.debug(`Sending tunnel config [uuid=${uuid}]`);
       ws.send(message);
     });
 
     let messageBuffer = Buffer.alloc(0);
-    
-    ws.on('message', (data) => {
+
+    ws.on('message', data => {
       logger.trace(`Received message chunk: ${data.length} bytes`);
       messageBuffer = Buffer.concat([messageBuffer, data]);
 
       while (messageBuffer.length >= 4) {
         const length = messageBuffer.readUInt32BE(0);
         if (messageBuffer.length < 4 + length) {
-          logger.trace(`Waiting for more data: need ${4 + length} bytes, have ${messageBuffer.length}`);
+          logger.trace(
+            `Waiting for more data: need ${4 + length} bytes, have ${messageBuffer.length}`
+          );
           break;
         }
 
         const message = messageBuffer.slice(4, 4 + length);
         messageBuffer = messageBuffer.slice(4 + length);
 
-        const messageTunnelId = message.slice(0, 36).toString();
+        const messageTunnelId = message.slice(0, 36).toString().trim();
         const uuid = message.slice(36, 72).toString();
         const type = message.readUInt8(72);
         const payload = message.slice(73);
 
-        logger.trace(`Received WS message for uuid=${uuid}, type=${type}, length=${payload.length}`);
+        // Validate tunnelId matches expected tunnel
+        if (messageTunnelId !== tunnelId) {
+          logger.warn(
+            `Received message for wrong tunnel: ${messageTunnelId} (expected: ${tunnelId})`
+          );
+          return;
+        }
+
+        logger.trace(
+          `Received WS message for uuid=${uuid}, type=${type}, length=${payload.length}`
+        );
 
         if (type === MESSAGE_TYPE_DATA) {
           if (payload.toString() === 'CLOSE') {
@@ -110,7 +168,8 @@ function connectWebSocket(config) {
             return;
           }
 
-          const client = clients[uuid] || createTcpClient(targetUrl, targetPort, ws, tunnelId, uuid);
+          const client =
+            clients[uuid] || createTcpClient(targetUrl, targetPort, ws, tunnelId, uuid);
 
           if (!client.write(payload)) {
             logger.debug(`Backpressure on TCP socket for uuid=${uuid}`);
@@ -119,13 +178,13 @@ function connectWebSocket(config) {
             });
           }
           return;
-
         } else if (type === MESSAGE_TYPE_APP_PONG) {
           try {
             const pongData = JSON.parse(payload.toString());
             // Accetta solo pong con seq >= pingSeq - 10 (finestra di 10 ping)
-            if (pongData.seq >= (pingSeq - 10)) {
-              lastPongTs = Date.now();
+            if (pongData.seq >= pingStateCallbacks.pingSeq() - 10) {
+              // Aggiorna lastPongTs usando il callback
+              pingStateCallbacks.setLastPongTs(Date.now());
               logger.trace(`App pong received: seq=${pongData.seq}`);
             } else {
               logger.debug(`Ignoring old pong: seq=${pongData.seq}`);
@@ -152,8 +211,12 @@ function connectWebSocket(config) {
         delete clients[uuid];
       }
 
+      // Reset message buffer on close for proper reconnection
+      messageBuffer = Buffer.alloc(0);
+
       if (!isClosed && autoReconnect) {
-        const delay = RECONNECT_BACKOFF[reconnectAttempt] || RECONNECT_BACKOFF[RECONNECT_BACKOFF.length - 1];
+        const delay =
+          RECONNECT_BACKOFF[reconnectAttempt] || RECONNECT_BACKOFF[RECONNECT_BACKOFF.length - 1];
         logger.info(`Reconnecting in ${delay / 1000}s (attempt ${reconnectAttempt + 1})`);
         setTimeout(() => {
           reconnectAttempt = Math.min(reconnectAttempt + 1, RECONNECT_BACKOFF.length);
@@ -162,7 +225,7 @@ function connectWebSocket(config) {
       }
     });
 
-    ws.on('error', (err) => {
+    ws.on('error', err => {
       logger.error('WebSocket error:', err);
     });
   };
@@ -217,13 +280,13 @@ function createTcpClient(targetUrl, targetPort, ws, tunnelId, uuid) {
     logger.info(`TCP connection established for uuid=${uuid}`);
   });
 
-  client.on('data', (data) => {
+  client.on('data', data => {
     logger.trace(`TCP data received for uuid=${uuid}, length=${data.length}`);
     const message = buildMessageBuffer(tunnelId, uuid, MESSAGE_TYPE_DATA, data);
     ws.send(message);
   });
 
-  client.on('error', (err) => {
+  client.on('error', err => {
     logger.error(`TCP error for uuid=${uuid}:`, err);
     client.destroy();
     delete clients[uuid];
@@ -248,7 +311,7 @@ function startAppHeartbeat(ws, tunnelId, pingState) {
       const pingData = JSON.stringify({
         type: 'ping',
         seq: currentPingSeq,
-        ts: Date.now()
+        ts: Date.now(),
       });
 
       const message = buildMessageBuffer(tunnelId, uuidv4(), MESSAGE_TYPE_APP_PING, pingData);
@@ -273,7 +336,8 @@ function startHealthMonitor(ws, tunnelId, pongState) {
   }, 5000); // Check every 5 seconds
 }
 
-function resetClients() { // for testing
+function resetClients() {
+  // for testing
   for (const key in clients) {
     delete clients[key];
   }
@@ -282,4 +346,4 @@ function resetClients() { // for testing
 module.exports = {
   connectWebSocket,
   resetClients, // for testing
-};
+};

package/client/utils.js

@@ -12,7 +12,8 @@ function buildMessageBuffer(tunnelId, uuid, type, payload) {
   const typeBuffer = Buffer.from([type]);
   const payloadBuffer = Buffer.isBuffer(payload) ? payload : Buffer.from(payload, 'utf8');
 
-  const totalLength = tunnelBuffer.length + uuidBuffer.length + typeBuffer.length + payloadBuffer.length;
+  const totalLength =
+    tunnelBuffer.length + uuidBuffer.length + typeBuffer.length + payloadBuffer.length;
   const lengthBuffer = Buffer.alloc(4);
   lengthBuffer.writeUInt32BE(totalLength);
 

package/index.cjs

@@ -5,5 +5,5 @@ const utils = require('./utils');
 module.exports = {
   ...server,
   ...client,
-  ...utils
-};
+  ...utils,
+};

package/index.mjs

@@ -1,3 +1,3 @@
 export * from './server/index.mjs';
 export * from './client/index.mjs';
-export * from './utils/index.mjs';
+export * from './utils/index.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remotelinker/reverse-ws-tunnel",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "A Node.js library for creating secure reverse tunnels over WebSocket connections",
   "main": "index.cjs",
   "types": "types/index.d.ts",
@@ -41,7 +41,9 @@
     "example:server:esm": "node examples/server/server-example.mjs",
     "example:client": "node examples/client/client-example.js",
     "example:client:esm": "node examples/client/client-example.mjs",
-    "example:webserver": "node examples/webserver/webserver-example.js"
+    "example:webserver": "node examples/webserver/webserver-example.js",
+    "format": "prettier --write \"**/*.js\" \"**/*.mjs\" \"**/*.cjs\"",
+    "format:check": "prettier --check \"**/*.js\" \"**/*.mjs\" \"**/*.cjs\""
   },
   "exports": {
     ".": {
@@ -78,6 +80,7 @@
   },
   "devDependencies": {
     "jest": "^29.7.0",
+    "prettier": "^3.8.1",
     "typescript": "^5.9.3"
   }
 }

package/server/index.js

@@ -1,8 +1,9 @@
 // require('dotenv').config();
-const { startWebSocketServer } = require('./websocketServer');
+const { startWebSocketServer, stopWebSocketServer } = require('./websocketServer');
 const { setLogContext } = require('../utils/logger');
 
 module.exports = {
   startWebSocketServer,
+  stopWebSocketServer,
   setLogContext,
 };

package/server/index.mjs

@@ -1,2 +1,2 @@
 import cjsModule from './index.js';
-export const { startWebSocketServer, setLogContext } = cjsModule;
+export const { startWebSocketServer, setLogContext } = cjsModule;

package/server/messageHandler.js

@@ -1,6 +1,11 @@
 const state = require('./state');
-const { MESSAGE_TYPE_CONFIG, MESSAGE_TYPE_DATA, MESSAGE_TYPE_APP_PING, MESSAGE_TYPE_APP_PONG } = require('./constants');
-const { startTCPServer } = require('./tcpServer');
+const {
+  MESSAGE_TYPE_CONFIG,
+  MESSAGE_TYPE_DATA,
+  MESSAGE_TYPE_APP_PING,
+  MESSAGE_TYPE_APP_PONG,
+} = require('./constants');
+const { ensureTCPServer } = require('./tcpServer');
 const { logger } = require('../utils/logger');
 const { buildMessageBuffer } = require('../client/utils');
 
@@ -14,7 +19,7 @@ const { buildMessageBuffer } = require('../client/utils');
  * @param {string} tunnelIdHeaderName - Header name to identify the tunnel.
  * @param {number} port - Listening port for state grouping.
  */
-function handleParsedMessage(ws, tunnelId, uuid, type, payload, tunnelIdHeaderName, port) {
+async function handleParsedMessage(ws, tunnelId, uuid, type, payload, tunnelIdHeaderName, port) {
   logger.trace(`handleParsedMessage called. type=${type}, tunnelId=${tunnelId}, uuid=${uuid}`);
 
   if (type === MESSAGE_TYPE_CONFIG) {
@@ -48,19 +53,52 @@ function handleParsedMessage(ws, tunnelId, uuid, type, payload, tunnelIdHeaderNa
       };
 
       const portKey = String(TUNNEL_ENTRY_PORT);
-      if (!state[port][portKey]) {
-        logger.info(`Starting new TCP server on port ${TUNNEL_ENTRY_PORT} for tunnelId=${tunnelId}`);
-        state[port][portKey] = {};
-        state[port][portKey] = {
-          tcpServer: startTCPServer(TUNNEL_ENTRY_PORT, tunnelIdHeaderName, port),
-        };
+      // Check both state and global tcpServers registry
+      logger.debug(`[TCP] Checking existing servers for portKey=${portKey}`);
+      const existingServerInState = state[port]?.[portKey]?.tcpServer;
+      const existingServerInGlobal = state.tcpServers[portKey];
+      logger.debug(`[TCP] existingServerInState=${!!existingServerInState}, existingServerInGlobal=${!!existingServerInGlobal}`);
+      
+      const isServerListening = (existingServerInState && existingServerInState.listening) || 
+                                (existingServerInGlobal && existingServerInGlobal.listening);
+      logger.debug(`[TCP] isServerListening=${isServerListening}`);
+      
+      if (!isServerListening) {
+        // Close any stale TCP server in global registry before creating new one
+        if (state.tcpServers[portKey] && state.tcpServers[portKey].listening) {
+          logger.warn(`[TCP] Closing stale TCP server on port ${TUNNEL_ENTRY_PORT} before creating new one`);
+          state.tcpServers[portKey].close();
+        }
+        
+        // Use ensureTCPServer to handle port cleanup (EADDRINUSE after Node-RED restart)
+        logger.info(`[TCP] Starting new TCP server on port ${TUNNEL_ENTRY_PORT} for tunnelId=${tunnelId}`);
+        
+        try {
+          logger.info(`[TCP] >>> Calling ensureTCPServer for port ${TUNNEL_ENTRY_PORT} <<<`);
+          const tcpServer = await ensureTCPServer(TUNNEL_ENTRY_PORT, tunnelIdHeaderName, port);
+          logger.info(`[TCP] >>> ensureTCPServer returned for port ${TUNNEL_ENTRY_PORT} <<<`);
+          
+          // Store in state per port
+          state[port][portKey] = { tcpServer };
+          logger.debug(`[TCP] Stored in state[${port}][${portKey}]`);
+          
+          // Also register in global tcpServers registry for tracking
+          state.tcpServers[portKey] = tcpServer;
+          logger.info(`[TCP] >>> REGISTERED in global state.tcpServers: port ${portKey}, listening=${tcpServer.listening} <<<`);
+          
+          logger.info(`[TCP] TCP server ready on port ${TUNNEL_ENTRY_PORT} for tunnelId=${tunnelId}`);
+        } catch (err) {
+          logger.error(`[TCP] Failed to create TCP server on port ${TUNNEL_ENTRY_PORT}: ${err.message}`);
+        }
       } else {
-        logger.debug(`TCP server already exists on port ${TUNNEL_ENTRY_PORT}`);
+        logger.debug(`[TCP] TCP server already exists and listening on port ${TUNNEL_ENTRY_PORT}`);
       }
 
       logger.info(`Tunnel [${tunnelId}] established successfully`);
     } catch (error) {
-      logger.error(`Failed to process MESSAGE_TYPE_CONFIG for tunnelId=${tunnelId}: ${error.message}`);
+      logger.error(
+        `Failed to process MESSAGE_TYPE_CONFIG for tunnelId=${tunnelId}: ${error.message}`
+      );
     }
 
     return;
@@ -72,7 +110,7 @@ function handleParsedMessage(ws, tunnelId, uuid, type, payload, tunnelIdHeaderNa
       const pingData = JSON.parse(payload.toString());
       const pongData = JSON.stringify({
         type: 'pong',
-        seq: pingData.seq
+        seq: pingData.seq,
       });
 
       const pongMessage = buildMessageBuffer(tunnelId, uuid, MESSAGE_TYPE_APP_PONG, pongData);

package/server/state.js

@@ -1 +1,5 @@
-module.exports = {};
+module.exports = {
+  // Global registry of all TCP servers created (keyed by TCP port)
+  // This is used to track and close TCP servers that may not be in the main state yet
+  tcpServers: {}
+};

package/server/tcpServer.js

@@ -11,7 +11,11 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
   const wsPortKey = String(websocketPort);
   const tcpPortKey = String(port);
 
-  const server = net.createServer((socket) => {
+  const server = net.createServer({ 
+    // Allow reusing the port quickly after server closes (SO_REUSEADDR)
+    // This helps with Node-RED restarts where old server might be in TIME_WAIT
+    // Note: On some OS, you may also need to handle EADDRINUSE by waiting a bit
+  }, socket => {
     const uuid = uuidv4();
     const uuidBuffer = Buffer.from(uuid);
     let currentTunnelId = null;
@@ -22,7 +26,7 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
     function createParser() {
       const parser = new HTTPParser(HTTPParser.REQUEST);
 
-      parser[HTTPParser.kOnHeadersComplete] = (info) => {
+      parser[HTTPParser.kOnHeadersComplete] = info => {
         const headers = info.headers.reduce((acc, val, i, arr) => {
           if (i % 2 === 0) acc[val.toLowerCase()] = arr[i + 1];
           return acc;
@@ -60,7 +64,9 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
 
         isWebSocket = headers['upgrade']?.toLowerCase() === 'websocket';
 
-        logger.trace(`Sending initial headers (${rawHeaders.length} bytes) to tunnel [${currentTunnelId}]`);
+        logger.trace(
+          `Sending initial headers (${rawHeaders.length} bytes) to tunnel [${currentTunnelId}]`
+        );
         const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, rawHeaders);
         tunnel.ws.send(message);
 
@@ -89,11 +95,13 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
 
     let currentParser = createParser();
 
-    socket.on('data', (chunk) => {
+    socket.on('data', chunk => {
       const tunnel = state[wsPortKey]?.websocketTunnels?.[currentTunnelId];
       if (isWebSocket) {
         if (tunnel?.ws) {
-          logger.trace(`Forwarding WebSocket TCP data (${chunk.length} bytes) for tunnel [${currentTunnelId}]`);
+          logger.trace(
+            `Forwarding WebSocket TCP data (${chunk.length} bytes) for tunnel [${currentTunnelId}]`
+          );
           const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, chunk);
           tunnel.ws.send(message);
         }
@@ -117,26 +125,135 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
     });
 
     socket.on('close', () => {
-      const deleted = delete state[wsPortKey]?.websocketTunnels?.[currentTunnelId]?.tcpConnections?.[uuid];
-      logger.debug(`TCP socket closed [${uuid}] for tunnel [${currentTunnelId}], connection ${deleted ? 'removed' : 'not found'}`);
+      const deleted =
+        delete state[wsPortKey]?.websocketTunnels?.[currentTunnelId]?.tcpConnections?.[uuid];
+      logger.debug(
+        `TCP socket closed [${uuid}] for tunnel [${currentTunnelId}], connection ${deleted ? 'removed' : 'not found'}`
+      );
     });
 
-    socket.on('error', (err) => {
+    socket.on('error', err => {
       logger.error(`Socket error on tunnel [${currentTunnelId}], uuid [${uuid}]:`, err);
       delete state[wsPortKey]?.websocketTunnels?.[currentTunnelId]?.tcpConnections?.[uuid];
     });
   });
 
-  // Store reference
-  state[wsPortKey][tcpPortKey].tcpServer = server;
+  // Note: We don't store the server reference here because the state structure
+  // doesn't exist yet (it's created in messageHandler.js AFTER this function returns).
+  // The caller (messageHandler.js) is responsible for storing the server reference.
 
-  server.listen(port, () => {
-    logger.info(`TCP server listening on port ${port} for websocketPort ${websocketPort}`);
+  // Return a promise that resolves when listening or rejects on error
+  return new Promise((resolve, reject) => {
+    server.on('listening', () => {
+      logger.info(`TCP server listening on port ${port} for websocketPort ${websocketPort}`);
+      resolve(server);
+    });
+
+    server.on('error', err => {
+      logger.error(`TCP server error on port ${port}:`, err);
+      reject(err);
+    });
+
+    // Use reuseAddr to allow quick port reuse after server restart (TIME_WAIT)
+    // This helps with Node-RED restarts where the old server might be in TIME_WAIT state
+    server.listen({
+      port: port,
+      host: '0.0.0.0',
+      reuseAddr: true,
+    }, () => {
+      // The server.address() returns the actual port bound (handles port === 0 case)
+      const addr = server.address();
+      logger.info(`TCP server listening on port ${addr.port} for websocketPort ${websocketPort}`);
+      resolve(server);
+    });
   });
+}
 
-  server.on('error', (err) => {
-    logger.error(`TCP server error on port ${port}:`, err);
+/**
+ * Forcefully kills any process using the specified port by connecting to it
+ * and keeping the connection open briefly, then attempts to bind the port.
+ * This helps release the port from a previous process.
+ * 
+ * @param {number} port - The port to clear
+ * @returns {Promise<boolean>} True if we successfully cleared the port
+ */
+async function forceClosePort(port) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    
+    socket.setTimeout(500);
+    
+    socket.on('connect', () => {
+      // Connected to existing server - destroy it and try to take over
+      socket.destroy();
+      
+      // Now try to bind to the port - this should cause the OS to close the old server
+      const takeover = net.createServer();
+      takeover.on('error', (err) => {
+        if (err.code === 'EADDRINUSE') {
+          // Try again with a different approach - wait a bit
+          setTimeout(() => resolve(true), 100);
+        } else {
+          resolve(false);
+        }
+      });
+      
+      takeover.on('listening', () => {
+        // We got the port! Close our temp server
+        takeover.close(() => resolve(true));
+      });
+      
+      takeover.listen(port);
+    });
+    
+    socket.on('timeout', () => {
+      socket.destroy();
+      resolve(false);
+    });
+    
+    socket.on('error', () => {
+      resolve(false);
+    });
+    
+    socket.connect(port, '127.0.0.1');
   });
 }
 
-module.exports = { startTCPServer };
+/**
+ * Ensures a TCP server is available on the specified port.
+ * If a server is already listening on the port (from a previous process),
+ * it will be forcefully closed before creating a new one.
+ *
+ * @param {number} port - The TCP port to bind to
+ * @param {string} tunnelIdHeaderName - Header name for tunnel identification
+ * @param {number} websocketPort - The WebSocket port (used as state key)
+ * @returns {Promise<net.Server>} The TCP server instance
+ */
+async function ensureTCPServer(port, tunnelIdHeaderName, websocketPort) {
+  const maxRetries = 5;
+  const retryDelay = 300;
+  
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      // Try to start the TCP server
+      return await startTCPServer(port, tunnelIdHeaderName, websocketPort);
+    } catch (err) {
+      if (err.code === 'EADDRINUSE') {
+        logger.warn(`Port ${port} in use (attempt ${attempt}/${maxRetries}), attempting to force close...`);
+        
+        // Try to force close the port
+        await forceClosePort(port);
+        
+        // Wait before retrying
+        await new Promise(resolve => setTimeout(resolve, retryDelay * attempt));
+      } else {
+        throw err;
+      }
+    }
+  }
+  
+  // Last attempt - don't catch, let it fail
+  return startTCPServer(port, tunnelIdHeaderName, websocketPort);
+}
+
+module.exports = { startTCPServer, ensureTCPServer, forceClosePort };

package/server/websocketServer.js

@@ -22,7 +22,9 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
   state[portKey].webSocketServer = new WebSocket.Server({ port, host, path });
 
   state[portKey].webSocketServer.on('listening', () => {
-    logger.info(`WebSocket server listening on port ${port}${host ? ` (host: ${host})` : ''}${path ? `, path: ${path}` : ''}`);
+    logger.info(
+      `WebSocket server listening on port ${port}${host ? ` (host: ${host})` : ''}${path ? `, path: ${path}` : ''}`
+    );
   });
 
   state[portKey].webSocketServer.on('connection', (ws, req) => {
@@ -41,7 +43,9 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
 
     const interval = setInterval(() => {
       if (!ws.isAlive) {
-        logger.warn(`No pong received from client on tunnel [${tunnelId || 'unknown'}], terminating.`);
+        logger.warn(
+          `No pong received from client on tunnel [${tunnelId || 'unknown'}], terminating.`
+        );
         return ws.terminate();
       }
       ws.isAlive = false;
@@ -51,7 +55,7 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
       }
     }, PING_INTERVAL);
 
-    ws.on('message', (chunk) => {
+    ws.on('message', chunk => {
       logger.trace(`Received message chunk: ${chunk.length} bytes`);
       buffer = Buffer.concat([buffer, chunk]);
 
@@ -67,15 +71,22 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
         const type = message.readUInt8(72);
         const payload = message.slice(73);
 
-        logger.trace(`Parsed message - tunnelId: ${messageTunnelId}, uuid: ${uuid}, type: ${type}, payload length: ${payload.length}`);
+        logger.trace(
+          `Parsed message - tunnelId: ${messageTunnelId}, uuid: ${uuid}, type: ${type}, payload length: ${payload.length}`
+        );
 
         // Check for duplicate tunnelId on first message (when tunnelId is not yet set)
         if (!tunnelId && messageTunnelId) {
           const existingTunnel = state[portKey]?.websocketTunnels?.[messageTunnelId];
           if (existingTunnel && existingTunnel.ws && existingTunnel.ws !== ws) {
             // Check if the existing WebSocket is still open
-            if (existingTunnel.ws.readyState === WebSocket.OPEN || existingTunnel.ws.readyState === WebSocket.CONNECTING) {
-              logger.error(`Tunnel [${messageTunnelId}] already exists with an active connection. Rejecting new connection.`);
+            if (
+              existingTunnel.ws.readyState === WebSocket.OPEN ||
+              existingTunnel.ws.readyState === WebSocket.CONNECTING
+            ) {
+              logger.error(
+                `Tunnel [${messageTunnelId}] already exists with an active connection. Rejecting new connection.`
+              );
 
               // Assign tunnelId before closing so cleanup logs the correct value
               tunnelId = messageTunnelId;
@@ -84,7 +95,9 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
               ws.close(1008, `Duplicate tunnelId: ${messageTunnelId}`);
               return;
             } else {
-              logger.info(`Existing tunnel [${messageTunnelId}] has a closed connection. Allowing new connection.`);
+              logger.info(
+                `Existing tunnel [${messageTunnelId}] has a closed connection. Allowing new connection.`
+              );
             }
           }
           tunnelId = messageTunnelId;
@@ -104,7 +117,9 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
           delete state[portKey].websocketTunnels[tunnelId];
           logger.debug(`Removed tunnel [${tunnelId}] from state`);
         } else {
-          logger.debug(`Tunnel [${tunnelId}] not removed - this was a duplicate/rejected connection`);
+          logger.debug(
+            `Tunnel [${tunnelId}] not removed - this was a duplicate/rejected connection`
+          );
         }
       } else {
         logger.debug(`No tunnelId assigned yet, nothing to remove from state`);
@@ -126,17 +141,101 @@ function startWebSocketServer({ port, host, path, tunnelIdHeaderName }) {
       cleanup('close');
     });
 
-    ws.on('error', (err) => {
+    ws.on('error', err => {
       logger.error(`WebSocket error on tunnel [${tunnelId || 'unknown'}]:`, err);
       cleanup('error');
     });
   });
 
-  state[portKey].webSocketServer.on('error', (err) => {
+  state[portKey].webSocketServer.on('error', err => {
     logger.error('WebSocket server error:', err);
   });
 
   return state;
 }
 
-module.exports = { startWebSocketServer };
+/**
+ * Stops the WebSocket tunnel server and cleans up all resources.
+ * @param {number} port - Port of the WebSocket server to stop.
+ * @returns {Promise<void>} Resolves when cleanup is complete.
+ */
+async function stopWebSocketServer(port) {
+  const portKey = String(port);
+  const serverState = state[portKey];
+
+  if (!serverState) {
+    logger.debug(`No server found on port ${port}, nothing to stop`);
+    return;
+  }
+
+  logger.info(`Stopping WebSocket server on port ${port}...`);
+
+  // 1. Close all active WebSocket connections (triggers cleanup for each tunnel)
+  if (serverState.websocketTunnels) {
+    for (const [tunnelId, tunnel] of Object.entries(serverState.websocketTunnels)) {
+      if (tunnel.ws && tunnel.ws.readyState === WebSocket.OPEN) {
+        tunnel.ws.close(1000, 'Server shutting down');
+      }
+    }
+  }
+
+  // 2. Close all TCP servers in per-port state
+  logger.debug(`[CLEANUP] Checking per-port state for TCP servers. Keys: ${Object.keys(serverState).join(', ')}`);
+  for (const [tcpPort, tcpState] of Object.entries(serverState)) {
+    if (tcpPort !== 'webSocketServer' && tcpPort !== 'websocketTunnels' && tcpState?.tcpServer) {
+      logger.info(`[CLEANUP] Closing TCP server in per-port state on port ${tcpPort}`);
+      await new Promise((resolve) => {
+        tcpState.tcpServer.close(() => {
+          logger.info(`[CLEANUP] Closed TCP server on port ${tcpPort}`);
+          resolve();
+        });
+      });
+    }
+  }
+
+  // 2b. Close all TCP servers in global tcpServers registry
+  // This handles TCP servers that may not be in state yet (client not reconnected)
+  // Note: We close ALL servers in registry, not just listening ones, because they may have been
+  // closed in per-port cleanup but still exist in global registry
+  const globalTcpServerCount = Object.keys(state.tcpServers || {}).length;
+  logger.info(`[CLEANUP] Global tcpServers registry has ${globalTcpServerCount} entries: ${Object.keys(state.tcpServers || {}).join(', ')}`);
+  if (state.tcpServers && globalTcpServerCount > 0) {
+    for (const [tcpPort, tcpServer] of Object.entries(state.tcpServers)) {
+      logger.info(`[CLEANUP] Checking global TCP server on port ${tcpPort}: exists=${!!tcpServer}, listening=${tcpServer?.listening}`);
+      // Close any server that exists, regardless of listening state (it may have been closed in per-port cleanup)
+      if (tcpServer) {
+        if (tcpServer.listening) {
+          logger.info(`[CLEANUP] Closing global TCP server on port ${tcpPort} (listening)...`);
+          await new Promise((resolve) => {
+            tcpServer.close(() => {
+              logger.info(`[CLEANUP] Closed global TCP server on port ${tcpPort}`);
+              resolve();
+            });
+          });
+        } else {
+          // Server exists but not listening - it was already closed in per-port cleanup
+          // Just log and clear from registry
+          logger.info(`[CLEANUP] Global TCP server on port ${tcpPort} already closed (listening=false), clearing from registry`);
+        }
+      }
+    }
+    // Clear the global tcpServers registry
+    state.tcpServers = {};
+  }
+
+  // 3. Close the main WebSocket server
+  if (serverState.webSocketServer) {
+    await new Promise((resolve) => {
+      serverState.webSocketServer.close(() => {
+        logger.debug(`Closed WebSocket server on port ${port}`);
+        resolve();
+      });
+    });
+  }
+
+  // 4. Clean up state
+  delete state[portKey];
+  logger.info(`WebSocket server on port ${port} stopped and state cleaned`);
+}
+
+module.exports = { startWebSocketServer, stopWebSocketServer };

package/utils/index.js

@@ -1,8 +1,11 @@
-const { setLogLevel, getLogLevel } = require('./logger.js');
+const { setLogLevel, getLogLevel, setLogContext, getLogContext, logger } = require('./logger.js');
 const { loadConfig } = require('./loadConfig.js');
 
 module.exports = {
   setLogLevel,
   getLogLevel,
+  setLogContext,
+  getLogContext,
+  logger,
   loadConfig,
 };

package/utils/index.mjs

@@ -1,2 +1,2 @@
 import cjsModule from './index.js';
-export const { setLogLevel, getLogLevel, loadConfig } = cjsModule;
+export const { setLogLevel, getLogLevel, loadConfig } = cjsModule;

package/utils/loadConfig.js

@@ -7,7 +7,9 @@ const TOML = require('@iarna/toml');
 
 function loadConfig(customPath) {
   const callerDir = require.main?.path || process.cwd();
-  const configPath = customPath ? path.join(customPath, FILE_CONFIG_NAME) : path.join(callerDir, FILE_CONFIG_NAME);
+  const configPath = customPath
+    ? path.join(customPath, FILE_CONFIG_NAME)
+    : path.join(callerDir, FILE_CONFIG_NAME);
 
   console.log({ configPath });
 
@@ -25,7 +27,9 @@ function loadConfig(customPath) {
       logger.warn(`⚠️ Failed to parse config.toml at ${configPath}: ${err.message}`);
     }
   } else {
-    logger.info(`ℹ️ No config.toml found at: ${configPath}, falling back to environment variables.`);
+    logger.info(
+      `ℹ️ No config.toml found at: ${configPath}, falling back to environment variables.`
+    );
   }
 
   const envConfig = {
@@ -33,7 +37,9 @@ function loadConfig(customPath) {
     wsUrl: process.env.WS_URL,
     targetUrl: process.env.TARGET_URL,
     tunnelEntryUrl: process.env.TUNNEL_ENTRY_URL,
-    tunnelEntryPort: process.env.TUNNEL_ENTRY_PORT ? Number(process.env.TUNNEL_ENTRY_PORT) : undefined,
+    tunnelEntryPort: process.env.TUNNEL_ENTRY_PORT
+      ? Number(process.env.TUNNEL_ENTRY_PORT)
+      : undefined,
     headers: process.env.HEADERS,
     allowInsicureCerts: process.env.ALLOW_INSICURE_CERTS === 'true',
     logLevel: process.env.LOG_LEVEL || 'info',

package/utils/logger.js

@@ -34,12 +34,12 @@ const logger = winston.createLogger({
     new winston.transports.Console({
       format: winston.format.combine(
         winston.format.timestamp(),
-        winston.format.printf((info) => {
+        winston.format.printf(info => {
           const contextPrefix = logContext ? `${logContext} | ` : '';
           // Get the raw level (before colorization)
           const rawLevel = info[Symbol.for('level')] || info.level || 'info';
           // Apply color to level and message separately
-           const colorizer = winston.format.colorize({ colors: customLevels.colors });
+          const colorizer = winston.format.colorize({ colors: customLevels.colors });
           const coloredLevel = colorizer.colorize(rawLevel, rawLevel);
           const coloredMessage = colorizer.colorize(rawLevel, `${contextPrefix}${info.message}`);
           return `[${info.timestamp}] ${coloredLevel}: ${coloredMessage}`;