BREAKING CHANGE(smart-proxy): remove route helper APIs and standardize route configuration on plain route objects

2026-03-26 20:45:41 +00:00
parent 47140e5403
commit 788ccea81e
32 changed files with 1159 additions and 2840 deletions
--- a/readme.md
+++ b/readme.md
@@ -44,7 +44,7 @@ Whether you're building microservices, deploying edge infrastructure, proxying U
 Get up and running in 30 seconds:

 ```typescript
-import { SmartProxy, createCompleteHttpsServer } from '@push.rocks/smartproxy';
+import { SmartProxy, SocketHandlers } from '@push.rocks/smartproxy';

 // Create a proxy with automatic HTTPS
 const proxy = new SmartProxy({
@@ -53,13 +53,25 @@ const proxy = new SmartProxy({
    useProduction: true
  },
  routes: [
-    // Complete HTTPS setup in one call! ✨
-    ...createCompleteHttpsServer('app.example.com', {
-      host: 'localhost',
-      port: 3000
-    }, {
-      certificate: 'auto'  // Automatic Let's Encrypt cert 🎩
-    })
+    // HTTPS route with automatic Let's Encrypt cert
+    {
+      name: 'https-app',
+      match: { ports: 443, domains: 'app.example.com' },
+      action: {
+        type: 'forward',
+        targets: [{ host: 'localhost', port: 3000 }],
+        tls: { mode: 'terminate', certificate: 'auto' }
+      }
+    },
+    // HTTP → HTTPS redirect
+    {
+      name: 'http-redirect',
+      match: { ports: 80, domains: 'app.example.com' },
+      action: {
+        type: 'socket-handler',
+        socketHandler: SocketHandlers.httpRedirect('https://{domain}:443{path}', 301)
+      }
+    }
  ]
 });

@@ -111,31 +123,38 @@ SmartProxy supports three TLS handling modes:
 ### 🌐 HTTP to HTTPS Redirect

 ```typescript
-import { SmartProxy, createHttpToHttpsRedirect } from '@push.rocks/smartproxy';
+import { SmartProxy, SocketHandlers } from '@push.rocks/smartproxy';

 const proxy = new SmartProxy({
-  routes: [
-    createHttpToHttpsRedirect(['example.com', '*.example.com'])
-  ]
+  routes: [{
+    name: 'http-to-https',
+    match: { ports: 80, domains: ['example.com', '*.example.com'] },
+    action: {
+      type: 'socket-handler',
+      socketHandler: SocketHandlers.httpRedirect('https://{domain}:443{path}', 301)
+    }
+  }]
 });
 ```

 ### ⚖️ Load Balancer with Health Checks

 ```typescript
-import { SmartProxy, createLoadBalancerRoute } from '@push.rocks/smartproxy';
+import { SmartProxy } from '@push.rocks/smartproxy';

 const proxy = new SmartProxy({
-  routes: [
-    createLoadBalancerRoute(
-      'app.example.com',
-      [
+  routes: [{
+    name: 'load-balancer',
+    match: { ports: 443, domains: 'app.example.com' },
+    action: {
+      type: 'forward',
+      targets: [
        { host: 'server1.internal', port: 8080 },
        { host: 'server2.internal', port: 8080 },
        { host: 'server3.internal', port: 8080 }
      ],
-      {
-        tls: { mode: 'terminate', certificate: 'auto' },
+      tls: { mode: 'terminate', certificate: 'auto' },
+      loadBalancing: {
        algorithm: 'round-robin',
        healthCheck: {
          path: '/health',
@@ -145,57 +164,68 @@ const proxy = new SmartProxy({
          healthyThreshold: 2
        }
      }
-    )
-  ]
+    }
+  }]
 });
 ```

 ### 🔌 WebSocket Proxy

 ```typescript
-import { SmartProxy, createWebSocketRoute } from '@push.rocks/smartproxy';
+import { SmartProxy } from '@push.rocks/smartproxy';

 const proxy = new SmartProxy({
-  routes: [
-    createWebSocketRoute(
-      'ws.example.com',
-      { host: 'websocket-server', port: 8080 },
-      {
-        path: '/socket',
-        useTls: true,
-        certificate: 'auto',
+  routes: [{
+    name: 'websocket',
+    match: { ports: 443, domains: 'ws.example.com', path: '/socket' },
+    priority: 100,
+    action: {
+      type: 'forward',
+      targets: [{ host: 'websocket-server', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      websocket: {
+        enabled: true,
        pingInterval: 30000,
        pingTimeout: 10000
      }
-    )
-  ]
+    }
+  }]
 });
 ```

 ### 🚦 API Gateway with Rate Limiting

 ```typescript
-import { SmartProxy, createApiGatewayRoute, addRateLimiting } from '@push.rocks/smartproxy';
+import { SmartProxy } from '@push.rocks/smartproxy';

-let apiRoute = createApiGatewayRoute(
-  'api.example.com',
-  '/api',
-  { host: 'api-backend', port: 8080 },
-  {
-    useTls: true,
-    certificate: 'auto',
-    addCorsHeaders: true
-  }
-);
-
-// Add rate limiting — 100 requests per minute per IP
-apiRoute = addRateLimiting(apiRoute, {
-  maxRequests: 100,
-  window: 60,
-  keyBy: 'ip'
+const proxy = new SmartProxy({
+  routes: [{
+    name: 'api-gateway',
+    match: { ports: 443, domains: 'api.example.com', path: '/api/*' },
+    priority: 100,
+    action: {
+      type: 'forward',
+      targets: [{ host: 'api-backend', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' }
+    },
+    headers: {
+      response: {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        'Access-Control-Max-Age': '86400'
+      }
+    },
+    security: {
+      rateLimit: {
+        enabled: true,
+        maxRequests: 100,
+        window: 60,
+        keyBy: 'ip'
+      }
+    }
+  }]
 });
-
-const proxy = new SmartProxy({ routes: [apiRoute] });
 ```

 ### 🎮 Custom Protocol Handler (TCP)
@@ -203,36 +233,40 @@ const proxy = new SmartProxy({ routes: [apiRoute] });
 SmartProxy lets you implement any protocol with full socket control. Routes with JavaScript socket handlers are automatically relayed from the Rust engine back to your TypeScript code:

 ```typescript
-import { SmartProxy, createSocketHandlerRoute, SocketHandlers } from '@push.rocks/smartproxy';
+import { SmartProxy, SocketHandlers } from '@push.rocks/smartproxy';

-// Use pre-built handlers
-const echoRoute = createSocketHandlerRoute(
-  'echo.example.com',
-  7777,
-  SocketHandlers.echo
-);
+const proxy = new SmartProxy({
+  routes: [
+    // Use pre-built handlers
+    {
+      name: 'echo-server',
+      match: { ports: 7777, domains: 'echo.example.com' },
+      action: { type: 'socket-handler', socketHandler: SocketHandlers.echo }
+    },
+    // Or create your own custom protocol
+    {
+      name: 'custom-protocol',
+      match: { ports: 9999, domains: 'custom.example.com' },
+      action: {
+        type: 'socket-handler',
+        socketHandler: async (socket) => {
+          console.log(`New connection on custom protocol`);
+          socket.write('Welcome to my custom protocol!\n');

-// Or create your own custom protocol
-const customRoute = createSocketHandlerRoute(
-  'custom.example.com',
-  9999,
-  async (socket) => {
-    console.log(`New connection on custom protocol`);
-    socket.write('Welcome to my custom protocol!\n');
-
-    socket.on('data', (data) => {
-      const command = data.toString().trim();
-      switch (command) {
-        case 'PING': socket.write('PONG\n'); break;
-        case 'TIME': socket.write(`${new Date().toISOString()}\n`); break;
-        case 'QUIT': socket.end('Goodbye!\n'); break;
-        default: socket.write(`Unknown: ${command}\n`);
+          socket.on('data', (data) => {
+            const command = data.toString().trim();
+            switch (command) {
+              case 'PING': socket.write('PONG\n'); break;
+              case 'TIME': socket.write(`${new Date().toISOString()}\n`); break;
+              case 'QUIT': socket.end('Goodbye!\n'); break;
+              default: socket.write(`Unknown: ${command}\n`);
+            }
+          });
+        }
      }
-    });
-  }
-);
-
-const proxy = new SmartProxy({ routes: [echoRoute, customRoute] });
+    }
+  ]
+});
 ```

 **Pre-built Socket Handlers:**
@@ -387,20 +421,23 @@ const dualStackRoute: IRouteConfig = {
 For ultra-low latency on Linux, use kernel-level forwarding via [`@push.rocks/smartnftables`](https://code.foss.global/push.rocks/smartnftables) (requires root):

 ```typescript
-import { SmartProxy, createNfTablesTerminateRoute } from '@push.rocks/smartproxy';
+import { SmartProxy } from '@push.rocks/smartproxy';

 const proxy = new SmartProxy({
-  routes: [
-    createNfTablesTerminateRoute(
-      'fast.example.com',
-      { host: 'backend', port: 8080 },
-      {
-        ports: 443,
-        certificate: 'auto',
+  routes: [{
+    name: 'nftables-fast',
+    match: { ports: 443, domains: 'fast.example.com' },
+    action: {
+      type: 'forward',
+      forwardingEngine: 'nftables',
+      targets: [{ host: 'backend', port: 8080 }],
+      tls: { mode: 'terminate', certificate: 'auto' },
+      nftables: {
+        protocol: 'tcp',
        preserveSourceIP: true  // Backend sees real client IP
      }
-    )
-  ]
+    }
+  }]
 });
 ```

@@ -409,15 +446,18 @@ const proxy = new SmartProxy({
 Forward encrypted traffic to backends without terminating TLS — the proxy routes based on the SNI hostname alone:

 ```typescript
-import { SmartProxy, createHttpsPassthroughRoute } from '@push.rocks/smartproxy';
+import { SmartProxy } from '@push.rocks/smartproxy';

 const proxy = new SmartProxy({
-  routes: [
-    createHttpsPassthroughRoute('secure.example.com', {
-      host: 'backend-that-handles-tls',
-      port: 8443
-    })
-  ]
+  routes: [{
+    name: 'sni-passthrough',
+    match: { ports: 443, domains: 'secure.example.com' },
+    action: {
+      type: 'forward',
+      targets: [{ host: 'backend-that-handles-tls', port: 8443 }],
+      tls: { mode: 'passthrough' }
+    }
+  }]
 });
 ```

@@ -524,15 +564,7 @@ Comprehensive per-route security options:
 }
 ```

-**Security modifier helpers** let you add security to any existing route:
-
-```typescript
-import { addRateLimiting, addBasicAuth, addJwtAuth } from '@push.rocks/smartproxy';
-
-let route = createHttpsTerminateRoute('api.example.com', { host: 'backend', port: 8080 });
-route = addRateLimiting(route, { maxRequests: 100, window: 60, keyBy: 'ip' });
-route = addBasicAuth(route, { users: [{ username: 'admin', password: 'secret' }] });
-```
+Security options are configured directly on each route's `security` property — no separate helpers needed.

 ### 📊 Runtime Management

@@ -712,7 +744,7 @@ SmartProxy uses a hybrid **Rust + TypeScript** architecture:
 ```

 - **Rust Engine** handles all networking: TCP, UDP, TLS, QUIC, HTTP proxying, connection management, security, and metrics
- **TypeScript** provides the npm API, configuration types, route helpers, validation, and handler callbacks
+- **TypeScript** provides the npm API, configuration types, validation, and handler callbacks
 - **NFTables** managed by [`@push.rocks/smartnftables`](https://code.foss.global/push.rocks/smartnftables) — kernel-level DNAT/SNAT forwarding, firewall rules, and rate limiting via the `nft` CLI
 - **IPC** — The TypeScript wrapper uses JSON commands/events over stdin/stdout to communicate with the Rust binary
 - **Socket/Datagram Relay** — Unix domain socket servers for routes requiring TypeScript-side handling (socket handlers, datagram handlers, dynamic host/port functions)
@@ -858,47 +890,13 @@ interface IRouteQuic {
 }
 ```

-## 🛠️ Helper Functions Reference
-
-All helpers are fully typed and return `IRouteConfig` or `IRouteConfig[]`:
+## 🛠️ Exports Reference

 ```typescript
 import {
-  // HTTP/HTTPS
-  createHttpRoute,                 // Plain HTTP route
-  createHttpsTerminateRoute,       // HTTPS with TLS termination
-  createHttpsPassthroughRoute,     // SNI passthrough (no termination)
-  createHttpToHttpsRedirect,       // HTTP → HTTPS redirect
-  createCompleteHttpsServer,       // HTTPS + redirect combo (returns IRouteConfig[])
-
-  // Load Balancing
-  createLoadBalancerRoute,         // Multi-backend with health checks
-  createSmartLoadBalancer,         // Dynamic domain-based backend selection
-
-  // API & WebSocket
-  createApiRoute,                  // API route with path matching
-  createApiGatewayRoute,           // API gateway with CORS
-  createWebSocketRoute,            // WebSocket-enabled route
-
-  // Custom Protocols
-  createSocketHandlerRoute,        // Custom TCP socket handler
-  SocketHandlers,                  // Pre-built handlers (echo, proxy, block, etc.)
-
-  // NFTables (Linux, requires root)
-  createNfTablesRoute,             // Kernel-level packet forwarding
-  createNfTablesTerminateRoute,    // NFTables + TLS termination
-  createCompleteNfTablesHttpsServer, // NFTables HTTPS + redirect combo
-
-  // Dynamic Routing
-  createPortMappingRoute,          // Port mapping with context
-  createOffsetPortMappingRoute,    // Simple port offset
-  createDynamicRoute,              // Dynamic host/port via functions
-  createPortOffset,                // Port offset factory
-
-  // Security Modifiers
-  addRateLimiting,                 // Add rate limiting to any route
-  addBasicAuth,                    // Add basic auth to any route
-  addJwtAuth,                      // Add JWT auth to any route
+  // Core
+  SmartProxy,                      // Main proxy class
+  SocketHandlers,                  // Pre-built socket handlers (echo, proxy, block, httpRedirect, httpServer, etc.)

  // Route Utilities
  mergeRouteConfigs,               // Deep-merge two route configs
@@ -910,7 +908,7 @@ import {
 } from '@push.rocks/smartproxy';
 ```

-> **Tip:** For UDP datagram handler routes or QUIC/HTTP3 routes, construct `IRouteConfig` objects directly — there are no helper functions for these yet. See the [UDP Datagram Handler](#-udp-datagram-handler) and [QUIC / HTTP3 Forwarding](#-quic--http3-forwarding) examples above.
+All routes are configured as plain `IRouteConfig` objects with `match` and `action` properties — see the examples throughout this document.

 ## 📖 API Documentation