@push.rocks/smartproxy 21.1.3 → 21.1.6

package/readme.md

@@ -1,475 +1,64 @@
-# @push.rocks/smartproxy
+# @push.rocks/smartproxy 🚀
 
-A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the central API to handle all your proxy needs:
+**The Swiss Army Knife of Node.js Proxies** - A unified, high-performance proxy toolkit that handles everything from simple HTTP forwarding to complex enterprise routing scenarios.
 
-- **Unified Route-Based Configuration**: Match/action pattern for clean, consistent traffic routing
-- **SSL/TLS Support**: Automatic HTTPS with Let's Encrypt certificate provisioning
-- **Flexible Matching Patterns**: Route by port, domain, path, client IP, and TLS version
-- **Advanced SNI Handling**: Smart TCP/SNI-based forwarding with IP filtering
-- **Multiple Action Types**: Forward traffic or handle with custom socket handlers
-- **Dynamic Port Management**: Add or remove listening ports at runtime without restart
-- **Security Features**: Route-specific IP allowlists, blocklists, connection limits, and authentication
-- **NFTables Integration**: High-performance kernel-level packet forwarding with Linux NFTables
-- **Socket Handlers**: Custom socket handling for specialized protocols and use cases
-- **Multiple Targets**: Load balancing and failover with support for multiple upstream targets
+## 🎯 What is SmartProxy?
 
-## Project Architecture Overview
+SmartProxy is a modern, production-ready proxy solution that brings order to the chaos of traffic management. Whether you're building microservices, deploying edge infrastructure, or need a battle-tested reverse proxy, SmartProxy has you covered.
 
-SmartProxy has been restructured using a modern, modular architecture with a unified route-based configuration system:
+### ⚡ Key Features
 
-```
-/ts
-├── /core                     # Core functionality
-│   ├── /models               # Data models and interfaces
-│   ├── /utils                # Shared utilities (IP validation, logging, etc.)
-│   └── /events               # Common event definitions
-├── /forwarding               # Forwarding system
-│   ├── /handlers             # Various forwarding handlers
-│   │   ├── base-handler.ts   # Abstract base handler
-│   │   ├── http-handler.ts   # HTTP-only handler
-│   │   └── ...               # Other handlers
-│   ├── /config               # Configuration models
-│   └── /factory              # Factory for creating handlers
-├── /proxies                  # Different proxy implementations
-│   ├── /smart-proxy          # SmartProxy implementation
-│   │   ├── /models           # SmartProxy-specific interfaces
-│   │   │   ├── route-types.ts # Route-based configuration types
-│   │   │   └── interfaces.ts  # SmartProxy interfaces
-│   │   ├── certificate-manager.ts # SmartCertManager
-│   │   ├── cert-store.ts     # Certificate file storage
-│   │   ├── route-helpers.ts  # Helper functions for creating routes
-│   │   ├── route-manager.ts  # Route management system
-│   │   ├── smart-proxy.ts    # Main SmartProxy class
-│   │   └── ...               # Supporting classes
-│   ├── /http-proxy           # HttpProxy implementation (HTTP/HTTPS handling)
-│   └── /nftables-proxy       # NfTablesProxy implementation
-├── /tls                      # TLS-specific functionality
-│   ├── /sni                  # SNI handling components
-│   └── /alerts               # TLS alerts system
-└── /routing                  # Routing functionality
-    └── /router               # HTTP routing system
-```
-
-## Main Components
+- **🔀 Unified Route-Based Configuration** - Clean match/action patterns for intuitive traffic routing
+- **🔒 Automatic SSL/TLS with Let's Encrypt** - Zero-config HTTPS with automatic certificate provisioning
+- **🎯 Flexible Matching Patterns** - Route by port, domain, path, client IP, TLS version, or custom logic
+- **🚄 High-Performance Forwarding** - Choose between user-space or kernel-level (NFTables) forwarding
+- **⚖️ Built-in Load Balancing** - Distribute traffic across multiple backends with health checks
+- **🛡️ Enterprise Security** - IP filtering, rate limiting, authentication, and connection limits
+- **🔌 WebSocket Support** - First-class WebSocket proxying with ping/pong management
+- **🎮 Custom Socket Handlers** - Implement any protocol with full socket control
+- **📊 Dynamic Port Management** - Add/remove ports at runtime without restarts
+- **🔧 Protocol Detection** - Smart protocol detection for mixed-mode operation
 
-### Primary API (Recommended)
-
-- **SmartProxy** (`ts/proxies/smart-proxy/smart-proxy.ts`)
-  The central unified API for all proxy needs, featuring:
-  - Route-based configuration with match/action pattern
-  - Flexible matching criteria (ports, domains, paths, client IPs)
-  - Multiple action types (forward, redirect, block, socket-handler)
-  - Automatic certificate management
-  - Advanced security controls
-  - Custom socket handling capabilities
-  - Load balancing with multiple targets
-
-### Helper Functions
+## 📦 Installation
 
-- **createHttpRoute**, **createHttpsTerminateRoute**, **createHttpsPassthroughRoute**
-  Helper functions to create different route configurations with clean syntax
-- **createHttpToHttpsRedirect**
-  Helper function for HTTP to HTTPS redirects using socket handlers
-- **createLoadBalancerRoute**, **createCompleteHttpsServer**
-  Helper functions for complex configurations
-- **createSocketHandlerRoute**, **SocketHandlers**
-  Helper functions for custom socket handling
-- **createNfTablesRoute**, **createNfTablesTerminateRoute**, **createCompleteNfTablesHttpsServer**
-  Helper functions for NFTables-based high-performance kernel-level routing
-- **createPortMappingRoute**, **createOffsetPortMappingRoute**, **createDynamicRoute**, **createSmartLoadBalancer**
-  Helper functions for dynamic routing and port mapping
-- **createApiGatewayRoute**, **addRateLimiting**, **addBasicAuth**, **addJwtAuth**
-  Helper functions for API gateway features and authentication
-
-### Specialized Components
-
-- **HttpProxy** (`ts/proxies/http-proxy/http-proxy.ts`)
-  HTTP/HTTPS reverse proxy with TLS termination and WebSocket support
-- **NfTablesProxy** (`ts/proxies/nftables-proxy/nftables-proxy.ts`)
-  Low-level port forwarding using nftables NAT rules
-- **SniHandler** (`ts/tls/sni/sni-handler.ts`)
-  Utilities for SNI extraction from TLS handshakes
-
-### Core Utilities
-
-- **ValidationUtils** (`ts/core/utils/validation-utils.ts`)
-  Domain, port, and configuration validation
-- **IpUtils** (`ts/core/utils/ip-utils.ts`)
-  IP address validation and filtering with glob patterns
-
-### Interfaces and Types
-
-- `IRouteConfig`, `IRouteMatch`, `IRouteAction` (`ts/proxies/smart-proxy/models/route-types.ts`)
-- `IRoutedSmartProxyOptions` (`ts/proxies/smart-proxy/models/route-types.ts`)
-- `IHttpProxyOptions` (`ts/proxies/http-proxy/models/types.ts`)
-- `INfTableProxySettings` (`ts/proxies/nftables-proxy/models/interfaces.ts`)
-
-## Installation
-Install via npm:
 ```bash
 npm install @push.rocks/smartproxy
 ```
 
-## Quick Start with SmartProxy
+## 🚀 Quick Start
 
-SmartProxy v20.0.0 provides a unified route-based configuration system with enhanced certificate management, NFTables integration for high-performance kernel-level routing, custom socket handling, and improved helper functions for common proxy setups.
-
-**⚠️ Breaking Change in v20.0.0**: The route action configuration has changed from single `target` to `targets` array to support multiple upstream targets for load balancing and failover.
+Let's get you up and running in 30 seconds:
 
 ```typescript
-import {
-  SmartProxy,
-  createHttpRoute,
-  createHttpsTerminateRoute,
-  createHttpsPassthroughRoute,
-  createHttpToHttpsRedirect,
-  createCompleteHttpsServer,
-  createLoadBalancerRoute,
-  createApiRoute,
-  createWebSocketRoute,
-  createSocketHandlerRoute,
-  createNfTablesRoute,
-  createNfTablesTerminateRoute,
-  createCompleteNfTablesHttpsServer,
-  createPortMappingRoute,
-  createOffsetPortMappingRoute,
-  createDynamicRoute,
-  createSmartLoadBalancer,
-  createApiGatewayRoute,
-  addRateLimiting,
-  addBasicAuth,
-  addJwtAuth,
-  SocketHandlers
-} from '@push.rocks/smartproxy';
+import { SmartProxy, createCompleteHttpsServer } from '@push.rocks/smartproxy';
 
-// Create a new SmartProxy instance with route-based configuration
+// Create a proxy with automatic HTTPS
 const proxy = new SmartProxy({
-  // Global ACME settings for all routes with certificate: 'auto'
   acme: {
-    email: 'ssl@example.com',       // Required for Let's Encrypt
-    useProduction: false,           // Use staging by default
-    renewThresholdDays: 30,         // Renew 30 days before expiry
-    port: 80,                       // Port for HTTP-01 challenges (use 8080 for non-privileged)
-    autoRenew: true,               // Enable automatic renewal
-    renewCheckIntervalHours: 24    // Check for renewals daily
+    email: 'ssl@example.com',       // Your email for Let's Encrypt
+    useProduction: true              // Use Let's Encrypt production servers
   },
-  
-  // Define all your routing rules in a single array
   routes: [
-    // Basic HTTP route - forward traffic from port 80 to internal service
-    createHttpRoute('api.example.com', { host: 'localhost', port: 3000 }),
-
-    // HTTPS route with TLS termination and automatic certificates
-    createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
-      certificate: 'auto'  // Uses global ACME settings
-    }),
-
-    // HTTPS passthrough for legacy systems
-    createHttpsPassthroughRoute('legacy.example.com', { host: '192.168.1.10', port: 443 }),
-
-    // Redirect HTTP to HTTPS for all domains and subdomains
-    createHttpToHttpsRedirect(['example.com', '*.example.com']),
-
-    // Complete HTTPS server (creates both HTTPS route and HTTP redirect)
-    ...createCompleteHttpsServer('complete.example.com', { host: 'localhost', port: 3000 }, {
-      certificate: 'auto'
-    }),
-
-    // API route with CORS headers
-    createApiRoute('api.service.com', '/v1', { host: 'api-backend', port: 8081 }, {
-      useTls: true,
-      certificate: 'auto',
-      addCorsHeaders: true
-    }),
-
-    // WebSocket route for real-time communication
-    createWebSocketRoute('ws.example.com', '/socket', { host: 'socket-server', port: 8082 }, {
-      useTls: true,
-      certificate: 'auto',
-      pingInterval: 30000
-    }),
-
-
-    // Load balancer with multiple backend servers
-    createLoadBalancerRoute(
-      'app.example.com',
-      ['192.168.1.10', '192.168.1.11', '192.168.1.12'],
-      8080,
-      {
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto'
-        }
-      }
-    ),
-
-    // Custom socket handler for specialized protocols
-    createSocketHandlerRoute('telnet.example.com', 23, SocketHandlers.lineProtocol((line, socket) => {
-      console.log('Received:', line);
-      socket.write(`Echo: ${line}\n`);
-    })),
-
-    // High-performance NFTables route (requires root/sudo)
-    createNfTablesRoute('fast.example.com', { host: 'backend-server', port: 8080 }, {
-      ports: 80,
-      protocol: 'tcp',
-      preserveSourceIP: true,
-      ipAllowList: ['10.0.0.*']
-    }),
-
-    // NFTables HTTPS termination for ultra-fast TLS handling
-    createNfTablesTerminateRoute('secure-fast.example.com', { host: 'backend-ssl', port: 443 }, {
-      ports: 443,
-      certificate: 'auto',
-      maxRate: '100mbps'
-    }),
-
-    // Route with security configuration
-    {
-      name: 'secure-admin',
-      match: {
-        ports: 443,
-        domains: 'admin.example.com'
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'localhost', port: 8080 }],  // Note: targets is an array
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto'
-        }
-      },
-      security: {
-        ipAllowList: ['10.0.0.*', '192.168.1.*'],
-        ipBlockList: ['192.168.1.100'],
-        maxConnections: 100
-      }
-    }
+    // Complete HTTPS setup with one line
+    ...createCompleteHttpsServer('app.example.com', { 
+      host: 'localhost', 
+      port: 3000 
+    }, {
+      certificate: 'auto'  // Magic! 🎩
+    })
   ]
 });
 
-// Start the proxy
 await proxy.start();
-
-// Dynamically add new routes later
-await proxy.updateRoutes([
-  ...proxy.settings.routes,
-  createHttpsTerminateRoute('new-domain.com', { host: 'localhost', port: 9000 }, {
-    certificate: 'auto'
-  })
-]);
-
-// Dynamically add or remove port listeners
-await proxy.addListeningPort(8081);
-await proxy.removeListeningPort(8081);
-console.log('Currently listening on ports:', proxy.getListeningPorts());
-
-// Later, gracefully shut down
-await proxy.stop();
-```
-
-## Route-Based Configuration System
-
-SmartProxy uses a unified route configuration system based on the `IRouteConfig` interface. This system follows a match/action pattern that makes routing more powerful, flexible, and declarative.
-
-### IRouteConfig Interface
-
-The `IRouteConfig` interface is the core building block of SmartProxy's configuration system. Each route definition consists of match criteria and an action to perform on matched traffic:
-
-```typescript
-interface IRouteConfig {
-  // What traffic to match (required)
-  match: IRouteMatch;
-
-  // What to do with matched traffic (required)
-  action: IRouteAction;
-
-  // Security configuration (optional)
-  security?: IRouteSecurity;
-
-  // Metadata (all optional)
-  name?: string;             // Human-readable name for this route
-  description?: string;      // Description of the route's purpose
-  priority?: number;         // Controls matching order (higher = matched first)
-  tags?: string[];           // Arbitrary tags for categorization
-  enabled?: boolean;         // Whether the route is active (default: true)
-}
-```
-
-#### Match Criteria (IRouteMatch)
-
-The `match` property defines criteria for identifying which incoming traffic should be handled by this route:
-
-```typescript
-interface IRouteMatch {
-  // Port(s) to match
-  ports: number | number[] | string;    // Single port, array, or range like '8000-8999'
-  
-  // Domain matching (optional - if not specified, matches all domains)
-  domains?: string | string[];          // Exact domains or patterns with wildcards
-  
-  // Path matching (optional)
-  path?: string;                        // URL path pattern (supports wildcards)
-  
-  // Client IP matching (optional)
-  clientIp?: string | string[];         // IP addresses or CIDR ranges
-  
-  // Protocol matching (optional)
-  protocol?: 'tcp' | 'udp' | 'http' | 'https' | 'ws' | 'wss';
-  
-  // TLS version matching (optional)
-  tlsVersion?: string | string[];       // e.g., ['TLSv1.2', 'TLSv1.3']
-  
-  // Custom matcher function (optional)
-  customMatcher?: (context: IRouteContext) => boolean | Promise<boolean>;
-}
+console.log('🚀 Proxy running with automatic HTTPS!');
 ```
 
-**Domain Matching Patterns:**
-- Exact match: `example.com`
-- Wildcard subdomain: `*.example.com`
-- Multiple domains: `['example.com', '*.example.com', 'example.org']`
-- All domains: omit the `domains` field
-
-**Path Matching Patterns:**
-- Exact path: `/api/users`
-- Path prefix with wildcard: `/api/*`
-- Path with parameter: `/api/users/:id`
-- Multiple path segments: `/api/*/details`
+## 📚 Core Concepts
 
-#### Action Types (IRouteAction)
+### 🏗️ Route-Based Architecture
 
-The `action` property defines what to do with matched traffic:
+SmartProxy uses a powerful match/action pattern that makes routing predictable and maintainable:
 
-```typescript
-interface IRouteAction {
-  // Action type (required)
-  type: 'forward' | 'redirect' | 'block' | 'socket-handler';
-  
-  // For 'forward' type - array of upstream targets
-  targets?: IRouteTarget[];
-  
-  // For 'redirect' type
-  redirectUrl?: string;               // URL template with placeholders
-  redirectCode?: number;              // HTTP status code (301, 302, etc.)
-  
-  // For 'socket-handler' type
-  socketHandler?: (socket: net.Socket, context: IRouteContext) => void | Promise<void>;
-  
-  // TLS configuration (optional)
-  tls?: IRouteTls;
-  
-  // WebSocket configuration (optional)
-  websocket?: {
-    enabled: boolean;
-    pingInterval?: number;            // Milliseconds between pings
-    pingTimeout?: number;             // Milliseconds to wait for pong
-  };
-  
-  // Headers manipulation (optional)
-  headers?: {
-    request?: Record<string, string>;   // Headers to add to requests
-    response?: Record<string, string>;  // Headers to add to responses
-  };
-}
-```
-
-**Forward Action with Multiple Targets:**
-```typescript
-{
-  type: 'forward',
-  targets: [
-    { host: 'backend1.example.com', port: 8080 },
-    { host: 'backend2.example.com', port: 8080 },
-    { host: 'backend3.example.com', port: 8080 }
-  ]
-}
-```
-
-**Redirect Action:**
-```typescript
-{
-  type: 'redirect',
-  redirectUrl: 'https://{domain}/{path}',  // Placeholders: {domain}, {path}, {clientIp}
-  redirectCode: 301
-}
-```
-
-**Socket Handler Action:**
-```typescript
-{
-  type: 'socket-handler',
-  socketHandler: (socket, context) => {
-    // Custom logic for handling the socket
-    socket.write('Hello from custom handler\n');
-    socket.end();
-  }
-}
-```
-
-### Route Examples
-
-#### Basic HTTP Forwarding
-```typescript
-{
-  match: {
-    ports: 80,
-    domains: 'api.example.com'
-  },
-  action: {
-    type: 'forward',
-    targets: [{ host: 'localhost', port: 3000 }]
-  }
-}
-```
-
-#### HTTPS with TLS Termination and Load Balancing
-```typescript
-{
-  match: {
-    ports: 443,
-    domains: ['secure.example.com', '*.secure.example.com']
-  },
-  action: {
-    type: 'forward',
-    targets: [
-      { host: '10.0.0.10', port: 8080 },
-      { host: '10.0.0.11', port: 8080 },
-      { host: '10.0.0.12', port: 8080 }
-    ],
-    tls: {
-      mode: 'terminate',
-      certificate: 'auto'  // Automatic Let's Encrypt certificate
-    }
-  }
-}
-```
-
-#### WebSocket Route
-```typescript
-{
-  match: {
-    ports: 443,
-    domains: 'ws.example.com',
-    path: '/socket/*'
-  },
-  action: {
-    type: 'forward',
-    targets: [{ host: 'websocket-server', port: 8080 }],
-    tls: {
-      mode: 'terminate',
-      certificate: 'auto'
-    },
-    websocket: {
-      enabled: true,
-      pingInterval: 30000,
-      pingTimeout: 5000
-    }
-  }
-}
-```
-
-#### API Gateway with Security
 ```typescript
 {
   match: {
@@ -479,473 +68,367 @@ interface IRouteAction {
   },
   action: {
     type: 'forward',
-    targets: [{ host: 'api-backend', port: 8080 }],
-    tls: {
-      mode: 'terminate',
-      certificate: 'auto'
-    },
-    headers: {
-      request: {
-        'X-API-Version': 'v1',
-        'X-Real-IP': '{clientIp}'
-      },
-      response: {
-        'Access-Control-Allow-Origin': '*',
-        'X-Powered-By': 'SmartProxy'
-      }
-    }
-  },
-  security: {
-    ipAllowList: ['10.0.0.0/8', '172.16.0.0/12'],
-    rateLimit: {
-      maxRequests: 100,
-      windowMs: 60000
-    },
-    authentication: {
-      type: 'basic',
-      realm: 'API Access',
-      users: {
-        'apiuser': 'hashedpassword'
-      }
-    }
+    targets: [{ host: 'backend', port: 8080 }],
+    tls: { mode: 'terminate', certificate: 'auto' }
   }
 }
 ```
 
-## NFTables Integration
+Every route has:
+- **Match criteria** - What traffic to capture
+- **Action** - What to do with it
+- **Security** (optional) - Access controls and limits
+- **Metadata** (optional) - Name, priority, tags
 
-SmartProxy includes high-performance kernel-level packet forwarding using Linux NFTables. This provides ultra-low latency forwarding by operating at the kernel level.
+## 💡 Common Use Cases
 
-### Requirements
-- Linux kernel with NFTables support
-- Root/sudo privileges
-- `nft` command-line tool installed
+### 🌐 Simple HTTP to HTTPS Redirect
 
-### NFTables Route Example
 ```typescript
-// Basic NFTables forwarding
-createNfTablesRoute('fast.example.com', { host: 'backend', port: 8080 }, {
-  ports: 80,
-  protocol: 'tcp',
-  preserveSourceIP: true
-})
-
-// NFTables with TLS termination
-createNfTablesTerminateRoute('secure-fast.example.com', { host: 'backend', port: 8080 }, {
-  ports: 443,
-  certificate: 'auto',
-  maxRate: '100mbps'
-})
-```
-
-## Socket Handlers
+import { SmartProxy, createHttpToHttpsRedirect } from '@push.rocks/smartproxy';
 
-SmartProxy supports custom socket handlers for implementing specialized protocols or custom logic:
+const proxy = new SmartProxy({
+  routes: [
+    // Redirect all HTTP traffic to HTTPS
+    createHttpToHttpsRedirect(['example.com', '*.example.com'])
+  ]
+});
+```
 
-### Pre-built Socket Handlers
+### ⚖️ Load Balancer with Health Checks
 
 ```typescript
-// Echo server
-createSocketHandlerRoute('echo.example.com', 7, SocketHandlers.echo)
-
-// HTTP redirect
-createHttpToHttpsRedirect('example.com')
-
-// Line-based protocol
-createSocketHandlerRoute('telnet.example.com', 23, SocketHandlers.lineProtocol((line, socket) => {
-  socket.write(`You said: ${line}\n`);
-}))
-
-// HTTP server for custom logic
-createSocketHandlerRoute('custom.example.com', 8080, SocketHandlers.httpServer((req, res) => {
-  if (req.url === '/health') {
-    res.status(200);
-    res.send('OK');
-  } else {
-    res.status(404);
-    res.send('Not Found');
-  }
-  res.end();
-}))
+import { createLoadBalancerRoute } from '@push.rocks/smartproxy';
 
-// Block connections
-createSocketHandlerRoute('blocked.example.com', 443, SocketHandlers.block('Access Denied'))
-
-// TCP proxy
-createSocketHandlerRoute('proxy.example.com', 8080, SocketHandlers.proxy('internal-server', 3000))
+const route = createLoadBalancerRoute(
+  'app.example.com',
+  [
+    { host: 'server1.internal', port: 8080 },
+    { host: 'server2.internal', port: 8080 },
+    { host: 'server3.internal', port: 8080 }
+  ],
+  {
+    tls: { mode: 'terminate', certificate: 'auto' },
+    loadBalancing: {
+      algorithm: 'round-robin',
+      healthCheck: {
+        path: '/health',
+        interval: 30000,
+        timeout: 5000
+      }
+    }
+  }
+);
 ```
 
-### Custom Socket Handler
+### 🔌 WebSocket Proxy
 
 ```typescript
-{
-  match: {
-    ports: 9999,
-    domains: 'custom.example.com'
-  },
-  action: {
-    type: 'socket-handler',
-    socketHandler: async (socket, context) => {
-      console.log(`New connection from ${context.clientIp} to ${context.domain}`);
-      
-      socket.write('Welcome to the custom protocol server\n');
-      
-      socket.on('data', (data) => {
-        // Process incoming data
-        const command = data.toString().trim();
-        
-        if (command === 'QUIT') {
-          socket.end('Goodbye\n');
-        } else {
-          socket.write(`Unknown command: ${command}\n`);
-        }
-      });
-      
-      socket.on('error', (err) => {
-        console.error('Socket error:', err);
-      });
-    }
+import { createWebSocketRoute } from '@push.rocks/smartproxy';
+
+const route = createWebSocketRoute(
+  'ws.example.com',
+  { host: 'websocket-server', port: 8080 },
+  {
+    path: '/socket',
+    useTls: true,
+    certificate: 'auto',
+    pingInterval: 30000  // Keep connections alive
   }
-}
+);
 ```
 
-## Dynamic Port Management
-
-SmartProxy allows you to dynamically add or remove listening ports without restarting:
+### 🚦 API Gateway with Rate Limiting
 
 ```typescript
-// Add a new listening port
-await proxy.addListeningPort(8443);
+import { createApiGatewayRoute, addRateLimiting } from '@push.rocks/smartproxy';
 
-// Remove a listening port
-await proxy.removeListeningPort(8080);
+let route = createApiGatewayRoute(
+  'api.example.com',
+  '/api',
+  { host: 'api-backend', port: 8080 },
+  {
+    useTls: true,
+    certificate: 'auto',
+    addCorsHeaders: true
+  }
+);
 
-// Get all currently listening ports
-const ports = proxy.getListeningPorts(); // [80, 443, 8443]
+// Add rate limiting
+route = addRateLimiting(route, {
+  maxRequests: 100,
+  window: 60,  // seconds
+  keyBy: 'ip'
+});
 ```
 
-## Certificate Management
+### 🎮 Custom Protocol Handler
 
-SmartProxy includes automatic certificate management with Let's Encrypt support:
-
-### Automatic Certificates (Let's Encrypt)
 ```typescript
-{
-  action: {
-    tls: {
-      mode: 'terminate',
-      certificate: 'auto'  // Automatic Let's Encrypt certificate
-    }
-  }
-}
-```
+import { createSocketHandlerRoute, SocketHandlers } from '@push.rocks/smartproxy';
 
-### Manual Certificates
-```typescript
-{
-  action: {
-    tls: {
-      mode: 'terminate',
-      certificate: {
-        key: fs.readFileSync('./certs/private.key', 'utf8'),
-        cert: fs.readFileSync('./certs/certificate.crt', 'utf8')
+// Pre-built handlers
+const echoRoute = createSocketHandlerRoute(
+  'echo.example.com', 
+  7777, 
+  SocketHandlers.echo
+);
+
+// Custom handler
+const customRoute = createSocketHandlerRoute(
+  'custom.example.com',
+  9999,
+  async (socket, context) => {
+    console.log(`Connection from ${context.clientIp}`);
+    
+    socket.write('Welcome to my custom protocol!\n');
+    
+    socket.on('data', (data) => {
+      const command = data.toString().trim();
+      
+      if (command === 'HELLO') {
+        socket.write('World!\n');
+      } else if (command === 'EXIT') {
+        socket.end('Goodbye!\n');
       }
-    }
+    });
   }
-}
+);
 ```
 
-### Certificate Store
-Certificates are automatically stored and managed:
-- Auto certificates: `./certificates/{domain}/`
-- Manual certificates: In-memory only
+### ⚡ High-Performance NFTables Forwarding
 
-## Security Features
+For ultra-low latency, use kernel-level forwarding (Linux only, requires root):
 
-### IP-Based Access Control
 ```typescript
-{
-  security: {
-    ipAllowList: ['10.0.0.0/8', '192.168.*', '::1'],
-    ipBlockList: ['192.168.1.100', '10.0.0.0/24']
-  }
-}
-```
+import { createNfTablesTerminateRoute } from '@push.rocks/smartproxy';
 
-### Connection Limits
-```typescript
-{
-  security: {
-    maxConnections: 1000,              // Total connections
-    maxConnectionsPerIp: 10            // Per IP address
+const route = createNfTablesTerminateRoute(
+  'fast.example.com',
+  { host: 'backend', port: 8080 },
+  {
+    ports: 443,
+    certificate: 'auto',
+    preserveSourceIP: true,
+    maxRate: '1gbps'
   }
-}
+);
 ```
 
-### Rate Limiting
+## 🔧 Advanced Features
+
+### 🎯 Dynamic Routing
+
+Route traffic based on runtime conditions:
+
 ```typescript
 {
-  security: {
-    rateLimit: {
-      maxRequests: 100,                // Maximum requests
-      windowMs: 60000                  // Time window (1 minute)
+  match: {
+    ports: 443,
+    customMatcher: async (context) => {
+      // Route based on time of day
+      const hour = new Date().getHours();
+      return hour >= 9 && hour < 17;  // Business hours only
     }
+  },
+  action: {
+    type: 'forward',
+    targets: [{
+      host: (context) => {
+        // Dynamic host selection
+        return context.path.startsWith('/premium') 
+          ? 'premium-backend' 
+          : 'standard-backend';
+      },
+      port: 8080
+    }]
   }
 }
 ```
 
-### Authentication
-```typescript
-// Basic Authentication
-{
-  security: {
-    authentication: {
-      type: 'basic',
-      realm: 'Protected Area',
-      users: {
-        'admin': 'hashedpassword'
-      }
-    }
-  }
-}
+### 🔒 Security Controls
+
+Comprehensive security options per route:
 
-// JWT Authentication
+```typescript
 {
   security: {
+    // IP-based access control
+    ipAllowList: ['10.0.0.0/8', '192.168.*'],
+    ipBlockList: ['192.168.1.100'],
+    
+    // Connection limits
+    maxConnections: 1000,
+    maxConnectionsPerIp: 10,
+    
+    // Rate limiting
+    rateLimit: {
+      maxRequests: 100,
+      windowMs: 60000
+    },
+    
+    // Authentication
     authentication: {
       type: 'jwt',
-      secret: 'your-secret-key',
+      secret: process.env.JWT_SECRET,
       algorithms: ['HS256']
     }
   }
 }
 ```
 
-## Advanced Features
+### 📊 Runtime Management
+
+Control your proxy without restarts:
 
-### Custom Route Matching
 ```typescript
-{
-  match: {
-    ports: 443,
-    customMatcher: async (context) => {
-      // Custom logic to determine if route should match
-      const hour = new Date().getHours();
-      return hour >= 9 && hour < 17; // Only match during business hours
-    }
-  }
-}
+// Add/remove ports dynamically
+await proxy.addListeningPort(8443);
+await proxy.removeListeningPort(8080);
+
+// Update routes on the fly
+await proxy.updateRoutes([...newRoutes]);
+
+// Monitor status
+const status = proxy.getStatus();
+const metrics = proxy.getMetrics();
+
+// Certificate management
+await proxy.renewCertificate('example.com');
+const certInfo = proxy.getCertificateInfo('example.com');
 ```
 
-### Header Manipulation
+### 🔄 Header Manipulation
+
+Transform requests and responses:
+
 ```typescript
 {
   action: {
     headers: {
       request: {
-        'X-Real-IP': '{clientIp}',
-        'X-Forwarded-For': '{clientIp}',
-        'X-Custom-Header': 'value'
+        'X-Real-IP': '{clientIp}',           // Template variables
+        'X-Request-ID': '{uuid}',
+        'X-Custom': 'value'
       },
       response: {
         'X-Powered-By': 'SmartProxy',
-        'Strict-Transport-Security': 'max-age=31536000'
+        'Strict-Transport-Security': 'max-age=31536000',
+        'X-Frame-Options': 'DENY'
       }
     }
   }
 }
 ```
 
-### Dynamic Target Selection
-```typescript
-{
-  action: {
-    type: 'forward',
-    targets: [
-      {
-        host: ['backend1.example.com', 'backend2.example.com'],  // Round-robin
-        port: (context) => {
-          // Dynamic port based on path
-          return context.path.startsWith('/api/v1') ? 8081 : 8080;
-        }
-      }
-    ]
-  }
-}
-```
+## 🏛️ Architecture
 
-## Complete Examples
+SmartProxy is built with a modular, extensible architecture:
 
-### Multi-Domain HTTPS Server with Redirects
-```typescript
-const proxy = new SmartProxy({
-  acme: {
-    email: 'admin@example.com',
-    useProduction: true
-  },
-  routes: [
-    // HTTPS routes
-    ...['example.com', 'app.example.com', 'api.example.com'].map(domain =>
-      createHttpsTerminateRoute(domain, { host: 'localhost', port: 3000 }, {
-        certificate: 'auto'
-      })
-    ),
-    
-    // HTTP to HTTPS redirects
-    createHttpToHttpsRedirect(['example.com', '*.example.com'])
-  ]
-});
 ```
+SmartProxy
+├── 📋 Route Manager         # Route matching and prioritization
+├── 🔌 Port Manager          # Dynamic port lifecycle
+├── 🔒 Certificate Manager   # ACME/Let's Encrypt automation
+├── 🚦 Connection Manager    # Connection pooling and limits
+├── 📊 Metrics Collector     # Performance monitoring
+├── 🛡️ Security Manager      # Access control and rate limiting
+└── 🔧 Protocol Detectors    # Smart protocol identification
+```
+
+## 🎯 Route Configuration Reference
+
+### Match Criteria
 
-### API Gateway with Multiple Services
 ```typescript
-const proxy = new SmartProxy({
-  routes: [
-    // User service
-    createApiRoute('api.example.com', '/users', { host: 'user-service', port: 8081 }),
-    
-    // Product service
-    createApiRoute('api.example.com', '/products', { host: 'product-service', port: 8082 }),
-    
-    // Order service with authentication
-    {
-      match: {
-        ports: 443,
-        domains: 'api.example.com',
-        path: '/orders/*'
-      },
-      action: {
-        type: 'forward',
-        targets: [{ host: 'order-service', port: 8083 }],
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto'
-        }
-      },
-      security: {
-        authentication: {
-          type: 'jwt',
-          secret: process.env.JWT_SECRET
-        }
-      }
-    }
-  ]
-});
+interface IRouteMatch {
+  ports: number | number[] | string;      // 80, [80, 443], '8000-8999'
+  domains?: string | string[];            // 'example.com', '*.example.com'
+  path?: string;                          // '/api/*', '/users/:id'
+  clientIp?: string | string[];           // '10.0.0.0/8', ['192.168.*']
+  protocol?: 'tcp' | 'udp' | 'http' | 'https' | 'ws' | 'wss';
+  tlsVersion?: string | string[];         // ['TLSv1.2', 'TLSv1.3']
+  customMatcher?: (context) => boolean;   // Custom logic
+}
 ```
 
-### WebSocket Server with Load Balancing
+### Action Types
+
 ```typescript
-const proxy = new SmartProxy({
-  routes: [
-    {
-      match: {
-        ports: 443,
-        domains: 'ws.example.com'
-      },
-      action: {
-        type: 'forward',
-        targets: [
-          { host: 'ws-server-1', port: 8080 },
-          { host: 'ws-server-2', port: 8080 },
-          { host: 'ws-server-3', port: 8080 }
-        ],
-        tls: {
-          mode: 'terminate',
-          certificate: 'auto'
-        },
-        websocket: {
-          enabled: true,
-          pingInterval: 30000
-        }
-      }
-    }
-  ]
-});
+interface IRouteAction {
+  type: 'forward' | 'redirect' | 'block' | 'socket-handler';
+  
+  // For 'forward'
+  targets?: Array<{
+    host: string | string[] | ((context) => string);
+    port: number | ((context) => number);
+  }>;
+  
+  // For 'redirect'
+  redirectUrl?: string;      // With {domain}, {path}, {clientIp} templates
+  redirectCode?: number;      // 301, 302, etc.
+  
+  // For 'socket-handler'
+  socketHandler?: (socket, context) => void | Promise<void>;
+  
+  // TLS options
+  tls?: {
+    mode: 'terminate' | 'passthrough' | 'terminate-and-reencrypt';
+    certificate: 'auto' | { key: string; cert: string };
+  };
+  
+  // WebSocket options
+  websocket?: {
+    enabled: boolean;
+    pingInterval?: number;
+    pingTimeout?: number;
+  };
+}
 ```
 
-## Troubleshooting
-
-### Common Issues
+## 🐛 Troubleshooting
 
-#### Certificate Provisioning
-- Ensure domains are publicly accessible
-- Check firewall rules for port 80 (ACME challenges)
-- Verify DNS resolution
-- Check ACME email configuration
+### Certificate Issues
+- ✅ Ensure domain points to your server
+- ✅ Port 80 must be accessible for ACME challenges
+- ✅ Check DNS propagation with `nslookup`
+- ✅ Verify email in ACME configuration
 
-#### Connection Issues
-- Verify route matching criteria
-- Check security rules (IP lists, authentication)
-- Ensure target servers are accessible
-- Check for port conflicts
+### Connection Problems
+- ✅ Check route priorities (higher = matched first)
+- ✅ Verify security rules aren't blocking
+- ✅ Test with `curl -v` for detailed output
+- ✅ Enable debug mode for verbose logging
 
-#### Performance Issues
-- Consider using NFTables for high-traffic routes
-- Adjust connection pool sizes
-- Enable connection keep-alive
-- Monitor resource usage
+### Performance Tuning
+- ✅ Use NFTables for high-traffic routes
+- ✅ Enable connection pooling
+- ✅ Adjust keep-alive settings
+- ✅ Monitor with built-in metrics
 
 ### Debug Mode
-Enable detailed logging:
 ```typescript
 const proxy = new SmartProxy({
-  debug: true,
+  debug: true,  // Enable verbose logging
   routes: [...]
 });
 ```
 
-### Route Testing
-Test route matching:
-```typescript
-const matchedRoute = proxy.findMatchingRoute({
-  port: 443,
-  domain: 'example.com',
-  path: '/api/users',
-  clientIp: '192.168.1.100'
-});
+## 🚀 Migration from v20.x to v21.x
 
-console.log('Matched route:', matchedRoute?.name);
-```
+No breaking changes! v21.x adds enhanced socket cleanup, improved connection tracking, and better process exit handling.
 
-## Migration Guide
+## 🏆 Best Practices
 
-### From v19.x to v20.x
+1. **📝 Use Helper Functions** - They provide sensible defaults and prevent errors
+2. **🎯 Set Route Priorities** - More specific routes should have higher priority
+3. **🔒 Always Enable Security** - Use IP filtering and rate limiting for public services
+4. **📊 Monitor Performance** - Use metrics to identify bottlenecks
+5. **🔄 Regular Certificate Checks** - Monitor expiration and renewal status
+6. **🛑 Graceful Shutdown** - Always call `proxy.stop()` for clean shutdown
+7. **🎮 Test Your Routes** - Use the route testing utilities before production
 
-The main breaking change is the route action configuration:
-
-**Before (v19.x):**
-```typescript
-{
-  action: {
-    type: 'forward',
-    target: { host: 'localhost', port: 8080 }  // Single target
-  }
-}
-```
-
-**After (v20.x):**
-```typescript
-{
-  action: {
-    type: 'forward',
-    targets: [{ host: 'localhost', port: 8080 }]  // Array of targets
-  }
-}
-```
-
-Helper functions have been updated to use the new format automatically.
-
-## Best Practices
-
-1. **Use Helper Functions**: They provide sensible defaults and reduce configuration errors
-2. **Set Route Priorities**: Higher priority routes are matched first
-3. **Use Specific Matches**: More specific routes should have higher priorities
-4. **Enable Security Features**: Always use IP filtering and rate limiting for public services
-5. **Monitor Performance**: Use debug logging and metrics to identify bottlenecks
-6. **Regular Certificate Checks**: Monitor certificate expiration and renewal
-7. **Graceful Shutdown**: Always call `proxy.stop()` for clean shutdown
-
-## API Reference
+## 📖 API Documentation
 
 ### SmartProxy Class
 
@@ -953,46 +436,56 @@ Helper functions have been updated to use the new format automatically.
 class SmartProxy {
   constructor(options: IRoutedSmartProxyOptions);
   
-  // Lifecycle methods
+  // Lifecycle
   start(): Promise<void>;
   stop(): Promise<void>;
   
-  // Route management
+  // Route Management
   updateRoutes(routes: IRouteConfig[]): Promise<void>;
   addRoute(route: IRouteConfig): Promise<void>;
   removeRoute(routeName: string): Promise<void>;
   findMatchingRoute(context: Partial<IRouteContext>): IRouteConfig | null;
   
-  // Port management
+  // Port Management
   addListeningPort(port: number): Promise<void>;
   removeListeningPort(port: number): Promise<void>;
   getListeningPorts(): number[];
   
-  // Certificate management
+  // Certificate Management
   getCertificateInfo(domain: string): ICertificateInfo | null;
   renewCertificate(domain: string): Promise<void>;
   
-  // Status and monitoring
+  // Monitoring
   getStatus(): IProxyStatus;
   getMetrics(): IProxyMetrics;
 }
 ```
 
-### Route Configuration Types
-
-See the TypeScript definitions in:
-- `ts/proxies/smart-proxy/models/route-types.ts`
-- `ts/proxies/smart-proxy/models/interfaces.ts`
-
-## Contributing
+### Helper Functions
 
-Contributions are welcome! Please follow these guidelines:
+All helper functions are fully typed and documented. Import them from the main package:
 
-1. Fork the repository
-2. Create a feature branch
-3. Write tests for new functionality
-4. Ensure all tests pass
-5. Submit a pull request
+```typescript
+import {
+  createHttpRoute,
+  createHttpsTerminateRoute,
+  createHttpsPassthroughRoute,
+  createHttpToHttpsRedirect,
+  createCompleteHttpsServer,
+  createLoadBalancerRoute,
+  createApiRoute,
+  createWebSocketRoute,
+  createSocketHandlerRoute,
+  createNfTablesRoute,
+  createPortMappingRoute,
+  createDynamicRoute,
+  createApiGatewayRoute,
+  addRateLimiting,
+  addBasicAuth,
+  addJwtAuth,
+  SocketHandlers
+} from '@push.rocks/smartproxy';
+```
 
 ## License and Legal Information