@remotelinker/reverse-ws-tunnel 1.0.7 → 1.0.9

package/README.md

@@ -30,6 +30,20 @@ Reverse WebSocket Tunnel is a library that enables you to expose local services
 
 ---
 
+## ✨ v1.0.9 - What's New
+
+### 🐛 Bug Fixes
+- **Message Format Standardization**: Fixed inconsistent message formats between server components
+- **Ping/Pong Reliability**: Resolved issues with application-level heartbeat failing during data transfer
+- **Connection Stability**: Improved connection handling and reduced timeout issues
+
+### 🔧 Technical Improvements
+- **Unified Message Protocol**: All server messages now use consistent `buildMessageBuffer` format
+- **Simplified Client Architecture**: Removed hybrid parsing logic for better maintainability
+- **Enhanced Buffer Management**: Improved message buffering and parsing reliability
+
+---
+
 ## 📦 Installation
 
 ```bash

package/client/tunnelClient.js

@@ -9,12 +9,17 @@ 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;
+const MESSAGE_TYPE_APP_PONG = 0x04;
 const clients = {};
 const PING_INTERVAL = 30 * 1000; //30s
 const PONG_WAIT = 5 * 1000; //5s
+const APP_PING_INTERVAL = 20 * 1000; // 20 secondi
+const HEALTH_TIMEOUT = 45 * 1000; // 45 secondi sliding window
+const RECONNECT_BACKOFF = [1000, 2000, 5000, 10000, 30000]; // Backoff progressivo
 
 /**
- * Starts the WebSocket tunnel client.
+ * Starts WebSocket tunnel client.
  * @param {Object} config - Configuration for tunnel.
  */
 function connectWebSocket(config) {
@@ -23,7 +28,12 @@ function connectWebSocket(config) {
   const eventEmitter = new EventEmitter();
   let ws;
   let pingInterval;
+  let appPingInterval;
+  let healthMonitor;
   let isClosed = false;
+  let reconnectAttempt = 0;
+  let pingSeq = 0;
+  let lastPongTs = Date.now();
 
   if (!tunnelId) {
     throw new Error(`Missing mandatory tunnelId`);
@@ -49,6 +59,10 @@ function connectWebSocket(config) {
       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 });
+
       const uuid = uuidv4();
       const payload = {
         TARGET_URL: targetUrl,
@@ -64,29 +78,62 @@ function connectWebSocket(config) {
       ws.send(message);
     });
 
+    let messageBuffer = Buffer.alloc(0);
+    
     ws.on('message', (data) => {
-      const uuid = data.slice(0, 36).toString();
-      const type = data.readUInt8(36);
-      const payload = data.slice(37);
+      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}`);
+          break;
+        }
+
+        const message = messageBuffer.slice(4, 4 + length);
+        messageBuffer = messageBuffer.slice(4 + length);
+
+        const messageTunnelId = message.slice(0, 36).toString();
+        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}`);
+        logger.trace(`Received WS message for uuid=${uuid}, type=${type}, length=${payload.length}`);
 
-      if (type === MESSAGE_TYPE_DATA) {
-        if (payload.toString() === 'CLOSE') {
-          logger.debug(`Received CLOSE for uuid=${uuid}`);
-          if (clients[uuid]) {
-            clients[uuid].end();
+        if (type === MESSAGE_TYPE_DATA) {
+          if (payload.toString() === 'CLOSE') {
+            logger.debug(`Received CLOSE for uuid=${uuid}`);
+            if (clients[uuid]) {
+              clients[uuid].end();
+            }
+            return;
           }
-          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}`);
+            client.once('drain', () => {
+              logger.info(`TCP socket drained for uuid=${uuid}`);
+            });
+          }
+          return;
 
-        if (!client.write(payload)) {
-          logger.debug(`Backpressure on TCP socket for uuid=${uuid}`);
-          client.once('drain', () => {
-            logger.info(`TCP socket drained for uuid=${uuid}`);
-          });
+        } 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();
+              logger.trace(`App pong received: seq=${pongData.seq}`);
+            } else {
+              logger.debug(`Ignoring old pong: seq=${pongData.seq}`);
+            }
+          } catch (err) {
+            logger.error(`Invalid app pong format: ${err.message}`);
+          }
+          return;
         }
       }
     });
@@ -95,6 +142,8 @@ function connectWebSocket(config) {
       logger.warn('WebSocket connection closed. Cleaning up clients.');
       eventEmitter.emit('disconnected');
       clearInterval(pingInterval);
+      clearInterval(appPingInterval);
+      clearInterval(healthMonitor);
 
       for (const uuid in clients) {
         logger.debug(`Closing TCP connection for uuid=${uuid}`);
@@ -104,8 +153,12 @@ function connectWebSocket(config) {
       }
 
       if (!isClosed && autoReconnect) {
-        logger.info(`Reconnecting in ${RECONNECT_INTERVAL / 1000}s...`);
-        setTimeout(connect, RECONNECT_INTERVAL);
+        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);
+          connect();
+        }, delay);
       }
     });
 
@@ -151,7 +204,7 @@ function heartBeat(ws) {
 }
 
 /**
- * Creates a TCP connection to the target service.
+ * Creates a TCP connection to target service.
  */
 function createTcpClient(targetUrl, targetPort, ws, tunnelId, uuid) {
   const hostname = new URL(targetUrl).hostname;
@@ -184,6 +237,42 @@ function createTcpClient(targetUrl, targetPort, ws, tunnelId, uuid) {
   return client;
 }
 
+/**
+ * Starts the application-level heartbeat (ping every 20 seconds)
+ */
+function startAppHeartbeat(ws, tunnelId, pingState) {
+  return setInterval(() => {
+    if (ws.readyState === WebSocket.OPEN) {
+      pingState.incPingSeq();
+      const currentPingSeq = pingState.pingSeq();
+      const pingData = JSON.stringify({
+        type: 'ping',
+        seq: currentPingSeq,
+        ts: Date.now()
+      });
+
+      const message = buildMessageBuffer(tunnelId, uuidv4(), MESSAGE_TYPE_APP_PING, pingData);
+      ws.send(message);
+
+      logger.trace(`App ping sent: seq=${currentPingSeq}`);
+    }
+  }, APP_PING_INTERVAL);
+}
+
+/**
+ * Starts health monitoring with sliding window timeout
+ */
+function startHealthMonitor(ws, tunnelId, pongState) {
+  return setInterval(() => {
+    const now = Date.now();
+    const currentLastPongTs = pongState.lastPongTs();
+    if (now - currentLastPongTs > HEALTH_TIMEOUT) {
+      logger.warn(`Health timeout exceeded (${HEALTH_TIMEOUT}ms) - terminating connection`);
+      ws.terminate();
+    }
+  }, 5000); // Check every 5 seconds
+}
+
 function resetClients() { // for testing
   for (const key in clients) {
     delete clients[key];
@@ -193,4 +282,4 @@ function resetClients() { // for testing
 module.exports = {
   connectWebSocket,
   resetClients, // for testing
-};
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remotelinker/reverse-ws-tunnel",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "A Node.js library for creating secure reverse tunnels over WebSocket connections",
   "main": "index.cjs",
   "types": "types/index.d.ts",

package/server/constants.js

@@ -4,4 +4,6 @@ module.exports = {
   RECONNECT_INTERVAL: 1000 * 5,
   MESSAGE_TYPE_CONFIG: 0x01,
   MESSAGE_TYPE_DATA: 0x02,
+  MESSAGE_TYPE_APP_PING: 0x03,
+  MESSAGE_TYPE_APP_PONG: 0x04,
 };

package/server/messageHandler.js

@@ -1,7 +1,8 @@
 const state = require('./state');
-const { MESSAGE_TYPE_CONFIG, MESSAGE_TYPE_DATA } = require('./constants');
+const { MESSAGE_TYPE_CONFIG, MESSAGE_TYPE_DATA, MESSAGE_TYPE_APP_PING, MESSAGE_TYPE_APP_PONG } = require('./constants');
 const { startTCPServer } = require('./tcpServer');
 const { logger } = require('../utils/logger');
+const { buildMessageBuffer } = require('../client/utils');
 
 /**
  * Handles a parsed WebSocket message.
@@ -65,6 +66,25 @@ function handleParsedMessage(ws, tunnelId, uuid, type, payload, tunnelIdHeaderNa
     return;
   }
 
+  // Handle MESSAGE_TYPE_APP_PING
+  if (type === MESSAGE_TYPE_APP_PING) {
+    try {
+      const pingData = JSON.parse(payload.toString());
+      const pongData = JSON.stringify({
+        type: 'pong',
+        seq: pingData.seq
+      });
+
+      const pongMessage = buildMessageBuffer(tunnelId, uuid, MESSAGE_TYPE_APP_PONG, pongData);
+      ws.send(pongMessage);
+
+      logger.trace(`App pong sent: seq=${pingData.seq} for tunnel ${tunnelId}`);
+    } catch (err) {
+      logger.error(`Invalid app ping format for tunnel ${tunnelId}: ${err.message}`);
+    }
+    return;
+  }
+
   // Handle MESSAGE_TYPE_DATA
   const tunnel = state[port]?.websocketTunnels?.[tunnelId];
 

package/server/tcpServer.js

@@ -5,6 +5,7 @@ const { HTTPParser, methods } = require('http-parser-js');
 const state = require('./state');
 const { MESSAGE_TYPE_DATA } = require('./constants');
 const { logger } = require('../utils/logger');
+const { buildMessageBuffer } = require('../client/utils');
 
 function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
   const wsPortKey = String(websocketPort);
@@ -60,7 +61,8 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
         isWebSocket = headers['upgrade']?.toLowerCase() === 'websocket';
 
         logger.trace(`Sending initial headers (${rawHeaders.length} bytes) to tunnel [${currentTunnelId}]`);
-        tunnel.ws.send(Buffer.concat([uuidBuffer, Buffer.from([MESSAGE_TYPE_DATA]), Buffer.from(rawHeaders)]));
+        const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, rawHeaders);
+        tunnel.ws.send(message);
 
         if (isWebSocket) parser.close();
       };
@@ -70,7 +72,8 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
         if (tunnel?.ws && !isWebSocket) {
           const body = chunk.slice(offset, offset + length);
           logger.trace(`Forwarding body (${body.length} bytes) to tunnel [${currentTunnelId}]`);
-          tunnel.ws.send(Buffer.concat([uuidBuffer, Buffer.from([MESSAGE_TYPE_DATA]), body]));
+          const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, body);
+          tunnel.ws.send(message);
         }
       };
 
@@ -91,7 +94,8 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
       if (isWebSocket) {
         if (tunnel?.ws) {
           logger.trace(`Forwarding WebSocket TCP data (${chunk.length} bytes) for tunnel [${currentTunnelId}]`);
-          tunnel.ws.send(Buffer.concat([uuidBuffer, Buffer.from([MESSAGE_TYPE_DATA]), chunk]));
+          const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, chunk);
+          tunnel.ws.send(message);
         }
       } else {
         try {
@@ -107,7 +111,8 @@ function startTCPServer(port, tunnelIdHeaderName, websocketPort) {
       const tunnel = state[wsPortKey]?.websocketTunnels?.[currentTunnelId];
       if (tunnel?.ws) {
         logger.debug(`TCP socket end for tunnel [${currentTunnelId}] (uuid: ${uuid})`);
-        tunnel.ws.send(Buffer.concat([uuidBuffer, Buffer.from([MESSAGE_TYPE_DATA]), Buffer.from('CLOSE')]));
+        const message = buildMessageBuffer(currentTunnelId, uuid, MESSAGE_TYPE_DATA, 'CLOSE');
+        tunnel.ws.send(message);
       }
     });