@push.rocks/smartproxy 15.0.2 → 16.0.3

package/readme.md

@@ -7,6 +7,7 @@ A unified high-performance proxy toolkit for Node.js, with **SmartProxy** as the
 - **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 (with TLS modes), redirect, or block traffic
+- **Dynamic Port Management**: Add or remove listening ports at runtime without restart
 - **Security Features**: IP allowlists, connection limits, timeouts, and more
 
 ## Project Architecture Overview
@@ -105,63 +106,86 @@ Install via npm:
 npm install @push.rocks/smartproxy
 ```
 
-## Quick Start with SmartProxy v14.0.0
+## Quick Start with SmartProxy
 
-SmartProxy v14.0.0 introduces a new unified route-based configuration system that makes configuring proxies more flexible and intuitive.
+SmartProxy v16.0.0 continues the evolution of the unified route-based configuration system making your proxy setup more flexible and intuitive with improved helper functions.
 
 ```typescript
-import { 
-  SmartProxy, 
-  createHttpRoute, 
-  createHttpsRoute, 
-  createPassthroughRoute, 
-  createHttpToHttpsRedirect
+import {
+  SmartProxy,
+  createHttpRoute,
+  createHttpsTerminateRoute,
+  createHttpsPassthroughRoute,
+  createHttpToHttpsRedirect,
+  createCompleteHttpsServer,
+  createLoadBalancerRoute,
+  createStaticFileRoute,
+  createApiRoute,
+  createWebSocketRoute,
+  createSecurityConfig
 } from '@push.rocks/smartproxy';
 
 // Create a new SmartProxy instance with route-based configuration
 const proxy = new SmartProxy({
-  // Define all your routing rules in one array
+  // Define all your routing rules in a single array
   routes: [
     // Basic HTTP route - forward traffic from port 80 to internal service
-    createHttpRoute({
-      ports: 80,
-      domains: 'api.example.com',
-      target: { host: 'localhost', port: 3000 }
-    }),
+    createHttpRoute('api.example.com', { host: 'localhost', port: 3000 }),
 
     // HTTPS route with TLS termination and automatic certificates
-    createHttpsRoute({
-      ports: 443,
-      domains: 'secure.example.com',
-      target: { host: 'localhost', port: 8080 },
+    createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
       certificate: 'auto'  // Use Let's Encrypt
     }),
 
     // HTTPS passthrough for legacy systems
-    createPassthroughRoute({
-      ports: 443,
-      domains: 'legacy.example.com',
-      target: { host: '192.168.1.10', port: 443 }
+    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'
     }),
 
-    // Redirect HTTP to HTTPS
-    createHttpToHttpsRedirect({
-      domains: ['example.com', '*.example.com']
+    // API route with CORS headers
+    createApiRoute('api.service.com', '/v1', { host: 'api-backend', port: 8081 }, {
+      useTls: true,
+      certificate: 'auto',
+      addCorsHeaders: true
     }),
 
-    // Complex load balancer setup with security controls
-    createLoadBalancerRoute({
-      domains: ['app.example.com'],
-      targets: ['192.168.1.10', '192.168.1.11', '192.168.1.12'],
-      targetPort: 8080,
-      tlsMode: 'terminate',
+    // WebSocket route for real-time communication
+    createWebSocketRoute('ws.example.com', '/socket', { host: 'socket-server', port: 8082 }, {
+      useTls: true,
       certificate: 'auto',
-      security: {
-        allowedIps: ['10.0.0.*', '192.168.1.*'],
-        blockedIps: ['1.2.3.4'],
-        maxConnections: 1000
+      pingInterval: 30000
+    }),
+
+    // Static file server for web assets
+    createStaticFileRoute('static.example.com', '/var/www/html', {
+      serveOnHttps: true,
+      certificate: 'auto',
+      indexFiles: ['index.html', 'index.htm', 'default.html']
+    }),
+
+    // 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'
+        },
+        security: createSecurityConfig({
+          allowedIps: ['10.0.0.*', '192.168.1.*'],
+          blockedIps: ['1.2.3.4'],
+          maxConnections: 1000
+        })
       }
-    })
+    )
   ],
 
   // Global settings that apply to all routes
@@ -188,14 +212,18 @@ proxy.on('certificate', evt => {
 await proxy.start();
 
 // Dynamically add new routes later
-await proxy.addRoutes([
-  createHttpsRoute({
-    domains: 'new-domain.com',
-    target: { host: 'localhost', port: 9000 },
+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();
 ```
@@ -445,33 +473,33 @@ const route = {
   name: 'Web Server'
 };
 
-// Use the helper function:
-const route = createHttpRoute({
-  domains: 'example.com',
-  target: { host: 'localhost', port: 8080 },
+// Use the helper function for cleaner syntax:
+const route = createHttpRoute('example.com', { host: 'localhost', port: 8080 }, {
   name: 'Web Server'
 });
 ```
 
 Available helper functions:
-- `createRoute()` - Basic function to create any route configuration
 - `createHttpRoute()` - Create an HTTP forwarding route
-- `createHttpsRoute()` - Create an HTTPS route with TLS termination
-- `createPassthroughRoute()` - Create an HTTPS passthrough route
-- `createRedirectRoute()` - Create a generic redirect route
+- `createHttpsTerminateRoute()` - Create an HTTPS route with TLS termination
+- `createHttpsPassthroughRoute()` - Create an HTTPS passthrough route
 - `createHttpToHttpsRedirect()` - Create an HTTP to HTTPS redirect
+- `createCompleteHttpsServer()` - Create a complete HTTPS server setup with HTTP redirect
+- `createLoadBalancerRoute()` - Create a route for load balancing across multiple backends
+- `createStaticFileRoute()` - Create a route for serving static files
+- `createApiRoute()` - Create an API route with path matching and CORS support
+- `createWebSocketRoute()` - Create a route for WebSocket connections
+- `createPortRange()` - Helper to create port range configurations
+- `createSecurityConfig()` - Helper to create security configuration objects
 - `createBlockRoute()` - Create a route to block specific traffic
-- `createLoadBalancerRoute()` - Create a route for load balancing
-- `createHttpsServer()` - Create a complete HTTPS server setup with HTTP redirect
+- `createTestRoute()` - Create a test route for debugging and testing
 
 ## What You Can Do with SmartProxy
 
 1. **Route-Based Traffic Management**
    ```typescript
    // Route requests for different domains to different backend servers
-   createHttpsRoute({
-     domains: 'api.example.com',
-     target: { host: 'api-server', port: 3000 },
+   createHttpsTerminateRoute('api.example.com', { host: 'api-server', port: 3000 }, {
      certificate: 'auto'
    })
    ```
@@ -479,9 +507,7 @@ Available helper functions:
 2. **Automatic SSL with Let's Encrypt**
    ```typescript
    // Get and automatically renew certificates
-   createHttpsRoute({
-     domains: 'secure.example.com',
-     target: { host: 'localhost', port: 8080 },
+   createHttpsTerminateRoute('secure.example.com', { host: 'localhost', port: 8080 }, {
      certificate: 'auto'
    })
    ```
@@ -489,21 +515,23 @@ Available helper functions:
 3. **Load Balancing**
    ```typescript
    // Distribute traffic across multiple backend servers
-   createLoadBalancerRoute({
-     domains: 'app.example.com',
-     targets: ['10.0.0.1', '10.0.0.2', '10.0.0.3'],
-     targetPort: 8080,
-     tlsMode: 'terminate',
-     certificate: 'auto'
-   })
+   createLoadBalancerRoute(
+     'app.example.com',
+     ['10.0.0.1', '10.0.0.2', '10.0.0.3'],
+     8080,
+     {
+       tls: {
+         mode: 'terminate',
+         certificate: 'auto'
+       }
+     }
+   )
    ```
 
 4. **Security Controls**
    ```typescript
    // Restrict access based on IP addresses
-   createHttpsRoute({
-     domains: 'admin.example.com',
-     target: { host: 'localhost', port: 8080 },
+   createHttpsTerminateRoute('admin.example.com', { host: 'localhost', port: 8080 }, {
      certificate: 'auto',
      security: {
        allowedIps: ['10.0.0.*', '192.168.1.*'],
@@ -515,19 +543,14 @@ Available helper functions:
 5. **Wildcard Domains**
    ```typescript
    // Handle all subdomains with one config
-   createPassthroughRoute({
-     domains: ['example.com', '*.example.com'],
-     target: { host: 'backend-server', port: 443 }
-   })
+   createHttpsPassthroughRoute(['example.com', '*.example.com'], { host: 'backend-server', port: 443 })
    ```
 
 6. **Path-Based Routing**
    ```typescript
    // Route based on URL path
-   createHttpsRoute({
-     domains: 'example.com',
-     path: '/api/*',
-     target: { host: 'api-server', port: 3000 },
+   createApiRoute('example.com', '/api', { host: 'api-server', port: 3000 }, {
+     useTls: true,
      certificate: 'auto'
    })
    ```
@@ -535,19 +558,43 @@ Available helper functions:
 7. **Block Malicious Traffic**
    ```typescript
    // Block traffic from specific IPs
-   createBlockRoute({
-     ports: [80, 443],
+   createBlockRoute([80, 443], {
      clientIp: ['1.2.3.*', '5.6.7.*'],
      priority: 1000  // High priority to ensure blocking
    })
    ```
 
+8. **Dynamic Port Management**
+   ```typescript
+   // Start the proxy with initial configuration
+   const proxy = new SmartProxy({
+     routes: [
+       createHttpRoute('example.com', { host: 'localhost', port: 8080 })
+     ]
+   });
+   await proxy.start();
+
+   // Dynamically add a new port listener
+   await proxy.addListeningPort(8081);
+
+   // Add a route for the new port
+   const currentRoutes = proxy.settings.routes;
+   const newRoute = createHttpRoute('api.example.com', { host: 'api-server', port: 3000 });
+   newRoute.match.ports = 8081;  // Override the default port
+
+   // Update routes - will automatically sync port listeners
+   await proxy.updateRoutes([...currentRoutes, newRoute]);
+
+   // Later, remove a port listener when needed
+   await proxy.removeListeningPort(8081);
+   ```
+
 ## Other Components
 
 While SmartProxy provides a unified API for most needs, you can also use individual components:
 
 ### NetworkProxy
-For HTTP/HTTPS reverse proxy with TLS termination and WebSocket support:
+For HTTP/HTTPS reverse proxy with TLS termination and WebSocket support. Now with native route-based configuration support:
 
 ```typescript
 import { NetworkProxy } from '@push.rocks/smartproxy';
@@ -555,9 +602,49 @@ import * as fs from 'fs';
 
 const proxy = new NetworkProxy({ port: 443 });
 await proxy.start();
+
+// Modern route-based configuration (recommended)
+await proxy.updateRouteConfigs([
+  {
+    match: {
+      ports: 443,
+      domains: 'example.com'
+    },
+    action: {
+      type: 'forward',
+      target: {
+        host: '127.0.0.1',
+        port: 3000
+      },
+      tls: {
+        mode: 'terminate',
+        certificate: {
+          cert: fs.readFileSync('cert.pem', 'utf8'),
+          key: fs.readFileSync('key.pem', 'utf8')
+        }
+      },
+      advanced: {
+        headers: {
+          'X-Forwarded-By': 'NetworkProxy'
+        },
+        urlRewrite: {
+          pattern: '^/old/(.*)$',
+          target: '/new/$1',
+          flags: 'g'
+        }
+      },
+      websocket: {
+        enabled: true,
+        pingInterval: 30000
+      }
+    }
+  }
+]);
+
+// Legacy configuration (for backward compatibility)
 await proxy.updateProxyConfigs([
   {
-    hostName: 'example.com',
+    hostName: 'legacy.example.com',
     destinationIps: ['127.0.0.1'],
     destinationPorts: [3000],
     publicKey: fs.readFileSync('cert.pem', 'utf8'),
@@ -607,19 +694,20 @@ const redirect = new SslRedirect(80);
 await redirect.start();
 ```
 
-## Migration from v13.x to v14.0.0
+## Migration to v16.0.0
 
-Version 14.0.0 introduces a breaking change with the new route-based configuration system:
+Version 16.0.0 completes the migration to a fully unified route-based configuration system with improved helper functions:
 
 ### Key Changes
 
-1. **Configuration Structure**: The configuration now uses the match/action pattern instead of the old domain-based and port-based approach
-2. **SmartProxy Options**: Now takes an array of route configurations instead of `domainConfigs` and port ranges
-3. **Helper Functions**: New helper functions have been introduced to simplify configuration
+1. **Pure Route-Based API**: The configuration now exclusively uses the match/action pattern with no legacy interfaces
+2. **Improved Helper Functions**: Enhanced helper functions with cleaner parameter signatures
+3. **Removed Legacy Support**: Legacy domain-based APIs have been completely removed
+4. **More Route Pattern Helpers**: Additional helper functions for common routing patterns
 
 ### Migration Example
 
-**v13.x Configuration**:
+**Legacy Configuration (pre-v14)**:
 ```typescript
 import { SmartProxy, createDomainConfig, httpOnly, tlsTerminateToHttp } from '@push.rocks/smartproxy';
 
@@ -635,29 +723,48 @@ const proxy = new SmartProxy({
 });
 ```
 
-**v14.0.0 Configuration**:
+**Current Configuration (v16.0.0)**:
 ```typescript
-import { SmartProxy, createHttpsRoute } from '@push.rocks/smartproxy';
+import { SmartProxy, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
 
 const proxy = new SmartProxy({
   routes: [
-    createHttpsRoute({
-      ports: 443,
-      domains: 'example.com',
-      target: { host: 'localhost', port: 8080 },
+    createHttpsTerminateRoute('example.com', { host: 'localhost', port: 8080 }, {
       certificate: 'auto'
     })
-  ]
+  ],
+  acme: {
+    enabled: true,
+    useProduction: true
+  }
 });
 ```
 
-### Migration Steps
+### Migration from v14.x/v15.x to v16.0.0
+
+If you're already using route-based configuration, update your helper function calls:
+
+```typescript
+// Old v14.x/v15.x style:
+createHttpsRoute({
+  domains: 'example.com',
+  target: { host: 'localhost', port: 8080 },
+  certificate: 'auto'
+})
+
+// New v16.0.0 style:
+createHttpsTerminateRoute('example.com', { host: 'localhost', port: 8080 }, {
+  certificate: 'auto'
+})
+```
+
+### Complete Migration Steps
 
-1. Replace `domainConfigs` with an array of route configurations using `routes`
-2. Convert each domain configuration to use the new helper functions
-3. Update any code that uses `updateDomainConfigs()` to use `addRoutes()` or `updateRoutes()`
-4. For port-only configurations, create route configurations with port matching only
-5. For SNI-based routing, SNI is now automatically enabled when needed
+1. Replace any remaining `domainConfigs` with route-based configuration using the `routes` array
+2. Update helper function calls to use the newer parameter format (domain first, target second, options third)
+3. Use the new specific helper functions (e.g., `createHttpsTerminateRoute` instead of `createHttpsRoute`)
+4. Update any code that uses `updateDomainConfigs()` to use `addRoutes()` or `updateRoutes()`
+5. For port-only configurations, create route configurations with port matching only
 
 ## Architecture & Flow Diagrams
 
@@ -806,33 +913,26 @@ The SmartProxy component with route-based configuration offers a clean, unified
 Create a flexible API gateway to route traffic to different microservices based on domain and path:
 
 ```typescript
-import { SmartProxy, createHttpsRoute } from '@push.rocks/smartproxy';
+import { SmartProxy, createApiRoute, createHttpsTerminateRoute } from '@push.rocks/smartproxy';
 
 const apiGateway = new SmartProxy({
   routes: [
     // Users API
-    createHttpsRoute({
-      ports: 443,
-      domains: 'api.example.com',
-      path: '/users/*',
-      target: { host: 'users-service', port: 3000 },
-      certificate: 'auto'
+    createApiRoute('api.example.com', '/users', { host: 'users-service', port: 3000 }, {
+      useTls: true,
+      certificate: 'auto',
+      addCorsHeaders: true
     }),
 
     // Products API
-    createHttpsRoute({
-      ports: 443,
-      domains: 'api.example.com',
-      path: '/products/*',
-      target: { host: 'products-service', port: 3001 },
-      certificate: 'auto'
+    createApiRoute('api.example.com', '/products', { host: 'products-service', port: 3001 }, {
+      useTls: true,
+      certificate: 'auto',
+      addCorsHeaders: true
     }),
 
     // Admin dashboard with extra security
-    createHttpsRoute({
-      ports: 443,
-      domains: 'admin.example.com',
-      target: { host: 'admin-dashboard', port: 8080 },
+    createHttpsTerminateRoute('admin.example.com', { host: 'admin-dashboard', port: 8080 }, {
       certificate: 'auto',
       security: {
         allowedIps: ['10.0.0.*', '192.168.1.*'] // Only allow internal network
@@ -1056,18 +1156,34 @@ createRedirectRoute({
 - Socket opts: `noDelay`, `keepAlive`, `enableKeepAliveProbes`
 - `certProvisionFunction` (callback) - Custom certificate provisioning
 
+#### SmartProxy Dynamic Port Management Methods
+- `async addListeningPort(port: number)` - Add a new port listener without changing routes
+- `async removeListeningPort(port: number)` - Remove a port listener without changing routes
+- `getListeningPorts()` - Get all ports currently being listened on
+- `async updateRoutes(routes: IRouteConfig[])` - Update routes and automatically adjust port listeners
+
 ### NetworkProxy (INetworkProxyOptions)
-- `port` (number, required)
-- `backendProtocol` ('http1'|'http2', default 'http1')
-- `maxConnections` (number, default 10000)
-- `keepAliveTimeout` (ms, default 120000)
-- `headersTimeout` (ms, default 60000)
-- `cors` (object)
-- `connectionPoolSize` (number, default 50)
-- `logLevel` ('error'|'warn'|'info'|'debug')
-- `acme` (IAcmeOptions)
-- `useExternalPort80Handler` (boolean)
-- `portProxyIntegration` (boolean)
+- `port` (number, required) - Main port to listen on
+- `backendProtocol` ('http1'|'http2', default 'http1') - Protocol to use with backend servers
+- `maxConnections` (number, default 10000) - Maximum concurrent connections
+- `keepAliveTimeout` (ms, default 120000) - Connection keep-alive timeout
+- `headersTimeout` (ms, default 60000) - Timeout for receiving complete headers
+- `cors` (object) - Cross-Origin Resource Sharing configuration
+- `connectionPoolSize` (number, default 50) - Size of the connection pool for backend servers
+- `logLevel` ('error'|'warn'|'info'|'debug') - Logging verbosity level
+- `acme` (IAcmeOptions) - ACME certificate configuration
+- `useExternalPort80Handler` (boolean) - Use external port 80 handler for ACME challenges
+- `portProxyIntegration` (boolean) - Integration with other proxies
+
+#### NetworkProxy Enhanced Features
+NetworkProxy now supports full route-based configuration including:
+- Advanced request and response header manipulation
+- URL rewriting with RegExp pattern matching
+- Template variable resolution for dynamic values (e.g. `{domain}`, `{clientIp}`)
+- Function-based dynamic target resolution
+- Security features (IP filtering, rate limiting, authentication)
+- WebSocket configuration with path rewriting, custom headers, ping control, and size limits
+- Context-aware CORS configuration
 
 ### Port80Handler (IAcmeOptions)
 - `enabled` (boolean, default true)