@push.rocks/smartproxy 19.6.2 → 19.6.7

package/readme.md

@@ -665,6 +665,661 @@ redirect: {
 }
 ```
 
+## Forwarding Modes Guide
+
+This section provides a comprehensive reference for all forwarding modes available in SmartProxy, helping you choose the right configuration for your use case.
+
+### Visual Overview
+
+```mermaid
+graph TD
+    A[Incoming Traffic] --> B{Action Type?}
+    
+    B -->|forward| C{TLS Mode?}
+    B -->|socket-handler| D[Custom Handler]
+    
+    C -->|terminate| E[Decrypt TLS]
+    C -->|passthrough| F[Forward Encrypted]
+    C -->|terminate-and-reencrypt| G[Decrypt & Re-encrypt]
+    C -->|none/HTTP| H[Forward HTTP]
+    
+    E --> I{Engine?}
+    F --> I
+    G --> I
+    H --> I
+    
+    I -->|node| J[Node.js Processing]
+    I -->|nftables| K[Kernel NAT]
+    
+    J --> L[Backend]
+    K --> L
+    D --> M[Custom Logic]
+    
+    style B fill:#f9f,stroke:#333,stroke-width:2px
+    style C fill:#bbf,stroke:#333,stroke-width:2px
+    style I fill:#bfb,stroke:#333,stroke-width:2px
+```
+
+### Overview
+
+SmartProxy offers flexible traffic forwarding through combinations of:
+- **Action Types**: How to handle matched traffic
+- **TLS Modes**: How to handle HTTPS/TLS connections
+- **Forwarding Engines**: Where packet processing occurs
+
+### Quick Reference
+
+#### Modern Route-Based Configuration
+
+| Use Case | Action Type | TLS Mode | Engine | Performance | Security |
+|----------|------------|----------|---------|-------------|----------|
+| HTTP web server | `forward` | N/A | `node` | Good | Basic |
+| HTTPS web server (inspect traffic) | `forward` | `terminate` | `node` | Good | Full inspection |
+| HTTPS passthrough (no inspection) | `forward` | `passthrough` | `node` | Better | End-to-end encryption |
+| HTTPS gateway (re-encrypt to backend) | `forward` | `terminate-and-reencrypt` | `node` | Moderate | Full control |
+| High-performance TCP forwarding | `forward` | `passthrough` | `nftables` | Excellent | Basic |
+| Custom protocol handling | `socket-handler` | N/A | `node` | Varies | Custom |
+
+#### Legacy Forwarding Types (Deprecated)
+
+| Legacy Type | Modern Equivalent |
+|------------|------------------|
+| `http-only` | `action.type: 'forward'` with port 80 |
+| `https-passthrough` | `action.type: 'forward'` + `tls.mode: 'passthrough'` |
+| `https-terminate-to-http` | `action.type: 'forward'` + `tls.mode: 'terminate'` |
+| `https-terminate-to-https` | `action.type: 'forward'` + `tls.mode: 'terminate-and-reencrypt'` |
+
+### Forwarding Mode Categories
+
+#### 1. Action Types
+
+##### Forward Action
+Routes traffic to a backend server. This is the most common action type.
+
+```typescript
+{
+  action: {
+    type: 'forward',
+    target: {
+      host: 'backend-server',
+      port: 8080
+    }
+  }
+}
+```
+
+##### Socket Handler Action
+Provides custom handling for any TCP protocol. Used for specialized protocols or custom logic.
+
+```typescript
+{
+  action: {
+    type: 'socket-handler',
+    socketHandler: async (socket, context) => {
+      // Custom protocol implementation
+    }
+  }
+}
+```
+
+#### 2. TLS Modes (for Forward Action)
+
+##### Passthrough Mode
+- **What**: Forwards encrypted TLS traffic without decryption
+- **When**: Backend handles its own TLS termination
+- **Pros**: Maximum performance, true end-to-end encryption
+- **Cons**: Cannot inspect or modify HTTPS traffic
+
+```mermaid
+graph LR
+    Client -->|TLS| SmartProxy
+    SmartProxy -->|TLS| Backend
+    style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+##### Terminate Mode
+- **What**: Decrypts TLS, forwards as plain HTTP
+- **When**: Backend doesn't support HTTPS or you need to inspect traffic
+- **Pros**: Can modify headers, inspect content, add security headers
+- **Cons**: Backend connection is unencrypted
+
+```mermaid
+graph LR
+    Client -->|TLS| SmartProxy
+    SmartProxy -->|HTTP| Backend
+    style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+##### Terminate-and-Reencrypt Mode
+- **What**: Decrypts TLS, then creates new TLS connection to backend
+- **When**: Need traffic inspection but backend requires HTTPS
+- **Pros**: Full control while maintaining backend security
+- **Cons**: Higher CPU usage, increased latency
+
+```mermaid
+graph LR
+    Client -->|TLS| SmartProxy
+    SmartProxy -->|New TLS| Backend
+    style SmartProxy fill:#f9f,stroke:#333,stroke-width:2px
+```
+
+#### 3. Forwarding Engines
+
+##### Node.js Engine (Default)
+- **Processing**: Application-level in Node.js event loop
+- **Features**: Full protocol support, header manipulation, WebSockets
+- **Performance**: Good for most use cases
+- **Use when**: You need application-layer features
+
+##### NFTables Engine
+- **Processing**: Kernel-level packet forwarding
+- **Features**: Basic NAT, minimal overhead
+- **Performance**: Excellent, near wire-speed
+- **Use when**: Maximum performance is critical
+- **Requirements**: Linux, root permissions, NFTables installed
+
+### Detailed Mode Explanations
+
+#### HTTP Forwarding (Port 80)
+
+Simple HTTP forwarding without encryption:
+
+```typescript
+{
+  match: { ports: 80, domains: 'example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'localhost', port: 8080 }
+  }
+}
+```
+
+**Data Flow**: Client → SmartProxy (HTTP) → Backend (HTTP)
+
+#### HTTPS with TLS Termination
+
+Decrypt HTTPS and forward as HTTP:
+
+```typescript
+{
+  match: { ports: 443, domains: 'secure.example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'localhost', port: 8080 },
+    tls: {
+      mode: 'terminate',
+      certificate: 'auto'  // Use Let's Encrypt
+    }
+  }
+}
+```
+
+**Data Flow**: Client → SmartProxy (HTTPS decrypt) → Backend (HTTP)
+
+#### HTTPS Passthrough
+
+Forward encrypted traffic without decryption:
+
+```typescript
+{
+  match: { ports: 443, domains: 'legacy.example.com' },
+  action: {
+    type: 'forward',
+    target: { host: '192.168.1.10', port: 443 },
+    tls: {
+      mode: 'passthrough'
+    }
+  }
+}
+```
+
+**Data Flow**: Client → SmartProxy (TLS forwarding) → Backend (Original TLS)
+
+#### HTTPS Gateway (Terminate and Re-encrypt)
+
+Decrypt, inspect, then re-encrypt to backend:
+
+```typescript
+{
+  match: { ports: 443, domains: 'api.example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'api-backend', port: 443 },
+    tls: {
+      mode: 'terminate-and-reencrypt',
+      certificate: 'auto'
+    },
+    advanced: {
+      headers: {
+        'X-Forwarded-Proto': 'https',
+        'X-Real-IP': '{clientIp}'
+      }
+    }
+  }
+}
+```
+
+**Data Flow**: Client → SmartProxy (HTTPS decrypt) → SmartProxy (New HTTPS) → Backend
+
+#### High-Performance NFTables Forwarding
+
+Kernel-level forwarding for maximum performance:
+
+```typescript
+{
+  match: { ports: 443, domains: 'fast.example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'backend', port: 443 },
+    tls: { mode: 'passthrough' },
+    forwardingEngine: 'nftables',
+    nftables: {
+      preserveSourceIP: true,
+      maxRate: '10gbps'
+    }
+  }
+}
+```
+
+**Data Flow**: Client → Kernel (NFTables NAT) → Backend
+
+#### Custom Socket Handler
+
+Handle custom protocols or implement specialized logic:
+
+```typescript
+{
+  match: { ports: 9000, domains: 'custom.example.com' },
+  action: {
+    type: 'socket-handler',
+    socketHandler: async (socket, context) => {
+      console.log(`Connection from ${context.clientIp}`);
+      
+      socket.write('Welcome to custom protocol server\n');
+      
+      socket.on('data', (data) => {
+        // Handle custom protocol
+        const response = processCustomProtocol(data);
+        socket.write(response);
+      });
+    }
+  }
+}
+```
+
+### Decision Guide
+
+#### Choose HTTP Forwarding When:
+- Backend only supports HTTP
+- Internal services not exposed to internet
+- Development/testing environments
+
+#### Choose HTTPS Termination When:
+- Need to inspect/modify HTTP traffic
+- Backend doesn't support HTTPS
+- Want to add security headers
+- Need to cache responses
+
+#### Choose HTTPS Passthrough When:
+- Backend manages its own certificates
+- Need true end-to-end encryption
+- Compliance requires no MITM
+- WebSocket connections to backend
+
+#### Choose HTTPS Terminate-and-Reencrypt When:
+- Need traffic inspection AND backend requires HTTPS
+- API gateway scenarios
+- Adding authentication layers
+- Different certificates for client/backend
+
+#### Choose NFTables Engine When:
+- Handling 1Gbps+ traffic
+- Thousands of concurrent connections
+- Minimal latency is critical
+- Don't need application-layer features
+
+#### Choose Socket Handler When:
+- Implementing custom protocols
+- Need fine-grained connection control
+- Building protocol adapters
+- Special authentication flows
+
+### Complete Examples
+
+#### Example 1: Complete Web Application
+
+```typescript
+const proxy = new SmartProxy({
+  routes: [
+    // HTTP to HTTPS redirect
+    {
+      match: { ports: 80, domains: ['example.com', 'www.example.com'] },
+      action: {
+        type: 'socket-handler',
+        socketHandler: SocketHandlers.httpRedirect('https://{domain}{path}')
+      }
+    },
+    
+    // Main website with TLS termination
+    {
+      match: { ports: 443, domains: ['example.com', 'www.example.com'] },
+      action: {
+        type: 'forward',
+        target: { host: 'web-backend', port: 3000 },
+        tls: {
+          mode: 'terminate',
+          certificate: 'auto'
+        },
+        websocket: { enabled: true }
+      }
+    },
+    
+    // API with re-encryption
+    {
+      match: { ports: 443, domains: 'api.example.com' },
+      action: {
+        type: 'forward',
+        target: { host: 'api-backend', port: 443 },
+        tls: {
+          mode: 'terminate-and-reencrypt',
+          certificate: 'auto'
+        }
+      },
+      security: {
+        ipAllowList: ['10.0.0.0/8'],
+        rateLimit: {
+          enabled: true,
+          maxRequests: 100,
+          window: 60
+        }
+      }
+    }
+  ]
+});
+```
+
+#### Example 2: Multi-Mode Proxy Setup
+
+```typescript
+const proxy = new SmartProxy({
+  routes: [
+    // Legacy app with passthrough
+    {
+      match: { ports: 443, domains: 'legacy.example.com' },
+      action: {
+        type: 'forward',
+        target: { host: 'legacy-server', port: 443 },
+        tls: { mode: 'passthrough' }
+      }
+    },
+    
+    // High-performance streaming with NFTables
+    {
+      match: { ports: 8080, domains: 'stream.example.com' },
+      action: {
+        type: 'forward',
+        target: { host: 'stream-backend', port: 8080 },
+        forwardingEngine: 'nftables',
+        nftables: {
+          protocol: 'tcp',
+          preserveSourceIP: true
+        }
+      }
+    },
+    
+    // Custom protocol handler
+    {
+      match: { ports: 9999 },
+      action: {
+        type: 'socket-handler',
+        socketHandler: SocketHandlers.proxy('custom-backend', 9999)
+      }
+    }
+  ]
+});
+```
+
+### Performance Considerations
+
+#### Node.js Engine Performance
+
+| Metric | Typical Performance |
+|--------|-------------------|
+| Throughput | 1-10 Gbps |
+| Connections | 10,000-50,000 concurrent |
+| Latency | 1-5ms added |
+| CPU Usage | Moderate |
+
+**Best for**: Most web applications, APIs, sites needing inspection
+
+#### NFTables Engine Performance
+
+| Metric | Typical Performance |
+|--------|-------------------|
+| Throughput | 10-100 Gbps |
+| Connections | 100,000+ concurrent |
+| Latency | <0.1ms added |
+| CPU Usage | Minimal |
+
+**Best for**: High-traffic services, streaming, gaming, TCP forwarding
+
+#### Performance Tips
+
+1. **Use passthrough mode** when you don't need inspection
+2. **Enable NFTables** for high-traffic services
+3. **Terminate TLS only when necessary** - it adds CPU overhead
+4. **Use connection pooling** for terminate-and-reencrypt mode
+5. **Enable HTTP/2** for better multiplexing
+
+### Security Implications
+
+#### TLS Termination Security
+
+**Pros:**
+- Inspect traffic for threats
+- Add security headers
+- Implement WAF rules
+- Log requests for audit
+
+**Cons:**
+- Proxy has access to decrypted data
+- Requires secure certificate storage
+- Potential compliance issues
+
+**Best Practices:**
+- Use auto-renewal with Let's Encrypt
+- Store certificates securely
+- Implement proper access controls
+- Use strong TLS configurations
+
+#### Passthrough Security
+
+**Pros:**
+- True end-to-end encryption
+- No MITM concerns
+- Backend controls security
+
+**Cons:**
+- Cannot inspect traffic
+- Cannot add security headers
+- Limited DDoS protection
+
+#### Socket Handler Security
+
+**Risks:**
+- Custom code may have vulnerabilities
+- Resource exhaustion possible
+- Authentication bypass risks
+
+**Mitigations:**
+```typescript
+{
+  action: {
+    type: 'socket-handler',
+    socketHandler: async (socket, context) => {
+      // Always validate and sanitize input
+      socket.on('data', (data) => {
+        if (data.length > MAX_SIZE) {
+          socket.destroy();
+          return;
+        }
+        // Process safely...
+      });
+      
+      // Set timeouts
+      socket.setTimeout(30000);
+      
+      // Rate limit connections
+      if (connectionsFromIP(context.clientIp) > 10) {
+        socket.destroy();
+      }
+    }
+  }
+}
+```
+
+### Migration from Legacy Types
+
+#### From `http-only`
+
+**Old:**
+```typescript
+{
+  type: 'http-only',
+  target: { host: 'localhost', port: 8080 }
+}
+```
+
+**New:**
+```typescript
+{
+  match: { ports: 80, domains: 'example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'localhost', port: 8080 }
+  }
+}
+```
+
+#### From `https-passthrough`
+
+**Old:**
+```typescript
+{
+  type: 'https-passthrough',
+  target: { host: 'backend', port: 443 }
+}
+```
+
+**New:**
+```typescript
+{
+  match: { ports: 443, domains: 'example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'backend', port: 443 },
+    tls: { mode: 'passthrough' }
+  }
+}
+```
+
+#### From `https-terminate-to-http`
+
+**Old:**
+```typescript
+{
+  type: 'https-terminate-to-http',
+  target: { host: 'localhost', port: 8080 },
+  ssl: { /* certs */ }
+}
+```
+
+**New:**
+```typescript
+{
+  match: { ports: 443, domains: 'example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'localhost', port: 8080 },
+    tls: {
+      mode: 'terminate',
+      certificate: 'auto'  // or provide cert/key
+    }
+  }
+}
+```
+
+#### From `https-terminate-to-https`
+
+**Old:**
+```typescript
+{
+  type: 'https-terminate-to-https',
+  target: { host: 'backend', port: 443 },
+  ssl: { /* certs */ }
+}
+```
+
+**New:**
+```typescript
+{
+  match: { ports: 443, domains: 'example.com' },
+  action: {
+    type: 'forward',
+    target: { host: 'backend', port: 443 },
+    tls: {
+      mode: 'terminate-and-reencrypt',
+      certificate: 'auto'
+    }
+  }
+}
+```
+
+### Helper Functions Quick Reference
+
+SmartProxy provides helper functions for common configurations:
+
+```typescript
+// HTTP forwarding
+createHttpRoute('example.com', { host: 'localhost', port: 8080 })
+
+// HTTPS with termination
+createHttpsTerminateRoute('secure.com', { host: 'localhost', port: 8080 }, {
+  certificate: 'auto'
+})
+
+// HTTPS passthrough
+createHttpsPassthroughRoute('legacy.com', { host: 'backend', port: 443 })
+
+// Complete HTTPS setup (includes HTTP redirect)
+...createCompleteHttpsServer('example.com', { host: 'localhost', port: 8080 }, {
+  certificate: 'auto'
+})
+
+// NFTables high-performance
+createNfTablesRoute('fast.com', { host: 'backend', port: 8080 }, {
+  ports: 80,
+  preserveSourceIP: true
+})
+
+// Custom socket handler
+createSocketHandlerRoute('custom.com', 9000, async (socket, context) => {
+  // Handler implementation
+})
+```
+
+### Summary
+
+SmartProxy's forwarding modes provide flexibility for any proxy scenario:
+
+- **Simple HTTP/HTTPS forwarding** for most web applications
+- **TLS passthrough** for end-to-end encryption
+- **TLS termination** for traffic inspection and modification
+- **NFTables** for extreme performance requirements
+- **Socket handlers** for custom protocols
+
+Choose based on your security requirements, performance needs, and whether you need to inspect or modify traffic. The modern route-based configuration provides a consistent interface regardless of the forwarding mode you choose.
+
 ### Route Metadata and Prioritization
 
 You can add metadata to routes to help with organization and control matching priority:
@@ -921,122 +1576,316 @@ Available helper functions:
 
 ## Metrics and Monitoring
 
-SmartProxy includes a comprehensive metrics collection system that provides real-time insights into proxy performance, connection statistics, and throughput data.
+SmartProxy includes a comprehensive metrics collection system that provides real-time insights into proxy performance, connection statistics, and throughput data. The metrics system uses a clean, grouped API design for intuitive access to different metric categories.
 
-### Getting Metrics
+### Enabling Metrics
 
 ```typescript
-const proxy = new SmartProxy({ /* config */ });
+const proxy = new SmartProxy({
+  // Enable metrics collection
+  metrics: {
+    enabled: true,
+    sampleIntervalMs: 1000,    // Sample throughput every second
+    retentionSeconds: 3600     // Keep 1 hour of history
+  },
+  routes: [/* your routes */]
+});
+
 await proxy.start();
+```
 
-// Access metrics through the getStats() method
-const stats = proxy.getStats();
+### Getting Metrics
 
-// Get current active connections
-console.log(`Active connections: ${stats.getActiveConnections()}`);
+```typescript
+// Access metrics through the getMetrics() method
+const metrics = proxy.getMetrics();
 
-// Get total connections since start
-console.log(`Total connections: ${stats.getTotalConnections()}`);
+// The metrics object provides grouped methods for different categories
+```
 
-// Get requests per second (RPS)
-console.log(`Current RPS: ${stats.getRequestsPerSecond()}`);
+### Connection Metrics
 
-// Get throughput data
-const throughput = stats.getThroughput();
-console.log(`Bytes received: ${throughput.bytesIn}`);
-console.log(`Bytes sent: ${throughput.bytesOut}`);
+Monitor active connections, total connections, and connection distribution:
+
+```typescript
+// Get current active connections
+console.log(`Active connections: ${metrics.connections.active()}`);
+
+// Get total connections since start
+console.log(`Total connections: ${metrics.connections.total()}`);
 
 // Get connections by route
-const routeConnections = stats.getConnectionsByRoute();
+const routeConnections = metrics.connections.byRoute();
 for (const [route, count] of routeConnections) {
   console.log(`Route ${route}: ${count} connections`);
 }
 
 // Get connections by IP address
-const ipConnections = stats.getConnectionsByIP();
+const ipConnections = metrics.connections.byIP();
 for (const [ip, count] of ipConnections) {
   console.log(`IP ${ip}: ${count} connections`);
 }
+
+// Get top IPs by connection count
+const topIPs = metrics.connections.topIPs(10);
+topIPs.forEach(({ ip, count }) => {
+  console.log(`${ip}: ${count} connections`);
+});
+```
+
+### Throughput Metrics
+
+Real-time and historical throughput data with customizable time windows:
+
+```typescript
+// Get instant throughput (last 1 second)
+const instant = metrics.throughput.instant();
+console.log(`Current: ${instant.in} bytes/sec in, ${instant.out} bytes/sec out`);
+
+// Get recent throughput (last 10 seconds average)
+const recent = metrics.throughput.recent();
+console.log(`Recent: ${recent.in} bytes/sec in, ${recent.out} bytes/sec out`);
+
+// Get average throughput (last 60 seconds)
+const average = metrics.throughput.average();
+console.log(`Average: ${average.in} bytes/sec in, ${average.out} bytes/sec out`);
+
+// Get custom time window (e.g., last 5 minutes)
+const custom = metrics.throughput.custom(300);
+console.log(`5-min avg: ${custom.in} bytes/sec in, ${custom.out} bytes/sec out`);
+
+// Get throughput history for graphing
+const history = metrics.throughput.history(300); // Last 5 minutes
+history.forEach(point => {
+  console.log(`${new Date(point.timestamp)}: ${point.in} in, ${point.out} out`);
+});
+
+// Get throughput by route
+const routeThroughput = metrics.throughput.byRoute(60); // Last 60 seconds
+routeThroughput.forEach((stats, route) => {
+  console.log(`Route ${route}: ${stats.in} in, ${stats.out} out bytes/sec`);
+});
+
+// Get throughput by IP
+const ipThroughput = metrics.throughput.byIP(60);
+ipThroughput.forEach((stats, ip) => {
+  console.log(`IP ${ip}: ${stats.in} in, ${stats.out} out bytes/sec`);
+});
+```
+
+### Request Metrics
+
+Track request rates:
+
+```typescript
+// Get requests per second
+console.log(`RPS: ${metrics.requests.perSecond()}`);
+
+// Get requests per minute
+console.log(`RPM: ${metrics.requests.perMinute()}`);
+
+// Get total requests
+console.log(`Total requests: ${metrics.requests.total()}`);
+```
+
+### Cumulative Totals
+
+Track total bytes transferred and connections:
+
+```typescript
+// Get total bytes
+console.log(`Total bytes in: ${metrics.totals.bytesIn()}`);
+console.log(`Total bytes out: ${metrics.totals.bytesOut()}`);
+console.log(`Total connections: ${metrics.totals.connections()}`);
 ```
 
-### Available Metrics
+### Performance Percentiles
 
-The `IProxyStats` interface provides the following methods:
+Get percentile statistics (when implemented):
 
-- `getActiveConnections()`: Current number of active connections
-- `getTotalConnections()`: Total connections handled since proxy start
-- `getRequestsPerSecond()`: Current requests per second (1-minute average)
-- `getThroughput()`: Total bytes transferred (in/out)
-- `getConnectionsByRoute()`: Connection count per route
-- `getConnectionsByIP()`: Connection count per client IP
+```typescript
+// Connection duration percentiles
+const durations = metrics.percentiles.connectionDuration();
+console.log(`Connection durations - P50: ${durations.p50}ms, P95: ${durations.p95}ms, P99: ${durations.p99}ms`);
+
+// Bytes transferred percentiles
+const bytes = metrics.percentiles.bytesTransferred();
+console.log(`Bytes in - P50: ${bytes.in.p50}, P95: ${bytes.in.p95}, P99: ${bytes.in.p99}`);
+console.log(`Bytes out - P50: ${bytes.out.p50}, P95: ${bytes.out.p95}, P99: ${bytes.out.p99}`);
+```
 
-### Monitoring Example
+### Complete Monitoring Example
 
 ```typescript
-// Create a monitoring loop
+// Create a monitoring dashboard
 setInterval(() => {
-  const stats = proxy.getStats();
+  const metrics = proxy.getMetrics();
   
   // Log key metrics
   console.log({
     timestamp: new Date().toISOString(),
-    activeConnections: stats.getActiveConnections(),
-    rps: stats.getRequestsPerSecond(),
-    throughput: stats.getThroughput()
+    connections: {
+      active: metrics.connections.active(),
+      total: metrics.connections.total()
+    },
+    throughput: {
+      instant: metrics.throughput.instant(),
+      average: metrics.throughput.average()
+    },
+    requests: {
+      rps: metrics.requests.perSecond(),
+      total: metrics.requests.total()
+    },
+    totals: {
+      bytesIn: metrics.totals.bytesIn(),
+      bytesOut: metrics.totals.bytesOut()
+    }
   });
   
-  // Check for high connection counts from specific IPs
-  const ipConnections = stats.getConnectionsByIP();
-  for (const [ip, count] of ipConnections) {
+  // Alert on high connection counts
+  const topIPs = metrics.connections.topIPs(5);
+  topIPs.forEach(({ ip, count }) => {
     if (count > 100) {
       console.warn(`High connection count from ${ip}: ${count}`);
     }
+  });
+  
+  // Alert on high throughput
+  const instant = metrics.throughput.instant();
+  if (instant.in > 100_000_000) { // 100 MB/s
+    console.warn(`High incoming throughput: ${instant.in} bytes/sec`);
   }
 }, 10000); // Every 10 seconds
 ```
 
 ### Exporting Metrics
 
-You can export metrics in various formats for external monitoring systems:
+Export metrics in various formats for external monitoring systems:
 
 ```typescript
 // Export as JSON
 app.get('/metrics.json', (req, res) => {
-  const stats = proxy.getStats();
+  const metrics = proxy.getMetrics();
   res.json({
-    activeConnections: stats.getActiveConnections(),
-    totalConnections: stats.getTotalConnections(),
-    requestsPerSecond: stats.getRequestsPerSecond(),
-    throughput: stats.getThroughput(),
-    connectionsByRoute: Object.fromEntries(stats.getConnectionsByRoute()),
-    connectionsByIP: Object.fromEntries(stats.getConnectionsByIP())
+    connections: {
+      active: metrics.connections.active(),
+      total: metrics.connections.total(),
+      byRoute: Object.fromEntries(metrics.connections.byRoute()),
+      byIP: Object.fromEntries(metrics.connections.byIP())
+    },
+    throughput: {
+      instant: metrics.throughput.instant(),
+      recent: metrics.throughput.recent(),
+      average: metrics.throughput.average()
+    },
+    requests: {
+      perSecond: metrics.requests.perSecond(),
+      perMinute: metrics.requests.perMinute(),
+      total: metrics.requests.total()
+    },
+    totals: {
+      bytesIn: metrics.totals.bytesIn(),
+      bytesOut: metrics.totals.bytesOut(),
+      connections: metrics.totals.connections()
+    }
   });
 });
 
 // Export as Prometheus format
 app.get('/metrics', (req, res) => {
-  const stats = proxy.getStats();
+  const metrics = proxy.getMetrics();
+  const instant = metrics.throughput.instant();
+  
   res.set('Content-Type', 'text/plain');
   res.send(`
-# HELP smartproxy_active_connections Current active connections
-# TYPE smartproxy_active_connections gauge
-smartproxy_active_connections ${stats.getActiveConnections()}
+# HELP smartproxy_connections_active Current active connections
+# TYPE smartproxy_connections_active gauge
+smartproxy_connections_active ${metrics.connections.active()}
+
+# HELP smartproxy_connections_total Total connections since start
+# TYPE smartproxy_connections_total counter
+smartproxy_connections_total ${metrics.connections.total()}
+
+# HELP smartproxy_throughput_bytes_per_second Current throughput in bytes per second
+# TYPE smartproxy_throughput_bytes_per_second gauge
+smartproxy_throughput_bytes_per_second{direction="in"} ${instant.in}
+smartproxy_throughput_bytes_per_second{direction="out"} ${instant.out}
 
 # HELP smartproxy_requests_per_second Current requests per second
 # TYPE smartproxy_requests_per_second gauge
-smartproxy_requests_per_second ${stats.getRequestsPerSecond()}
+smartproxy_requests_per_second ${metrics.requests.perSecond()}
 
-# HELP smartproxy_bytes_in Total bytes received
-# TYPE smartproxy_bytes_in counter
-smartproxy_bytes_in ${stats.getThroughput().bytesIn}
-
-# HELP smartproxy_bytes_out Total bytes sent
-# TYPE smartproxy_bytes_out counter
-smartproxy_bytes_out ${stats.getThroughput().bytesOut}
+# HELP smartproxy_bytes_total Total bytes transferred
+# TYPE smartproxy_bytes_total counter
+smartproxy_bytes_total{direction="in"} ${metrics.totals.bytesIn()}
+smartproxy_bytes_total{direction="out"} ${metrics.totals.bytesOut()}
 `);
 });
 ```
 
+### Metrics API Reference
+
+The metrics API is organized into logical groups:
+
+```typescript
+interface IMetrics {
+  connections: {
+    active(): number;
+    total(): number;
+    byRoute(): Map<string, number>;
+    byIP(): Map<string, number>;
+    topIPs(limit?: number): Array<{ ip: string; count: number }>;
+  };
+  
+  throughput: {
+    instant(): IThroughputData;      // Last 1 second
+    recent(): IThroughputData;       // Last 10 seconds  
+    average(): IThroughputData;      // Last 60 seconds
+    custom(seconds: number): IThroughputData;
+    history(seconds: number): Array<IThroughputHistoryPoint>;
+    byRoute(windowSeconds?: number): Map<string, IThroughputData>;
+    byIP(windowSeconds?: number): Map<string, IThroughputData>;
+  };
+  
+  requests: {
+    perSecond(): number;
+    perMinute(): number;
+    total(): number;
+  };
+  
+  totals: {
+    bytesIn(): number;
+    bytesOut(): number;
+    connections(): number;
+  };
+  
+  percentiles: {
+    connectionDuration(): { p50: number; p95: number; p99: number };
+    bytesTransferred(): { 
+      in: { p50: number; p95: number; p99: number };
+      out: { p50: number; p95: number; p99: number };
+    };
+  };
+}
+```
+
+Where `IThroughputData` is:
+```typescript
+interface IThroughputData {
+  in: number;   // Bytes per second incoming
+  out: number;  // Bytes per second outgoing
+}
+```
+
+And `IThroughputHistoryPoint` is:
+```typescript
+interface IThroughputHistoryPoint {
+  timestamp: number;  // Unix timestamp in milliseconds
+  in: number;        // Bytes per second at this point
+  out: number;       // Bytes per second at this point
+}
+```
+
 ## Other Components
 
 While SmartProxy provides a unified API for most needs, you can also use individual components:
@@ -1736,6 +2585,62 @@ createHttpToHttpsRedirect('old.example.com', 443)
 }
 ```
 
+## WebSocket Keep-Alive Configuration
+
+If your WebSocket connections are disconnecting every 30 seconds in SNI passthrough mode, here's how to configure keep-alive settings:
+
+### Extended Keep-Alive Treatment (Recommended)
+
+```typescript
+const proxy = new SmartProxy({
+  // Extend timeout for keep-alive connections
+  keepAliveTreatment: 'extended',
+  keepAliveInactivityMultiplier: 10, // 10x the base timeout
+  inactivityTimeout: 14400000, // 4 hours base (40 hours with multiplier)
+  
+  routes: [
+    {
+      name: 'websocket-passthrough',
+      match: { 
+        ports: 443, 
+        domains: ['ws.example.com', 'wss.example.com'] 
+      },
+      action: {
+        type: 'forward',
+        target: { host: 'backend', port: 443 },
+        tls: { mode: 'passthrough' }
+      }
+    }
+  ]
+});
+```
+
+### Immortal Connections (Never Timeout)
+
+```typescript
+const proxy = new SmartProxy({
+  // Never timeout keep-alive connections
+  keepAliveTreatment: 'immortal',
+  
+  routes: [
+    // ... same as above
+  ]
+});
+```
+
+### Understanding the Issue
+
+In SNI passthrough mode:
+1. **WebSocket Heartbeat**: The HTTP proxy's WebSocket handler sends ping frames every 30 seconds
+2. **SNI Passthrough**: In passthrough mode, traffic is encrypted end-to-end
+3. **Can't Inject Pings**: The proxy can't inject ping frames into encrypted traffic
+4. **Connection Terminated**: After 30 seconds, connection is marked inactive and closed
+
+The solution involves:
+- Longer grace periods for encrypted connections (5 minutes vs 30 seconds)
+- Relying on OS-level TCP keep-alive instead of application-level heartbeat
+- Different timeout strategies per route type
+
 ## Configuration Options
 
 ### SmartProxy (IRoutedSmartProxyOptions)
@@ -1746,6 +2651,7 @@ createHttpToHttpsRedirect('old.example.com', 443)
 - `httpProxyPort` (number, default 8443) - Port where HttpProxy listens for forwarded connections
 - Connection timeouts: `initialDataTimeout`, `socketTimeout`, `inactivityTimeout`, etc.
 - Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
+- Keep-alive configuration: `keepAliveTreatment` ('standard'|'extended'|'immortal'), `keepAliveInactivityMultiplier`
 - `certProvisionFunction` (callback) - Custom certificate provisioning
 
 #### SmartProxy Dynamic Port Management Methods