3.23.1

changelog.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2025-03-05 - 3.23.1 - fix(PortProxy)
+Enhanced connection setup to handle pending data buffering before establishing outgoing connection
+
+- Introduced pending data buffering to address issues with data reception before outgoing connection is fully established.
+- Removed immediate data piping in favor of buffering to ensure complete initial data transfer.
+- Added temporary data handler to collect incoming data during connection setup for precise activity tracking.
+
+## 2025-03-03 - 3.23.0 - feat(documentation)
+Updated documentation with architecture flow diagrams.
+
+- Added detailed architecture and flow diagrams for SmartProxy components.
+- Included HTTPS Reverse Proxy Flow diagram.
+- Integrated Port Proxy with SNI-based Routing diagram.
+- Added Let's Encrypt Certificate Acquisition flow.
+
 ## 2025-03-03 - 3.22.5 - fix(documentation)
 Refactored readme for clarity and consistency, fixed documentation typos
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smartproxy",
-  "version": "3.22.5",
+  "version": "3.23.1",
   "private": false,
   "description": "A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, and dynamic routing with authentication options.",
   "main": "dist_ts/index.js",

readme.md

@@ -2,6 +2,192 @@
 
 A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, and dynamic routing with authentication options.
 
+## Architecture & Flow Diagrams
+
+### Component Architecture
+The diagram below illustrates the main components of SmartProxy and how they interact:
+
+```mermaid
+flowchart TB
+    Client([Client])
+    
+    subgraph "SmartProxy Components"
+        direction TB
+        HTTP80[HTTP Port 80\nSslRedirect]
+        HTTPS443[HTTPS Port 443\nNetworkProxy]
+        PortProxy[TCP Port Proxy\nwith SNI routing]
+        IPTables[IPTablesProxy]
+        Router[ProxyRouter]
+        ACME[Port80Handler\nACME/Let's Encrypt]
+        Certs[(SSL Certificates)]
+    end
+    
+    subgraph "Backend Services"
+        Service1[Service 1]
+        Service2[Service 2]
+        Service3[Service 3]
+    end
+    
+    Client -->|HTTP Request| HTTP80
+    HTTP80 -->|Redirect| Client
+    Client -->|HTTPS Request| HTTPS443
+    Client -->|TLS/TCP| PortProxy
+    
+    HTTPS443 -->|Route Request| Router
+    Router -->|Proxy Request| Service1
+    Router -->|Proxy Request| Service2
+    
+    PortProxy -->|Direct TCP| Service2
+    PortProxy -->|Direct TCP| Service3
+    
+    IPTables -.->|Low-level forwarding| PortProxy
+    
+    HTTP80 -.->|Challenge Response| ACME
+    ACME -.->|Generate/Manage| Certs
+    Certs -.->|Provide TLS Certs| HTTPS443
+    
+    classDef component fill:#f9f,stroke:#333,stroke-width:2px;
+    classDef backend fill:#bbf,stroke:#333,stroke-width:1px;
+    classDef client fill:#dfd,stroke:#333,stroke-width:2px;
+    
+    class Client client;
+    class HTTP80,HTTPS443,PortProxy,IPTables,Router,ACME component;
+    class Service1,Service2,Service3 backend;
+```
+
+### HTTPS Reverse Proxy Flow
+This diagram shows how HTTPS requests are handled and proxied to backend services:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant NetworkProxy
+    participant ProxyRouter
+    participant Backend
+    
+    Client->>NetworkProxy: HTTPS Request
+    
+    Note over NetworkProxy: TLS Termination
+    
+    NetworkProxy->>ProxyRouter: Route Request
+    ProxyRouter->>ProxyRouter: Match hostname to config
+    
+    alt Authentication Required
+        NetworkProxy->>Client: Request Authentication
+        Client->>NetworkProxy: Send Credentials
+        NetworkProxy->>NetworkProxy: Validate Credentials
+    end
+    
+    NetworkProxy->>Backend: Forward Request
+    Backend->>NetworkProxy: Response
+    
+    Note over NetworkProxy: Add Default Headers
+    
+    NetworkProxy->>Client: Forward Response
+    
+    alt WebSocket Request
+        Client->>NetworkProxy: Upgrade to WebSocket
+        NetworkProxy->>Backend: Upgrade to WebSocket
+        loop WebSocket Active
+            Client->>NetworkProxy: WebSocket Message
+            NetworkProxy->>Backend: Forward Message
+            Backend->>NetworkProxy: WebSocket Message
+            NetworkProxy->>Client: Forward Message
+            NetworkProxy-->>NetworkProxy: Heartbeat Check
+        end
+    end
+```
+
+### Port Proxy with SNI-based Routing
+This diagram illustrates how TCP connections with SNI (Server Name Indication) are processed and forwarded:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant PortProxy
+    participant Backend
+    
+    Client->>PortProxy: TLS Connection
+    
+    alt SNI Enabled
+        PortProxy->>Client: Accept Connection
+        Client->>PortProxy: TLS ClientHello with SNI
+        PortProxy->>PortProxy: Extract SNI Hostname
+        PortProxy->>PortProxy: Match Domain Config
+        PortProxy->>PortProxy: Validate Client IP
+        
+        alt IP Allowed
+            PortProxy->>Backend: Forward Connection
+            Note over PortProxy,Backend: Bidirectional Data Flow
+        else IP Rejected
+            PortProxy->>Client: Close Connection
+        end
+    else Port-based Routing
+        PortProxy->>PortProxy: Match Port Range
+        PortProxy->>PortProxy: Find Domain Config
+        PortProxy->>PortProxy: Validate Client IP
+        
+        alt IP Allowed
+            PortProxy->>Backend: Forward Connection
+            Note over PortProxy,Backend: Bidirectional Data Flow
+        else IP Rejected
+            PortProxy->>Client: Close Connection
+        end
+    end
+    
+    loop Connection Active
+        PortProxy-->>PortProxy: Monitor Activity
+        PortProxy-->>PortProxy: Check Max Lifetime
+        alt Inactivity or Max Lifetime Exceeded
+            PortProxy->>Client: Close Connection
+            PortProxy->>Backend: Close Connection
+        end
+    end
+```
+
+### Let's Encrypt Certificate Acquisition
+This diagram shows how certificates are automatically acquired through the ACME protocol:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Port80Handler
+    participant ACME as Let's Encrypt ACME
+    participant NetworkProxy
+    
+    Client->>Port80Handler: HTTP Request for domain
+    
+    alt Certificate Exists
+        Port80Handler->>Client: Redirect to HTTPS
+    else No Certificate
+        Port80Handler->>Port80Handler: Mark domain as obtaining cert
+        Port80Handler->>ACME: Create account & new order
+        ACME->>Port80Handler: Challenge information
+        
+        Port80Handler->>Port80Handler: Store challenge token & key authorization
+        
+        ACME->>Port80Handler: HTTP-01 Challenge Request
+        Port80Handler->>ACME: Challenge Response
+        
+        ACME->>ACME: Validate domain ownership
+        ACME->>Port80Handler: Challenge validated
+        
+        Port80Handler->>Port80Handler: Generate CSR
+        Port80Handler->>ACME: Submit CSR
+        ACME->>Port80Handler: Issue Certificate
+        
+        Port80Handler->>Port80Handler: Store certificate & private key
+        Port80Handler->>Port80Handler: Mark certificate as obtained
+        
+        Note over Port80Handler,NetworkProxy: Certificate available for use
+        
+        Client->>Port80Handler: Another HTTP Request
+        Port80Handler->>Client: Redirect to HTTPS
+        Client->>NetworkProxy: HTTPS Request
+        Note over NetworkProxy: Uses new certificate
+    end
+```
+
 ## Features
 
 - **HTTPS Reverse Proxy** - Route traffic to backend services based on hostname with TLS termination

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartproxy',
-  version: '3.22.5',
+  version: '3.23.1',
   description: 'A powerful proxy package that effectively handles high traffic, with features such as SSL/TLS support, port proxying, WebSocket handling, and dynamic routing with authentication options.'
 }

ts/classes.portproxy.ts

@@ -99,6 +99,7 @@ interface IConnectionRecord {
   connectionClosed: boolean;        // Flag to prevent multiple cleanup attempts
   cleanupTimer?: NodeJS.Timeout;    // Timer for max lifetime/inactivity
   lastActivity: number;             // Last activity timestamp for inactivity detection
+  pendingData: Buffer[];            // Buffer to hold data during connection setup
 }
 
 // Helper: Check if a port falls within any of the given port ranges
@@ -257,7 +258,8 @@ export class PortProxy {
         outgoing: null,
         incomingStartTime: Date.now(),
         lastActivity: Date.now(),
-        connectionClosed: false
+        connectionClosed: false,
+        pendingData: [] // Initialize buffer for pending data
       };
       this.connectionRecords.set(connectionId, connectionRecord);
       
@@ -391,29 +393,32 @@ export class PortProxy {
           connectionOptions.localAddress = remoteIP.replace('::ffff:', '');
         }
 
-        // Create the target socket and immediately set up data piping
+        // Temporary handler to collect data during connection setup
+        const tempDataHandler = (chunk: Buffer) => {
+          connectionRecord.pendingData.push(Buffer.from(chunk));
+          this.updateActivity(connectionRecord);
+        };
+
+        // Add the temp handler to capture all incoming data during connection setup
+        socket.on('data', tempDataHandler);
+
+        // Add initial chunk to pending data if present
+        if (initialChunk) {
+          connectionRecord.pendingData.push(Buffer.from(initialChunk));
+        }
+
+        // Create the target socket but don't set up piping immediately
         const targetSocket = plugins.net.connect(connectionOptions);
         connectionRecord.outgoing = targetSocket;
         connectionRecord.outgoingStartTime = Date.now();
         
-        // Set up the pipe immediately to ensure data flows without delay
-        if (initialChunk) {
-          socket.unshift(initialChunk);
-        }
-        
-        socket.pipe(targetSocket);
-        targetSocket.pipe(socket);
-        
-        console.log(
-          `Connection established: ${remoteIP} -> ${targetHost}:${connectionOptions.port}` +
-          `${serverName ? ` (SNI: ${serverName})` : forcedDomain ? ` (Port-based for domain: ${forcedDomain.domains.join(', ')})` : ''}`
-        );
-
-        // Add appropriate handlers for connection management
+        // Setup error handlers immediately
         socket.on('error', handleError('incoming'));
         targetSocket.on('error', handleError('outgoing'));
         socket.on('close', handleClose('incoming'));
         targetSocket.on('close', handleClose('outgoing'));
+        
+        // Handle timeouts
         socket.on('timeout', () => {
           console.log(`Timeout on incoming side from ${remoteIP}`);
           if (incomingTerminationReason === null) {
@@ -435,13 +440,72 @@ export class PortProxy {
         socket.setTimeout(120000);
         targetSocket.setTimeout(120000);
         
-        // Update activity for both sockets
-        socket.on('data', () => {
-          connectionRecord.lastActivity = Date.now();
-        });
-        
-        targetSocket.on('data', () => {
-          connectionRecord.lastActivity = Date.now();
+        // Wait for the outgoing connection to be ready before setting up piping
+        targetSocket.once('connect', () => {
+          // Remove temporary data handler
+          socket.removeListener('data', tempDataHandler);
+          
+          // Flush all pending data to target
+          if (connectionRecord.pendingData.length > 0) {
+            const combinedData = Buffer.concat(connectionRecord.pendingData);
+            targetSocket.write(combinedData, (err) => {
+              if (err) {
+                console.log(`Error writing pending data to target: ${err.message}`);
+                return initiateCleanupOnce('write_error');
+              }
+              
+              // Now set up piping for future data
+              socket.pipe(targetSocket);
+              targetSocket.pipe(socket);
+              
+              console.log(
+                `Connection established: ${remoteIP} -> ${targetHost}:${connectionOptions.port}` +
+                `${serverName ? ` (SNI: ${serverName})` : forcedDomain ? ` (Port-based for domain: ${forcedDomain.domains.join(', ')})` : ''}`
+              );
+            });
+          } else {
+            // No pending data, so just set up piping
+            socket.pipe(targetSocket);
+            targetSocket.pipe(socket);
+            
+            console.log(
+              `Connection established: ${remoteIP} -> ${targetHost}:${connectionOptions.port}` +
+              `${serverName ? ` (SNI: ${serverName})` : forcedDomain ? ` (Port-based for domain: ${forcedDomain.domains.join(', ')})` : ''}`
+            );
+          }
+          
+          // Clear the buffer now that we've processed it
+          connectionRecord.pendingData = [];
+          
+          // Set up activity tracking
+          socket.on('data', () => {
+            connectionRecord.lastActivity = Date.now();
+          });
+          
+          targetSocket.on('data', () => {
+            connectionRecord.lastActivity = Date.now();
+          });
+          
+          // Add the renegotiation listener (we don't need setImmediate here anymore
+          // since we're already in the connect callback)
+          if (serverName) {
+            socket.on('data', (renegChunk: Buffer) => {
+              if (renegChunk.length > 0 && renegChunk.readUInt8(0) === 22) {
+                try {
+                  // Try to extract SNI from potential renegotiation
+                  const newSNI = extractSNI(renegChunk);
+                  if (newSNI && newSNI !== connectionRecord.lockedDomain) {
+                    console.log(`Rehandshake detected with different SNI: ${newSNI} vs locked ${connectionRecord.lockedDomain}. Terminating connection.`);
+                    initiateCleanupOnce('sni_mismatch');
+                  } else if (newSNI) {
+                    console.log(`Rehandshake detected with same SNI: ${newSNI}. Allowing.`);
+                  }
+                } catch (err) {
+                  console.log(`Error processing potential renegotiation: ${err}. Allowing connection to continue.`);
+                }
+              }
+            });
+          }
         });
 
         // Initialize a cleanup timer for max connection lifetime
@@ -514,27 +578,6 @@ export class PortProxy {
           connectionRecord.lockedDomain = serverName;
           console.log(`Received connection from ${remoteIP} with SNI: ${serverName}`);
           
-          // Delay adding the renegotiation listener until the next tick,
-          // so the initial ClientHello is not reprocessed.
-          setImmediate(() => {
-            socket.on('data', (renegChunk: Buffer) => {
-              if (renegChunk.length > 0 && renegChunk.readUInt8(0) === 22) {
-                try {
-                  // Try to extract SNI from potential renegotiation
-                  const newSNI = extractSNI(renegChunk);
-                  if (newSNI && newSNI !== connectionRecord.lockedDomain) {
-                    console.log(`Rehandshake detected with different SNI: ${newSNI} vs locked ${connectionRecord.lockedDomain}. Terminating connection.`);
-                    initiateCleanupOnce('sni_mismatch');
-                  } else if (newSNI) {
-                    console.log(`Rehandshake detected with same SNI: ${newSNI}. Allowing.`);
-                  }
-                } catch (err) {
-                  console.log(`Error processing potential renegotiation: ${err}. Allowing connection to continue.`);
-                }
-              }
-            });
-          });
-          
           setupConnection(serverName, chunk);
         });
       } else {