@push.rocks/smartproxy 15.0.2 → 16.0.2

package/readme.md

@@ -105,63 +105,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
@@ -189,9 +212,7 @@ await proxy.start();
 
 // Dynamically add new routes later
 await proxy.addRoutes([
-  createHttpsRoute({
-    domains: 'new-domain.com',
-    target: { host: 'localhost', port: 9000 },
+  createHttpsTerminateRoute('new-domain.com', { host: 'localhost', port: 9000 }, {
     certificate: 'auto'
   })
 ]);
@@ -445,33 +466,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 +500,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 +508,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 +536,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,8 +551,7 @@ 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
    })
@@ -607,19 +622,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 +651,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 +841,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